API Access

The Dimensions CRIS API is subscription-only, so your Dimensions account needs to be activated for this service and subject to restrictions on use.

Getting an API Key

Once you have API access, you’ll be able to generate a new API KEY by going to the CRIS API homepage https://cris-api.dimensions.ai/.

Querying the API

Querying the Dimensions API always involves two steps:

Sending your credentials (key) to the authentication url, in order to retrieve a query token.
Sending the token and a DSL query to the query url, in order to retrieve JSON data.

Important

The Dimensions CRIS API is limited to 30 requests per IP address per minute. The query token is valid for around 2 hours so it should be reobtained when it expires.

CURL Example

This example shows a minimal way to query the API from the command-line. This should be easily transferable to any other programming language or environment.

To obtain Access token, send a GET request to token endpoint with the API key as a query parameter

export DSL_TOKEN="$(curl -X GET "https://cris-api.dimensions.ai/v3/token?api_key=xxx")"

To query the API, make a POST request. The token is valid for one hour and needs to be refreshed then.

curl -X POST https://cris-api.dimensions.ai/v3/api/query -H "authorization: Bearer $DSL_TOKEN" -d 'search publications return publications'

Python Example

This example shows a minimal way to query the API from Python.

import requests

#   Your access credentials
key = "your cris-api key"

#   Send credentials to login url to retrieve token. Raise
#   an error, if the return code indicates a problem.
resp = requests.get("https://cris-api.dimensions.ai/v3/token?api_key="+key)
resp.raise_for_status()

#   Create http header using the generated token.
headers = {
    'Authorization': "Bearer " + resp.text
}

#   Execute DSL query.
resp = requests.post(
    'https://cris-api.dimensions.ai/v3/api/query',
    data='search publications for "graphene" return publications'.encode(),
    headers=headers)

#   Display raw result
print(resp.json())

Note

Please note escaping rules in Python. For example, when writing a query with escaped quotes, such as:

search publications for "\"phrase 1\" AND \"phrase 2\""

in Python, it is necessary to escape the backslashes as well, so it would look like:

resp = requests.post(
    '<your-api-url.dimensions.ai>',
    data='search publications for "\\"phrase 1\\" AND \\"phrase 2\\""',
    headers=headers)

Similar escaping rules might apply to other programming languages than Python as well.