altmetric-small
https://api.altmetric.com/version/citations/timeframe

List articles with activity in a given timeframe (see the parameters table for acceptable values of timeframe).

Parameters

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.

Pagination

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.

Sorting

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

Response object

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.

Examples

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

Example response

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"
      }
   ]
}