Querying the database
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 Altmetric Details Page 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. | |
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:
|
|
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 Altmetric Details Page 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"
}
]
}