../../_images/badge-colab.svg ../../_images/badge-github-custom.svg

Verifying Your API Connection

The purpose of this notebook is to verify that you can access the Dimensions Analytics API using Python.

Please note only Dimensions users with an Analytics API subscription can access this service.

Technical prerequisites

This guide assumes that you already have a Python 3 working environment and pip (the python package manager) installed. For more background, see this link.

The only library needed for this exercise is requests, which can be installed as follows

[ ]:

!pip install requests

[ ]:

import requests

[1]:

import datetime
print("==\nCHANGELOG\nThis notebook was last run on %s\n==" % datetime.date.today().strftime('%b %d, %Y'))

==
CHANGELOG
This notebook was last run on Jan 24, 2022
==

Connecting to the API using a key

If you have access to the Analytics API, simply get an API key from the Dimensions webapp (My Account > General Settings > API key and click “Create API key”) and fill in the parameters below with your details (see also this page).

[ ]:

KEY = 'your API key'            # your private API key
ENDPOINT = 'app.dimensions.ai'  # the Dimensions server you are using

Now try running the script below to verify your connection.

[ ]:

#   The credentials to be used
login = {
    'key': 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(f'https://{ENDPOINT}/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(
    f'https://{ENDPOINT}/api/dsl.json',
    data='search publications for "乳がん" return publications'.encode(),
    headers=headers)

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

{'_stats': {'total_count': 103121703}, 'publications': [{'title': 'Sure 16,1 - 23,118', 'type': 'book', 'id': 'pub.1113244530', 'year': 2019}, {'title': 'Deutungsmacht von Zeitdiagnosen', 'type': 'book', 'id': 'pub.1113146259', 'year': 2019}, {'title': '“So You Want to Write about American Indians?” Ethical Reflections on Euro-Academia’s Research on Indigenous Cultural Narratives', 'author_affiliations': [[{'first_name': 'Amina', 'last_name': 'Grunewald', 'orcid': '', 'current_organization_id': '', 'researcher_id': '', 'affiliations': []}]], 'type': 'chapter', 'id': 'pub.1113271690', 'pages': '239-260', 'year': 2019}, {'title': 'The Moral Nexus', 'author_affiliations': [[{'first_name': 'R. Jay', 'last_name': 'Wallace', 'orcid': '', 'current_organization_id': '', 'researcher_id': '', 'affiliations': []}]], 'type': 'monograph', 'id': 'pub.1117142285', 'year': 2019}, {'title': 'VC', 'author_affiliations': [[{'first_name': 'Tom', 'last_name': 'Nicholas', 'orcid': '', 'current_organization_id': '', 'researcher_id': '', 'affiliations': []}]], 'type': 'monograph', 'id': 'pub.1117152054', 'year': 2019}, {'title': 'Altenheim Thema Hauswirtschaft', 'type': 'monograph', 'id': 'pub.1117170089', 'year': 2019}, {'title': 'Expression of a novel gene encoding protease inhibitor from metagenome of sponge in Vietnam', 'author_affiliations': [[{'first_name': 'Tran Thi', 'last_name': 'Hong', 'orcid': '', 'current_organization_id': '', 'researcher_id': '', 'affiliations': []}, {'first_name': 'Ton That Huu', 'last_name': 'Dat', 'orcid': '', 'current_organization_id': 'grid.4818.5', 'researcher_id': 'ur.011501570541.62', 'affiliations': []}, {'first_name': 'Nguyen Phuong', 'last_name': 'Hoa', 'orcid': '', 'current_organization_id': '', 'researcher_id': '', 'affiliations': []}, {'first_name': 'Pham Viet', 'last_name': 'Cuong', 'orcid': '', 'current_organization_id': '', 'researcher_id': '', 'affiliations': []}, {'first_name': 'Nguyen Thi Kim', 'last_name': 'Cuc', 'orcid': '', 'current_organization_id': '', 'researcher_id': '', 'affiliations': []}]], 'type': 'article', 'volume': '40', 'issue': '4', 'id': 'pub.1112252248', 'year': 2019, 'journal': {'id': 'jour.1355760', 'title': 'ACADEMIA JOURNAL OF BIOLOGY'}}, {'title': "Macrophage's Arsenal in the Battle against Zaire EBOLA Virus", 'author_affiliations': [[{'first_name': 'Rosa', 'last_name': 'Michelino Di', 'orcid': '', 'current_organization_id': '', 'researcher_id': '', 'affiliations': []}, {'first_name': 'Malaguarnera', 'last_name': 'Lucia', 'orcid': '', 'current_organization_id': '', 'researcher_id': '', 'affiliations': []}]], 'type': 'article', 'volume': '2', 'issue': '1', 'id': 'pub.1112223838', 'year': 2019, 'journal': {'id': 'jour.1336528', 'title': 'International Journal of Tropical Diseases'}}, {'title': '»Dieses verfluchte Land«', 'author_affiliations': [[{'first_name': 'Annika', 'last_name': 'Raapke', 'orcid': '', 'current_organization_id': '', 'researcher_id': '', 'affiliations': []}]], 'type': 'monograph', 'id': 'pub.1112049851', 'year': 2019}, {'title': 'Medizinische Fachlichkeit und Emotionen', 'author_affiliations': [[{'first_name': 'Kerstin', 'last_name': 'Rego', 'orcid': '', 'current_organization_id': '', 'researcher_id': '', 'affiliations': []}]], 'type': 'monograph', 'id': 'pub.1112050121', 'year': 2019}, {'title': 'Zusammenarbeit', 'type': 'chapter', 'id': 'pub.1112050109', 'pages': '127-154', 'year': 2019}, {'title': 'Einleitung', 'author_affiliations': [[{'first_name': 'Albert', 'last_name': 'Gouaffo', 'orcid': '', 'current_organization_id': '', 'researcher_id': 'ur.016407172041.61', 'affiliations': []}, {'first_name': 'Stefanie', 'last_name': 'Michels', 'orcid': '', 'current_organization_id': '', 'researcher_id': '', 'affiliations': []}]], 'type': 'chapter', 'id': 'pub.1112049938', 'pages': '9-28', 'year': 2019}, {'title': 'Kapitel 18. Besonderheiten beim grenzüberschreitenden Unternehmenskauf', 'author_affiliations': [[{'first_name': 'Christoph F.', 'last_name': 'Wetzler', 'orcid': '', 'current_organization_id': '', 'researcher_id': '', 'affiliations': []}]], 'type': 'chapter', 'id': 'pub.1111892594', 'pages': '1401-1466', 'year': 2019}, {'title': 'Kapitel 71. Wiedereinsetzung in den vorigen Stand', 'type': 'chapter', 'id': 'pub.1111892348', 'pages': '1159-1185', 'year': 2019}, {'title': 'Sachregister', 'type': 'chapter', 'id': 'pub.1111901333', 'pages': '2645-2662', 'year': 2019}, {'title': '6. Teil: Vertrags- und Rechtsverhältnisse', 'type': 'chapter', 'id': 'pub.1111892463', 'pages': '967-1150', 'year': 2019}, {'title': 'Deutsch aus finnischer Sicht - Überblick über die sprachliche Situation in Finnland mit einer kontrastiven Betrachtung von Wort- und Wortformenstrukturen', 'author_affiliations': [[{'first_name': 'Irma', 'last_name': 'Hyvärinen', 'orcid': '', 'current_organization_id': '', 'researcher_id': '', 'affiliations': []}]], 'type': 'chapter', 'id': 'pub.1111879211', 'pages': '203-238', 'year': 2019}, {'title': 'Kapitel 137. Grundzüge des Arbeitsgerichtsverfahrens', 'type': 'chapter', 'id': 'pub.1111892415', 'pages': '3100-3104', 'year': 2019}, {'title': 'Kapitel 10. Prozesskostenhilfe', 'type': 'chapter', 'id': 'pub.1111892288', 'pages': '123-169', 'year': 2019}, {'title': 'Kapitel 107. Einstweilige Anordnungen', 'type': 'chapter', 'id': 'pub.1111892385', 'pages': '2442-2452', 'year': 2019}]}

If the details are correct, you should see some JSON results being returned, which looks like this

{'_stats': {'total_count': 103121703}, 'publications': [{'title': 'Sure 16,1 - 23,118', 'type': 'book', 'id': 'pub.1113244530', 'year': 2019}, {'title': 'Deutungsmacht von Zeitdiagnosen', 'type': 'book', 'id': 'pub.1113146259', 'year': 2019}, {'title': '“So You Want to Write about American Indians?” Ethical Reflections on Euro-Academia’s Research on Indigenous Cultural Narratives', 'author_affiliations': ....

Legacy authentication method: username & password

Some legacy users may still have to authenticate using their Dimensions username and password.

If that’s the case, simply replace the beginning of the snippet above as follows:

[1]:

#   Deprecated method if you don't have a key

login = {
    'username': 'ENTER YOUR USERNAME HERE',
    'password': 'ENTER YOUR PASSWORD HERE'
}

#   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(f'https://{ENDPOINT}/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(
    f'https://{ENDPOINT}/api/dsl.json',
    data='search publications for "乳がん" return publications'.encode(),
    headers=headers)

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

Troubleshooting

If you get an error it may be for any of these reasons:

  • your Dimensions credentials do not support API access

  • you mispelled your key

  • you mispelled the endpoint URL (if unknown, you can try ‘app.dimensions.ai’)

  • you don’t have a working internet connection

It’s also useful to take a look at the API official documentation as there various other way to test your API connection.


Note

The Dimensions Analytics API allows to carry out sophisticated research data analytics tasks like the ones described on this website. Check out also the associated Github repository for examples, the source code of these tutorials and much more.

../../_images/badge-dimensions-api.svg