Skip to content

API Client

A simple Python API client is available for public use at https://github.com/altmetric/altmetric-explorer-api-client.

You can use pip to install it directly from GitHub:

pip install https://github.com/altmetric/altmetric-explorer-api-client/tarball/main

The Altmetric Explorer API client simplifies making calls to the API in a number of ways:

  • Filters and other parameters are specified using python data structures so there is no need to construct query strings
  • Digests are calculated automatically for each request so there is no need to get them from Altmetric Explorer or use the tool embedded in this documentation
  • Pagination is handled automatically by fetching new pages as needed on demand

The client is not tied to a fixed list of read endpoints. Its generic client.get(path, **filters) method works for any read (GET) endpoint and any filter documented on this site, so newly added read endpoints and filters can be used immediately without waiting for a client update:

response = client.get(
    'research_outputs/mention_sources',
    timeframe='1w',
    mention_sources_countries=['us', 'gb'],
)

The one write endpoint, identifier lists (POST /explorer/api/identifier_lists), does not follow the generic get pattern, so the client provides a dedicated client.create_identifier_list(identifiers) method that returns the created list (its id, counts and content):

response = client.create_identifier_list('10.1038/nplants.2015.3 altmetric:12345')
identifier_list_id = response.resource['id']

In order to help you get started, the following notebooks are available. Click on the links below to open them in Google Colab:

  • Getting Started provides a step-by-step guide to installing, configuring and using the Altmetric Explorer API client. Start here if you are new to using the Altmetric Explorer API client.
  • Endpoints provides more focussed examples of using the Altmetric Explorer API client to query the data endpoints provided by the Altmetric Explorer API.