Finding academic entities in query expressions

Now that we have a query expression available, we can retrieve a set of academic entities using the Evaluate endpoint. This is a GET request, where we need to specify the attributes we want returned for each entity. We will cover the available attributes later.

We start by creating a query string, as shown in the following code:

    private async void Evaluate(object obj)
    {
        string queryString = $"expr={QueryExpression} &
        attributes=Id,Ti,Y,D,CC,AA.AuN";

        //queryString += "&model=latest";
        //queryString += "&count=10";
        //queryString += "&offset=0";5
        //queryString += "&orderby=name:asc";

The parameters we can add are described in the following table:

Parameter	Description
expr (required)	This is the query expression found in the Interpret call.
attributes (optional)	This is a comma-separated list of attributes to be included in the response. Each attribute is case-sensitive.
model (optional)	This is the model you wish to use for a query. This defaults to the latest model.
count (optional)	This is the number of entities to return.
offset (optional)	This is the index of the first result to return; it can be useful for pagination purposes.
orderby (optional)	This specifies the order in which to sort the entities.

Note that, while the attributes parameter is optional, you should specify which attributes you want. If none are specified, only the entity ID is returned.

We call the API, as follows:

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

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

As this is a GET request, we do not need any request bodies. With a successful call, we expect an EvaluateResponse object in return. This is a data contract, which will be deserialized from the JSON response.

A successful response will give a JSON response like the following code (depending on the attributes specified):

    {
        "expr": "Composite(AA.AuN=='jaime teevan')",
        "entities": [
        {
            "prob": 2.266e-007,
            "Ti": "personalizing search via automated analysis of interests and 
            activities",
            "Y": 2005,
            "CC": 372,
            "AA": [
            {
                "AuN": "jaime teevan",
                "AuId": 1968481722
            },
            {
                "AuN": "susan t dumais",
                "AuId": 676500258
            },
            {
                "AuN": "eric horvitz",
                "AuId": 1470530979
            }]
        }]
    }

The response contains the query expression we used. It also contains an array of entities. Each item in this array will contain the probability of it being correct. It will also contain all the attributes that we specified, in the form of either string or numeric values. It can also be in the form of objects, which we will need to have data contracts for.

For our request, we specified some attributes. These were the entity ID, title, year and date of publication, citation count, and author name. Knowing these attributes, we can use the following code to output the result:

    StringBuilder sb = new StringBuilder(); 
    sb.AppendFormat("Expression {0} returned {1} entities\n\n", response.expr,    
    response.entities.Length);

    foreach (Entity entity in response.entities)
    {
        sb.AppendFormat("Paper title: {0}\n\tDate: {1}\n", entity.Ti, entity.D);

        sb.Append("Authors:\n");
        foreach (AA author in entity.AA)
        {
            sb.AppendFormat("\t{0}\n", author.AuN);
        }

        sb.Append("\n");
    } 
    Results = sb.ToString();

A successful call can give the following output:

Any error responses will produce response codes, as described previously.