altmetric-small

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.

What can you do with this API?

Our 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 research:

Free, rate-limited API

  • No key required.
  • 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.

Free unlimited API

  • Key required.
  • 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 our free API in an academic research project, please visit our website.

For commercial use

Commercial (aka “/fetch”) API

  • 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 our API for non-commercial purposes that don’t exactly meet the “research project” use case, please email us at info@altmetric.comto discuss your options.

Here’s a list of all JSON fields available in the free API. Note that our Commercial API includes more data fields, which we’re happy to share with those who have a Commercial license.

Want to see what's possible? Check out examples on our website.

Getting Started

Data license

Requirements:

  • Do attribute the data to Altmetric.com.
  • Do feel free to use the basic, free, metrics-only Altmetric data for academic projects.
  • Do contact us about commercial projects, there are some important third party licensing restrictions.
  • Do apply for an API key; this will drastically increase rate limits.
  • 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:

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 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 free, rate-limited Altmetric API, but it is highly recommended. To get an API key for the free unlimited API for research use, please visit our website for more information.

To get a Commercial API key, please learn more on our website, then email info@altmetric.com for more information.

Attribution

If you use the Altmetric 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 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:

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