Getting Started¶

Introduction¶

This guide will cover the essential topics to get yourself familiarized with the functionalities of the Altmetric Explorer API. The API provides programmatic access to all the research outputs and attention data within your Altmetric Explorer instance. You'll learn how to retrieve the data in JSON API format, enabling seamless integration into your existing workflows or systems.

As you'll be working with large datasets we will cover pagination and how to navigate through API responses so you can efficiently retrieve all the desired information related to your search criteria. We will also cover how you can obtain and manage API keys, which serve as your applications authentication credentials for accessing the Altmetric Explorer API.

By following this getting started guide, you'll gain the necessary knowledge and skills to begin utilizing the Altmetric Explorer API effectively.

JSON API¶

The Altmetric Explorer API is generally following the JSON API specification.

The JSON API specification is a set of guidelines and conventions that define how client and server applications communicate over the web using JSON (JavaScript Object Notation) as the data format. It provides a standardized way to structure and format requests and responses, enabling interoperability between different systems and programming languages. The JSON API specification focuses on simplicity, efficiency, and consistency, aiming to reduce the complexity and ambiguity often associated with building and consuming web APIs. It establishes rules for resource representation, error handling, pagination, filtering, sorting, and other common aspects of API design, making it easier to build robust and scalable web applications.

The below example illustrates the high-level structure of a response originating from the Altmetric Explorer API.

{
  "meta": { },
  "links": { },
  "data": { },
  "included": { }
}

Pagination¶

Results are paginated by default with each page containing a limited number of items (25 by default). To access all the data matching your query parameters, you'll have to use the pagination links provided in the response to iterate through the remaining pages. You can also access pages directly by page number.

Using links provided in the response¶

Each page returned from the API includes a links section with the following keys.

In order to step through the pages of results one by one, you should retrieve the next page link until you reach the last page and there is no next link available.

A simple example in Python is shown below. Note that it uses the requests library to retrieve data and the page[size] url parameter describe below to set the number of items per page.

import requests

url = ('https://www.altmetric.com/explorer/api/research_outputs?'
       'digest=YOUR_DIGEST'
       '&filter[field_of_research_codes][]=4902'
       '&filter[publisher_id][]=b4b24c0e-d515-4dea-baa6-6aef404be00d'
       '&filter[q]=Gravity'
       '&filter[scope]=all'
       '&filter[type][]=article'
       '&page[size]=100'
       '&key=YOUR_API_KEY')
page_num = 0

while url:
    # Get a page of data
    resp = requests.get(url)
    page = resp.json()

    # Do something with the page of data
    page_num += 1
    page_size = len(page.get('data', []))
    print(f'Page #{page_num} contains {page_size} results')

    # Get the url of the next page if one exists
    url = page.get('links').get('next')

The output printed to the terminal will look something like this depending on the data in Altmetric Explorer when you run the query:

Page #1 contains 100 results
Page #2 contains 100 results
Page #3 contains 100 results
Page #4 contains 100 results
Page #5 contains 100 results
Page #6 contains 100 results
Page #7 contains 100 results
Page #8 contains 100 results
Page #9 contains 100 results
Page #10 contains 100 results
Page #11 contains 100 results
Page #12 contains 100 results
Page #13 contains 100 results
Page #14 contains 56 results

Accessing pages directly¶

It is also possible to construct a request that retrieves a page directly by setting two URL parameters:

Get first page, with 25 results per page

curl "https://www.altmetric.com/explorer/api/research_outputs?page[number]=1&key=YOUR_API_KEY&digest=YOUR_DIGEST&filter[q]=pandemic&filter[scope]=all&filter[timeframe]=3m&filter[type][]=article&filter[type][]=dataset"

Get the third page, with 20 results per page

curl "https://www.altmetric.com/explorer/api/research_outputs?page[number]=3&page[size]=20&key=YOUR_API_KEY&digest=YOUR_DIGEST&filter[q]=pandemic&filter[scope]=all&filter[timeframe]=3m&filter[type][]=article&filter[type][]=dataset"

Included Fields¶

The response from some endpoints also have an field called included that contain commonly requested information from data items related to the results of the query. For example, the name of a journal for a research output. You can find out more about the included fields by reading the documentation for each endpoint.

API Keys¶

Every request needs to be encoded with your API secret. Your API keys can be managed from your Account Settings in the Altmetric Explorer. If you don't see your API key and Secret there, you should contact us to find out why. It may be that your organization does not have access to the Altmetric Explorer API.

Your API key is tied to your account and may have certain privileges attached to it. For this reason, it's important not to allow your API Secret to be made public. Be careful to not include it in public projects or places like GitHub.

Resetting API Keys¶

If your API Secret has accidentally been revealed, you can reset it from your Account Settings. You can do this by clicking the 'Reset API Keys' button which will create a new API Key and Secret.

Authentication¶

All requests should be made over HTTPS in order to protect data during transit.

Fundamentally there are two methods of building Altmetric Explorer API requests, either using the Altmetric Explorer itself or by constructing them manually. If you're new to APIs then using the Altmetric Explorer is by far the quickest and easiest method, once you're familiar with how things work you can move onto singing your own requests in the future.

Using the Altmetric Explorer to create signed API requests¶

Using the Altmetric Explorer to handle digest generation is by far the easiest way to get started, it does however mean that your queries will be static. If you're using the API to harvest the same data from the system on a regular bases based on your own criteria then this isn't likely to be an issue. If on the other hand you're building a dashboard where users will be choosing their own criteria you should consider signing requests yourself.

Building your first query¶

• Log into your Altmetric Explorer account
• Click on the [RESEARCH OUTPUTS] tab
• Click on the blue [EDIT SEARCH] button at the top of the screen
• Type in the word pandemic in the KEYWORD field
• Change your search scope to Full Altmetric database (if your Explorer for Institutions instance doesn't have an integration you can skip this step)
• Tick the Articles and Data sets options for TYPE OF OUTPUT
• Change the ALTMETRIC MENTIONS DURING drop-down selection to the past 3 months
• Click the blue [RUN SEARCH] button
• Change the Sort by drop-down selection to Publication date (Newest first)
• Finally, click on the blue [EXPORT THIS TAB] button and choose Open results in API

That's it! You've just created your first Altmetric Explorer API query and the Altmetric Explorer has taken care of the authentication and digest generation for you. All you'd need to do now is take a copy of the generated URL from your browsers address bar and use it within your application to then make requests programmatically.

Signing your own requests¶

If you're not using the Altmetric Explorer to generate your Altmetric Explorer API calls you will need to handle authentication and digest generation yourself.

To authenticate your requests you will need to use HMAC with SHA1. The key will be your API Secret. The data used to create the digest should be each of the filters you're sending along with your request, except for the order, page[number] and page[size] filters, these should be excluded.

Filters should be ordered alphabetically, joined by a pipe |, and stripped of other any other syntax.

Below are the filters you will need to provide to see all mentions within the past three months of research papers and datasets regarding pandemics, ordered by publication date (newest first).

https://www.altmetric.com/explorer/api/research_outputs?
filter[type][]=article&
filter[q]=pandemic&
filter[timeframe]=3m&
filter[type][]=dataset&
filter[scope]=all&
filter[order]=publication_date

After transforming your filters, you will be left with a string like this (again, note that the order filter has been removed):

q|pandemic|scope|all|timeframe|3m|type|article|dataset

Run this through your favorite HMAC library, using SHA1 and your API Secret to get your digest.

api_secret = 'YOUR_API_SECRET'
filters = 'q|pandemic|scope|all|timeframe|3m|type|article|dataset'
digest = OpenSSL::Digest.new('sha1')

hmac = OpenSSL::HMAC.hexdigest(digest, api_secret, filters)
#=> "YOUR_DIGEST_RESULT"

Now you have a digest and your private key (not your secret). Add them both to your URL:

https://www.altmetric.com/explorer/api/research_outputs?
digest=YOUR_DIGEST&
filter[q]=pandemic&
filter[timeframe]=3m&
filter[type][]=article&
filter[type][]=dataset&
filter[scope]=all&
filter[order]=publication_date&
key=YOUR_API_KEY

In the above example, filters have been split over multiple lines so that it's easier to read.

Digest generator¶

You can use this tool to help you build and test your Altmetric Explorer API digest. The query field accepts a basic key/value pair object where the key is the name of the filter and the value is the value of the filter. For filters that accept multiple values you'll need to use an array of string values.

Click this link to view the Altmetric Explorer API response for your query:

Limitations¶

The Altmetric Explorer API consumes GET requests for handling queries sent to it. In general, most web servers and browsers enforce a maximum URL length for GET requests, typically around 2,048 characters. This limit includes the entire URL, including the domain, path, query parameters, and any additional data. Exceeding this limit will result in requests to fail.

To ensure compatibility and to avoid issues, it is recommended that your GET requests are kept reasonably short. If you need to provide a large amount of data via the query string, consider splitting up requests instead.

To accommodate the ability to search for up to 25,000 scholarly identifiers, which will most likely exceed the typical 2,048-character upper limit, the Altmetric Explorer employs an intermediary step. When users add scholarly identifiers, their provided list undergoes a transformation process. The Altmetric Explorer converts this list into a lookup list, assigning it it's own unique identifier (identifier_list_id).

Rather than sending a long list of identifiers directly in the querystring, the Altmetric Explorer now uses this generated identifier as a query string parameter instead. This approach enables efficient and effective searching while bypassing the restrictions imposed by URL length limitations. The lookup list can be created either interactively within the Altmetric Explorer or programmatically via the Identifier Lists endpoint. The list itself is static once created — if you need to modify the identifiers you'll need to create a new list (which will produce a new identifier_list_id).