../../_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

Connecting to the API

If you have access to the analytics API, simply fill in the parameters below with your details:

[ ]:
USERNAME = 'your username'
PASSWORD = 'your password'
ENDPOINT = 'app.dimensions.ai'  # eg no need to include 'https://'

Try running the script below (Note: the script is also available on the API official documentation).

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': ....
[ ]:
#   The credentials to be used
login = {
    'username': USERNAME,
    'password': PASSWORD,
    # NOTE if you have an API key, comment the two lines above and uncomment the next one:
    # '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(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}]}

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 username and/or password

  • 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