Altmetric Details Page API Reference & Getting Started
Introduction
Altmetric tracks mentions of scholarly works across the social web. For more information on what types of research we track and where we track it online, please visit our Support Portal.
We handle all of the heavy lifting involved in extracting, disambiguating and collating this information so that you can focus on the bigger picture. Contact us to discuss pricing before integrating Altmetric data.
If you are looking for information about the Altmetric Explorer API, please click here.
What can you do with this API?
The Altmetric Details Page API is perfect for integrating Altmetric metrics and full-text mentions into your website or app.
There are three ways you can access Altmetric’s data via our API:
For scientometrics research:
Altmetric Details Page API - Counts Only, rate-limited
- No API key required.
- Free for scientometrics researchers.
- Includes research object metadata and metrics only.
- Available only for one-time, limited term research projects.
- Best for small projects.
- Rate limited to 1 call per second.
Altmetric Details Page API - Counts Only, no rate limits
- API key required.
- Free for scientometrics researchers.
- Includes research object metadata and metrics only.
- Available only for one-time, limited term research projects.
- Best for medium to large projects
- No rate limit.
If you'd like to use the Altmetric Details Page API in an academic research project, please visit our website.
For commercial use
Altmetric Details Page API - Full Access (aka “/fetch”)
- Key required. Includes research object metadata, metrics, and full-text mentions for most data sources (except Twitter).
- Available for commercial use as well as one-time, limited term research projects.
- No rate limit.
To learn more about requesting a commercial license, visit our website.
If you’d like to use the Altmetric Details Page API for non-commercial purposes that don’t exactly meet the “research project” use case, please email us at info@altmetric.com to discuss your options.
Here’s a list of all JSON fields available in the Counts Only version of the API. Note that the Full Access version of the API includes more data fields, which we’re happy to share with those who have a license.
Want to see what's possible? Check out examples on our website.
Getting Started
Data license
Requirements:
- Altmetric data can be made free for scientometric 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. Please contact us for more information.
- Please attribute the data to Altmetric.com.
- Do not redistribute the data in bulk.
API versioning
The current Altmetric Details Page API version is v1. This is the version you should use in production.
All calls need to be versioned to avoid future API releases breaking client code. You can specify which version of the API to use by changing the base URL for your calls e.g. to use v1 it should be:
https://api.altmetric.com/v1/
and your actual calls should look like:
https://api.altmetric.com/v1/citations/1d https://api.altmetric.com/v1/doi/10.1038/480426a
API keys
You should include a parameter named key that contains your Altmetric Details Page API key in all of the calls you make.
For example, if your key was xxx:
curl 'http://api.altmetric.com/v1/id/241939?key=xxx'
If you are a scientometrics researcher, you don't need to register for an API key to use the rate-limited Altmetric Details Page API - Counts Only, but it is highly recommended that you do. If you wish to use the Altmetric Details Page API - Counts Only without limiting, you must obtain an API key. Please visit our website for more information.
If you would like to use the Altmetric Details Page API for commercial purposes, you will need to obtain an API key. Please email info@altmetric.com for more information.
Attribution
If you use the Altmetric Details Page API in an app or mashup, please attribute us prominently on the page where the data is displayed. Our official branding guidelines include more information on how to credit us appropriately.
Response Codes
When debugging queries that aren't returning what you expect it can be useful to check the HTTP status code being returned by the Altmetric Details Page API.
| HTTP status code | Description |
| 200 | Success. The body of the response should contain the data you requested. |
| 403 | You aren't authorized for this call. Some calls and query types can only be made by holders of an API key and/or a license for the Full Access version of the API. |
| 404 | Altmetric doesn't have any details for the article or set of articles you requested. |
| 429 | You are being rate limited. If you haven't already then apply for an API key. |
| 502 | The Altmetric Details Page API version you are using is currently down for maintenance. |
Cross site scripting & JSONP
The Altmetric Details Page API currently sets a liberal Access-Control-Allow-Origin header and supports preflight OPTION checks, so you should be able to make cross-domain calls to the API in modern browsers using CORS.
To support older browsers you can use JSONP. To do this include a callback parameter that contains the name of the Javascript function to invoke when the call returns.
For example:
https://api.altmetric.com/v1/doi/10.1038/480426a?callback=my_callback
You can try this now: https://api.altmetric.com/v1/doi/10.1038/480426a?callback=my_callback
Note that Altmetric is quite strict about what constitutes a valid callback - only letters, digits and underscores are allowed.
Rate limiting
Please don't hammer the server! Where possible limit calls to once a second.
Right now the Altmetric Details Page API limits by IP on an hourly and daily basis. Check the X-HourlyRateLimit-Limit and X-DailyRateLimit-Limit headers for the current limits. X-HourlyRateLimit-Remaining and X-DailyRateLimit-Remaining tell you how many calls you can make from your current IP. An API key raises the rate limits significantly.
If you start seeing 429 status codes then you've been rate limited. Please back off for an appropriate length of time.
Retrieving Twitter data
Due to a contractual agreement that Altmetric has with Twitter, a maximum of 1,500,000 tweet IDs can be retrieved in any rolling 30 day period, if your request returns tweet IDs, please check the X-TweetIDRateLimit-Limit and X-TweetIDRateLimit-Remaining headers to check how close you are to the limit.
Please ensure that you are compliant with Twitter's Terms of Service and the Developer Policy when using Twitter data. For further information about Twitter data usage restrictions, please read this Knowledgebase article.