Important

All Microsoft Academic Services have been officially retired as of December 31st, 2021. We are currently retaining original documentation as-is for educational use, however all information about signing up for services is no longer valid, and support and service (API) links will not function.

Evaluate Method

The evaluate REST API is used to return a set of academic entities based on a query expression.

REST endpoint:

https://api.labs.cognitive.microsoft.com/academic/v1.0/evaluate? 

Request Parameters

Name	Value	Required?	Description
subscription-key	String	Yes	Valid Project Academic Knowledge subscription key
expr	Text string	Yes	A query expression that specifies which entities should be returned.
model	Text string	No	Name of the model that you wish to query. Currently, the value defaults to latest.
attributes	Text string	No default: Id	A comma-delimited list that specifies the attribute values that are included in the response. Attribute names are case-sensitive.
count	Number	No Default: 10	Number of results to return.
offset	Number	No Default: 0	Index of the first result to return.
orderby	Text string	No Default: by decreasing prob	Name of an attribute that is used for sorting the entities. Optionally, ascending/descending can be specified. The format is: name:asc or name:desc.

Response (JSON)

Name	Description
expr	The expr parameter from the request.
entities	An array of 0 or more entities that matched the query expression. Each entity contains a natural log probability value and the values of other requested attributes.
aborted	True if the request timed out.

Example

https://api.labs.cognitive.microsoft.com/academic/v1.0/evaluate?expr=
Composite(AA.AuN=='jaime teevan')&count=2&attributes=Ti,Y,CC,AA.AuN,AA.AuId&subscription-key=<subscription_key>

Typically, an expression will be obtained from a response to the interpret method. But you can also compose query expressions yourself (see Query Expression Syntax).

Using the count and offset parameters, a large number of results may be obtained without sending a single request that results in a huge (and potentially slow) response. In this example, the request used the expression for the first interpretation from the interpret API response as the expr value. The count=2 parameter specifies that 2 entity results are being requested. And the attributes=Ti,Y,CC,AA.AuN,AA.AuId parameter indicates that the title, year, citation count, author name, and author ID are requested for each result. See Entity Attributes for a list of attributes.

{
  "expr": "Composite(AA.AuN=='jaime teevan')",
  "entities": 
  [
    {
      "logprob": -15.08,
      "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
        }
      ]
    },
    {
      "logprob": -15.389,
      "Ti": "the perfect search engine is not enough a study of orienteering behavior in directed search",
      "Y": 2004,
      "CC": 237,
      "AA": [
        {
          "AuN": "jaime teevan",
          "AuId": 1982462162
        },
        {
          "AuN": "christine alvarado",
          "AuId": 2163512453
        },
        {
          "AuN": "mark s ackerman",
          "AuId": 2055132526
        },
        {
          "AuN": "david r karger",
          "AuId": 2012534293
        }
      ]
    }
  ]
}