Querying the database

Parameter	Required	Accepts	Description
timeframe	Yes	at 1d, 2d, 3d, 4d, 5d, 6d 1w 1m, 3m 1y	Include only articles which have seen activity in the past x days / weeks / months. Use "at" for "all time": all of the articles in the Altmetric database.
page		integer	Page number, used to paginate through results. First page is page 1. Altmetric will return an error if you ask for a page number beyond (number of matched articles / num_results)
num_results		integer > 0 and < 100	Number of articles per page. Defaults to 25.
cited_in		One or more comma delimited options from: facebook, blogs, linkedin, video, pinterest, gplus, twitter, reddit, news, f1000, rh, qna, forum, peerreview	Include only articles mentioned in the supplied list of sources.
doi_prefix		A DOI prefix (the bit before the first slash, e.g. 10.1038)	Include only articles with a DOI that contains the given prefix.
order_by		One of the following: score, at_score, readers, first_seen, pubdate	Specifies the order in which the returned articles are listed. If omitted, a value of score will be assumed. For explanations of each value, see Sorting.

query.total is the JSON object returned by this call will give you the total number of results available, though only num_results (which defaults to 25) will be returned at any one time. Use the page parameter to page through results.

Use of the order_by parameter will determine the order in which articles are listed within the response of this call.

Parameter value	Description
score (default)	Orders articles based on the Altmetric attention score gained during the period defined by the timeframe argument supplied
at_score	Orders articles based on their overall Altmetric attention score
readers	Orders articles based on the number of Mendeley readers
first_seen	Orders articles based on when Altmetric first started tracking mentions
pubdate	Orders articles based on their publication date

The API returns JSON. /citations/x returns an object with "query" and "results" parameters. "query" contains information about your request. "results" is an array of citation objects, detailed below.

Query

Parameter	Required	Notes
query	Yes	Metadata about your query.
query.total	Yes	Total number of citations found matching your query. Use the page parameter to page through a results set.
results	Yes	Array of citation objects, detailed below. May be empty if query.count is 0.

Citation object

Parameter	Required	Notes
title	Yes	name of article or book cited.
type		This field shows the research output type.
doi		DOI of article or book cited.
nlmid		NLM ID of journal the cited article is from (if applicable).
arxiv_id		arXiv ID of article cited.
ads_id		ID of article cited in ADS.
handles		An array of Handle identifiers corresponding to the cited article.
isbns		An array of ISBN(s) corresponding to the cited article or book.
tq		Some descriptive phrases for this article.
cited_by_posts		List of unique IDs for the citing posts. Only included when you request details of a specific article.
journal		Journal the cited article comes from.
altmetric_id	Yes	Unique ID for this citation. Be careful: ATM there aren't necessarily persistent, just unique.
cited_by_x_count		Mention count breakdown, where x is one of: posts total number of posts delicious number of Delicious users fbwalls number of Facebook accounts feeds number of blogs forum number of internet forums users e.g. Seqanswers gplus number of Google+ users linkedin number of LinkedIn users msm number of news outlets peer_review_sites number of peer review sites pinners number of Pinterest users policies number of policy sources qs number of questions, answers or comments on Stack Exchange sites (inc. Biostar) rdts number of Reddit users rh number of research highlight platforms tweeters number of Twitter users videos number of YouTube channels weibo number of Sina Weibo users wikipedia number of pages on Wikipedia
score	Yes	Altmetric score for this article. This is a measure of the quality and quantity of attention received. It's calculated taking contextual information about each citing post and its author into account.
history	Yes	What would the cited article's Altmetric score be if you only look at posts from the past x, where x is days (1d, 2d, 3d...), a week (1w), in months (1m, 3m), a year (1y) or all time (at).
url	Yes	Link to the cited article.
authors		An array of the author or authors credited with this research output.
editors		An array of the editor or editors credited with this research output.
authors_or_editors		A list of names of contributors where we have been unable to distinguish between authors and editors. Some data sources (e.g., Google Books) do not provide sufficient information to differentiate between roles. If either the authors or editors fields are specified, their contents should be preferred.
book_cover_url		A URL for the cover image of the citation. This metadata is available for some citations of type: book
book		A nested metadata object containing book information including title and isbns. This metadata is available for some citations of type: chapter
chapters		An array of nested chapter metadata containing altmetric_id, title, ordinal_number. This metadata is available for some citations of type: book
added_on	Yes	UNIX timestamp. Date article was first tracked by Altmetric.
published_on		UNIX timestamp. Date article was published. Be careful: this may contains bad data, it's difficult to reliably parse heterogenous publication date strings.
subjects		If the publishing journal is indexed by Medline then the subject codes for that journal appear here.
cohorts		Experimental feature number of people mentioning this article who are members of the public (pub), practitioners (doc), research scientists (sci) or science communicators (com).
readers		Number of readers on Mendeley, Connotea and Citeulike, or -1 if that data is not yet available (there may be a few days delay between a citation's first track date and this field updating).
images		Links to different sizes of a score donut graphic for this citation. The donut has black text and a transparent background.
details_url		Link to a human readable webpage containing information about this citation.

To return the first 25 articles that have been mentioned in the past day:

curl 'https://api.altmetric.com/v1/citations/1d'

Try it now: https://api.altmetric.com/v1/citations/1d

And the next 25:

curl 'https://api.altmetric.com/v1/citations/1d?page=2'

Try it now: https://api.altmetric.com/v1/citations/1d?page=2

Get 100 articles mentioned in the past week:

curl 'https://api.altmetric.com/v1/citations/1w?num_results=100'

Try it now: https://api.altmetric.com/v1/citations/1w?num_results=100

Get 100 articles mentioned on Reddit in the past week:

curl 'https://api.altmetric.com/v1/citations/1w?num_results=100&cited_in=reddit'

Try it now: https://api.altmetric.com/v1/citations/1w?num_results=100&cited_in=reddit

Get 100 articles mentioned on Reddit or mainstream news sources in the past week:

curl 'https://api.altmetric.com/v1/citations/1w?num_results=100&cited_in=reddit,news'

Try it now: https://api.altmetric.com/v1/citations/1w?num_results=100&cited_in=reddit,news

Below is a sample API response in JSON format, real responses may contain more keys and more data.

{
   "query":{
      "total":2418
   },
   "results":[
      {
         "title":"Number of species on Earth tagged at 8.7 million",
         "doi":"10.1038/news.2011.498",
         "nlmid":"0410462",
         "journal":"Nature News",
         "altmetric_id":243700,
         "cited_by_posts_count":138,
         "cited_by_tweeters_count":134,
         "score":114.5,
         "history":{
            "1d":114.5,
            "2d":114.5,
            "3d":114.5,
            "4d":114.5,
            "5d":114.5,
            "6d":114.5,
            "1w":114.5,
            "1m":114.5,
            "3m":114.5,
            "1y":114.5,
            "at":114.5
         },
         "url":"http://www.nature.com/news/2011/110823/full/news.2011.498.html",
         "added_on":1314135172,
         "published_on":1314054000,
         "subjects":[
            "science"
         ],
         "readers":{
            "mendeley":-1,
            "downloads":-1
         }
      },
      {
         "title":"Courting connections",
         "doi":"10.1038/nj7361-479a",
         "nlmid":"0410462",
         "journal":"Nature",
         "altmetric_id":244437,
         "cited_by_posts_count":18,
         "cited_by_tweeters_count":18,
         "score":15,
         "history":{
            "1d":15,
            "2d":15,
            "3d":15,
            "4d":15,
            "5d":15,
            "6d":15,
            "1w":15,
            "1m":15,
            "3m":15,
            "1y":15,
            "at":15
         },
         "url":"http://www.nature.com/naturejobs/2011/110825/full/nj7361-479a.html",
         "added_on":1314214692,
         "published_on":1314140400,
         "subjects":[
            "science"
         ],
         "readers":{
            "mendeley":4,
            "connotea":0,
            "citeulike":6
         },
         "images":{
            "small": "http://api.altmetric.com/donut/241939_64x64.png",
            "medium": "http://api.altmetric.com/donut/241939_100x100.png",
            "large": "http://api.altmetric.com/donut/241939_180x180.png"
         },
         "details_url": "http://www.altmetric.com/details.php?citation_id=657451"
      }
   ]
}