What is the Altmetric Details Page API?


The Altmetric Details Page API is the API that powers the Altmetric details pages and the Altmetric badges. The Details Page API allows users to see the information from the Details Pages and the badges in a machine readable way. The Altmetric Details Page API has two tiers: Counts Only and Full Access. 


Altmetric Details Page API - Counts Only


The Altmetric Details Page API - Counts Only provides information about individual research outputs. For example, you can query the Altmetric API by a DOI and retrieve the relevant Altmetric data. The below table lists some of the fields that are returned by the Altmetric Details Page API - Counts Only when queried. A full list of the fields returned is available here.


Fields returned in the main call

Explanation

title

Title of the publication

doi

Related DOI

pmid

Related Pubmed identifier

pmcid

Related Pubmed Central identifier

url

URL for a captured identifier (e.g doi.org/xxx)

isbns

Related ISBNs

altmetric_jid

Internal identifier for a journal

issns

ISSNs associated with the publication

journal

Journal title associated with the publication



When should I use the Altmetric Details Page API - Counts Only?


The Altmetric Details Page API - Counts Only is optimized for querying for a single identifier or strictly defined search. You can see the output of  the Altmetric Details Page API - Counts Only API in a browser by adding an identifier to the URL. 


For example: A researcher is looking for the number of Facebook mentions  associated with their publication and queries the API for the data.  To get this information they add their DOI to the API query: http://api.altmetric.com/v1/doi/10.1371/journal.pone.0069841 



Altmetric Details Page API - Full Access


Altmetric Details Page API - Full Access is the paid tier and includes the 'fetch' call (http://api.altmetric.com/docs/call_fetch.html) which provides more detailed information about the mentions. 


The ‘fetch’ calls allows users to see full details of the mentions, including the URLs to the mentions themselves. 


There are two exceptions with the “fetch” call, Twitter and certain news sources that fall under UK licensing restrictions. Unfortunately, for legal reasons, we are not allowed to display the full body mentions of tweets or the information related to certain news sources. More information about why we can’t display some news mentions is available here


For more information about our API, query parameters you can use, and the fields it returns please visit this page to see our technical documentation.


When should I use the Altmetric Details Page API - Full Access?


The Altmetric Details Page API - Full Access is optimised for specific queries about single research outputs. To use the Full Access version of the Details Page API you will need some programming knowledge. There are various “wrappers” in different languages (e.g Python, Ruby) available on Github or you can choose to write your own software. 


For example: A researcher wants to see the Reddit mentions for their research output


Do I need an API key to access the Altmetric Details Page API?


We strongly recommend using and API key. Though you don’t need one to access the Altmetric Details Page API - Counts Only. Having an API key would increase the rate limit for your queries.


You do need an API key for the Full Access API, as it includes the /fetch/ call.


If you’d like an API key please email support@altmetric.com and we can review your use case for free access under our Researcher Data Access Program. 


How can I access the Altmetric Details Page API as a researcher?


If you’d like to do research using the Altmetric Details Page API, please send us an email at support@altmetric.com. We’d be happy to review your use case and provide you with access to our data via the Researcher Data Access Program. 


What are the usage restrictions associated with Altmetric data?

  • Do attribute the data to Altmetric.com.

  • Do feel free to use the Altmetric data for academic projects. (Read our guide for describing Altmetric data.)

  • Do contact us about commercial projects, there are some important third party licensing restrictions.

  • Do not redistribute the data in bulk.


How do I provide attribution to Altmetric data?


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.