altmetric-small

Introduction

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're affiliated with a non-profit organization or want to use the data in a research project then let us know and we can grant you a free license for non-commercial use.

Getting Started

Data license

Please:

  • 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 attribute the data to Altmetric.com.
  • Do not redistribute the data in bulk.

API versioning

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:

http://api.altmetric.com/v1/

and your actual calls should look like:

http://api.altmetric.com/v1/citations/1d
http://api.altmetric.com/v1/doi/10.1038/480426a

API keys

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:

curl 'http://api.altmetric.com/v1/id/241939?key=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 support@altmetric.com with a brief description of your project.

Attribution

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!

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 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.

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:

http://api.altmetric.com/v1/doi/10.1038/480426a?callback=my_callback

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.

Rate limiting

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.