API Access

A web API endpoint for executing DSL queries is available. The Python script below illustrates how to make a DSL query using the web API.

Note

The Dimensions Analytics API is limited to 30 requests per IP address per minute.

Python : raw access

The following code snippet shows how to connect to the Dimensions API only using Python’s requests library.

import requests

#   The credentials to be used
login = {
    'username': 'your username',
    'password': 'your password'
    # NOTE if you have an API key, comment the two lines above and use this line instead:
    # 'key': "your API key"
}

#   Send credentials to login url to retrieve token. Raise
#   an error, if the return code indicates a problem.
#   Please use the URL of the system you'd like to access the API
#   in the example below.
resp = requests.post('https://<your-url.dimensions.ai>/api/auth.json', json=login)
resp.raise_for_status()

#   Create http header using the generated token.
headers = {
    'Authorization': "JWT " + resp.json()['token']
}

#   Execute DSL query.
resp = requests.post(
    'https://<your-url.dimensions.ai>/api/dsl.json',
    data='search publications 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(
    'https://<your-url.dimensions.ai>/api/dsl.json',
    data='search publications for "\\"phrase 1\\" AND \\"phrase 2\\""',
    headers=headers)

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

Python : Dimcli

Dimensions API can be accessed from Python using Dimcli Python package as well. Dimcli is a convenient way to connect to, query and analyze the results of Dimensions API.

For further details regarding this package, please consult the Pypi page.

Please see this API LAB cookbook (link to https://api-lab.dimensions.ai/cookbooks/1-getting-started/1-Using-the-Dimcli-library-to-query-the-API.html)

curl + jq

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

export DSL_TOKEN=$(curl https://<your-url.dimensions.ai>/api/auth.json -d '{"username": "your username", "password": "your password"}' -s|jq -r .token)

curl https://<your-url.dimensions.ai>/api/dsl.json -H "Authorization: JWT $DSL_TOKEN" -d 'search publications return publications' -s|jq

Note

Note that jq tool is used to extract a “token” value from the JSON response in the first request. In the second request, jq is used only to pretty print the result so it’s use is optional.

PowerShell

This is an equivalent example of the above CURL + JQ Example, but usable in the PowerShell enivornment.

$DSL_TOKEN = (Invoke-RestMethod -Uri https://<your-url.dimensions.ai>/api/auth.json -Method Post -Body (@{'username' = 'your username'; 'password' = 'your password'} | ConvertTo-JSON)).token

Invoke-RestMethod -Uri https://<your-url.dimensions.ai>/api/dsl.json -Method Post -H @{Authorization = "JWT $DSL_TOKEN"} -Body 'search publications return publications'

Postman

This examples shows how to set up Postman to query the Dimensions API. This can be achieved in two simple steps.

1. Obtaining a JWT token

Make a POST request to https://app.dimensions.ai/api/auth.json with body { "username": "<your-username>", "password": "<your-password>"}

This will return a JWT token, which should be noted as it will be used in the next step.

postman example - part 1

2. Using the token to query the API

Make a new POST request by adding the token to the Headers panel in this format: Authorization : JWT {theToken}.

postman example - part 2

Finally, Compose your query in the request body section:

postman example - part 3

Note

Another approach to get started with Postman is by using the cURL importer.

Third-party libraries

dimensionsR Library

The dimensionsR library is an open-source R-package to gather bibliographic data using the Dimensions API and the DSL.

rdimensions Library

Another client library rdimensions for interacting with the Dimensions API from the R environment.

Sidewall Python Library

The Sidewall library is a Python package providing object classes for Dimensions entities, fetches data incrementally, caches results, copes with rate limits, and more, to make working with Dimensions in Python more natural.