Altmetric API Reference & Getting Started
Altmetric tracks mentions of scholarly works on social media sites, scholarly bookmarking services and in science news outlets. It handles all of the heavy lifting involved in extracting, disambiguating and collating this information so that you can focus on your core product.
The Altmetric API gives you programmatic access the data about articles & datasets collected by Altmetric.
If you're keen to get up and running quickly we also provide embeddable badges.
What can you do with this API?
It's free to use this API to fetch basic alt-metrics information about articles & datasets and to use that information in your own apps and mashups - just give altmetric.com attribution somewhere.
However, if you'd like to download the data in bulk, perform more complex queries, remove the rate limits and see more detailed data about articles then you'll need a commercial license (if you'd like to let us know about your use case you can reach us at email@example.com).
If you'd like to use the data in an academic research project then let us know and we can grant you a free license for non-commercial use.
- Do attribute the data to Altmetric.com.
- Do feel free to use the basic, free Altmetric data for commercial, academic or non-commercial projects.
- Do apply for an API key; this will drastically increase rate limits.
- Do not redistribute the data in bulk.
The current 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:
and your actual calls should look like:
You should include a parameter named key that contains your API key in all of the calls you make.
For example, if your key was xxx:
You don't need to register for an API key to use the Altmetric API. That said all queries are rate limited by IP and the limit for queries without a key is fairly low.
Registering an API key is also a good way of letting us know about your app or mashup.
To get an API key just email support at firstname.lastname@example.org with a brief description of your project.
If you use the Altmetric API or datasets in an app, mashup or report please attribute us somewhere appropriate on the page where the data is being displayed.
A simple namecheck and link to altmetric.com is fine. The exact location and style of the attribution is up to you!
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 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 commercial license.|
|404||Altmetric doesn't have any details for the article or set of articles you requested.|
|420||You are being rate limited. If you haven't already then apply for an API key.|
|502||The API version you are using is currently down for maintenance.|
Cross site scripting & JSONP
The 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.
You can try this now: http://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.
Please don't hammer the server! Where possible limit calls to once a second.
Right now the 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.
If you start seeing 420 status codes then you've been rate limited. Please back off for an appropriate length of time.
An API key raises the rate limits significantly.