The query expressions that the API uses to evaluate a query are not in a natural language format. To ensure that users can make queries in a natural way, we need to interpret their input.

When calling the Interpret feature of the API, it accepts a query string. This will be returned and formatted to reflect the user intent using academic grammar. In addition, this feature can be called as the user is writing, to provide an interactive experience.

The request is a GET request, as shown in the following code:

    private async void Interpret(object obj)
    {
        var queryString = HttpUtility.ParseQueryString(string.Empty);

        queryString["query"] = InputQuery;
        queryString["complete"] = "1";
        //queryString["count"] = "10";
        //queryString["offset"] = "0";
        //queryString["timeout"] = "1000";
        //queryString["model"] = "latest";

We start the call by creating a queryString variable. The parameters we can input are specified in the following table:

We call the API to get interpretations, as shown in the following code:

    InterpretResponse response = await _webRequest.MakeRequest<object, 
    InterpretResponse>(HttpMethod.Get, $"interpret?{queryString.ToString()}");

    if (response == null || response.interpretations.Length == 0)
        return;

As this is a GET request, we do not need to specify any request bodies. We do, however, expect a result to be serialized into an InterpretResponse object. This is a data contract, containing properties from the result.

A successful call to the API will result in a JSON response, which looks as follows:

    {
        "query": "papers by jaime", "interpretations": [
        {
            "prob": 2.429e-006,
            "parse": "<rule id="#GetPapers"> papers by <attr name="academic#AA.AuN">
            jaime teevan </attr></rule>",
            "rules": [
            {
                "name": "#GetPapers",
                "output": {
                    "type": "query",
                    "value": "Composite(AA.AuN=='jaime teevan')"
                }
            }]
        }]
    }

The result contains the original query. It also contains an array with interpretations. Each item in this array consists of the data shown in the following table:

Create the InterpretResponse data contract based on the preceding JSON output. We are interested in the last data field, rules[x].output.value. This is the query expression string, which we will use to evaluate queries.

When the API call has succeeded, we want to update the ObservableCollection class as to the available query expressions, using the following code:

    ObservableCollection<string> tempList = new ObservableCollection<string>();

    foreach (Interpretation interpretation in response.interpretations)
    {
        foreach (Rule rule in interpretation.rules) {
            tempList.Add(rule.output.value);
        }
    }

    AvailableQueryExpressions = tempList;
    QueryExpression = AvailableQueryExpressions.FirstOrDefault();

We loop through all interpretations, adding the outputvalue from a rule to our AvailableQueryExpressions.

Finally, we set the selected QueryExpression as the first one available. This is just for our own convenience.

A successful test run can generate the following results:

An unsuccessful call will produce an error response code. The response codes that can be generated are as follows: