What is the Altmetric Explorer API?
The Altmetric Explorer API gives programmatic access to all of the research outputs and attention data within your instance of the Altmetric Explorer, making it easy to integrate Altmetric data (including custom queries) into external websites, dashboards, visualizations, and reports with a bit of programming knowledge. The Explorer API should be accessed from within the Altmetric Explorer.
For customers with an institutional data implementation, imported information such as author names, department or group names, and institutional research outputs are all searchable via the Explorer API. For example, users can query the Explorer API by a particular department or author name and see all associated Altmetric data, including data relating to research outputs, mentions, demographics, journals, and more. This data is very similar to the data contained in the CSV spreadsheet exports. However, with the API you are able to access it programmatically and check for updates. You will need some programming experience in order to pull data from this API.
Users can build research output search queries using the Quick or the Advanced Search in the Altmetric Explorer, and then use the “Export this tab” button to view the information in the JSON format of the Explorer API. Altmetric attention data from the Research Outputs tab, the Timeline tab, the Demographics tab, the Mentions tab, and the Journals tab can be viewed in JSON format.
Screenshot of the Altmetric Explorer Research Outputs tab, showing how to access the Altmetric Explorer API results for a search query, by hovering over the “Export This Tab” button.
Screenshot of the Explorer API output for a search query
Which endpoints are available in the Altmetric Explorer API?
The Altmetric Explorer API has five endpoints you can query for Altmetric data:
The Research Outputs endpoint gives you the list of all research outputs (scholarly articles, datasets, and other types) matching your query. For example, a researcher can use this endpoint to collect data regarding a set of outputs for a research project.
The Attention Summary endpoint gives you access to the aggregated attention data for research outputs matching your query. For example, a journal editor can use this endpoint to collect aggregated attention over time for their publications.
The Demographics endpoint gives you access to aggregated location data from Twitter ("tweet"), Facebook ("fbwall"), news ("msm"), and policy ("policy") mentions. You can choose which one you want to see using the "filter[filter]" query parameter. If you don't specify a source, you'll see Twitter demographics by default. For example, a university department can use the Altmetric Explorer API to obtain the Demographics data for the attention associated with their research outputs, and then subsequently use the data to build custom maps.
The Mentions endpoint gives you access to all of the individual mentions of the research outputs in your search. For example, a librarian can use the Altmetric Explorer API to display the most recent policy mentions for their institution’s research outputs.
The Journals endpoint gives you aggregate information about the journals and collections that the research outputs belong to. For example, a journal editor can use this field to do horizon scanning and see where their journals are receiving the most attention in comparison to their competitors.
For more information, there is extra documentation within the Explorer. You can find this via your Settings page.
Do I need an API key? How do I change it?
Each Altmetric Explorer account with Altmetric Explorer API access has its own API key and API secret. The API key and secret are unique to a user’s account. If your API secret key becomes compromised, and you wish to revoke access for an application, the API key and secret can be reset in Account Settings, which you can find on the bottom left-hand navigation panel of the Explorer. Please note that this step is irreversible. This means that if you have an API implementation relying on the key and secret key, it will stop working.
What rate limits are in place for the Altmetric Explorer API?
The Explorer API does not have a rate limit in place, but we do ask that you keep your queries at two per second or below. Whilst we don’t foresee performance problems with the API at the moment, we may get in touch with you if we notice an issue with your integration to ensure you’re accessing the data in the most optimal way.
What are the usage restrictions associated with Altmetric data?
- Altmetric data can be made free for researchers. Please contact us to apply for our Researcher Data Access Program.
- Commercial projects must adhere to third party licensing restrictions contained in their contracts.
- Do not redistribute the data in bulk.
- If you are using Twitter data, please ensure that you are compliant with Twitter's Developer Policy and Twitter's Terms of Service.
How do I provide attribution to Altmetric data?
If you use the Altmetric Details Page API please attribute us prominently on the page where the data is displayed, guidelines for data attribution are available here. Our official branding guidelines include more information on how to credit us appropriately.