Citations

Returns a list of research outputs with activity in the provided timeframe.

Request

GET /{version}/citations/{timeframe}

Returns a list of research outputs with activity in the provided time frame.

Example request:

GET /v1/citations/1m HTTP/1.1
Host: api.altmetric.com

Query parameters:

Parameter	Required	Accepts	Description
`version`	Yes	`v1`	See Versioning
`timeframe`	Yes	`at` `1d` `2d` `3d` `4d` `5d` `6d` `1w` `1m` `3m` `1y`	Include only research outputs which have seen activity in the past x days / weeks / months. Use `at` for “all time”: all of the research outputs in the Altmetric database.
`page`		integer	Page number used to paginate through results. First page is page `1`. The API will return an error if you ask for a page number beyond (number of research outputs / `num_results`).
`num_results`		integer > `0` and < `100`	Number of research outputs 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` `policy` `weibo`	Include only research outputs mentioned in the supplied list of sources.
`doi_prefix`		A DOI prefix (for example 10.1038)	Include only research outputs with a DOI that contains the given prefix.
`issn`		Accepts a comma separated list of ISSN’s. Both `00221465` and `0022-1465` are accepted values.	A valid journal ISSN number. Must be a journal already registered and accessible from within the Altmetric Explorer.
`order_by`		One of the following: `score` `at_score` `readers` `first_seen` `pubdate`	Specifies the order in which the returned research outputs are listed. If omitted, a value of `score` will be assumed. For explanations of each value, see Sorting.
`key`			The API key that you were issued.

HTTP status codes:

Code	Description
200 OK	The body of the response should contain the data you requested.
403 Forbidden	You aren’t authorized for this call. Some requests require an API key.
404 Not Found	Altmetric doesn’t have any details for the research output or set of research outputs you requested.
429 Too Many Requests	You are being rate limited. If you haven’t already then apply for an API key.
502 Bad Gateway	The API version you are using is currently down for maintenance.

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

Pagination

Results from this endpoint are paginated. To help with paging through the list of results a query object is embedded in each response.

Key	Description
`total`	The total number of research outputs that match the query parameters.
`page`	The current page that you are on.
`num_results`	The number of research outputs in the current page.

Example

Here we can see that we are currently on page 1 and we have been returned 25 results of a possible 100.

{
    "query": {
        "total": 100,
        "page": 1,
        "num_results": 25
    },
    "results" : [ ]
}

To get the next page you’d need to make the following request:

curl https://api.altmetric.com/v1/citations/at?page=2

To page through the entire list of research outputs: while query.page multiplied by query.num_results is less-than query.total you will need to keep incrementing the page query string integer value. In the example here we’d just need to increment the page up to 4 (4 x 25 = 100).

Sorting

Use of the order_by parameter will determine the order in which research outputs are listed within the response of the request.

Parameter	Description
`score (default)`	Orders research outputs based on the Altmetric attention score gained during the period defined by the timeframe argument supplied. For example, if the timeframe is `1d`, the article which gained the most attention in the last 24 hours will be at the top.
`at_score`	Orders research outputs based on their overall Altmetric attention score (the number generally shown within Altmetric donuts or other badges).
`readers`	Orders research outputs based on the number of readers.
`first_seen`	Orders research outputs based on when Altmetric first started tracking mentions.
`pubdate`	Orders by the publication date of the article. This can be approximate; for example, some publishers may not provide an exact publication date, choosing instead to provide only a year or month.

Response object

The Altmetric Details Page API returns JSON. The /citations/ endpoint returns an object with the keys query and results.

Query object

Parameter	Required	Notes
`query`	Yes	Metadata about your query.
`results`	Yes	Array of citation objects detailed below. May be empty if `query.count` is 0.

Results object

A GET request to the /citations/ endpoint returns a JSON object with the following keys.

Key	Type	Description
`title`	string	Title of the publication
`altmetric_id`	number	Internal ID associated with the research output. Altmetric IDs are transient and unstable over the medium term.
`doi`	string	Relevant DOI.
`pmid`	string	Relevant Pubmed Id.
`pmc`	string	Relevant Pubmed Central Id.
`uri`	string	URI for a captured identifier (e.g https://doi.org/xxx).
`url`	string	URL to publication page.
`isbns`	string []	Relevant ISBN(s).
`altmetric_jid`	string	Internal identifier assigned to each journal or collection.
`handles`	string[]	Relevant Handle(s).
`issns`	string []	Relevant ISSN(s).
`journal`	string	Name of publication journal.
`dimensions_publication_id`	string	Unique identifier for the publication in the Dimensions publications database.
`pubdate`	number	The print date that the publication was published. In Unix.
`epubdate`	number	The date that the publication was published electronically. In Unix.
`published_on`	number	Returns the `epubdate` if it exists on the record - if not then the `pubdate` is returned instead.
`cohorts`	object	See Cohorts for more information.
`abstract`	string	Full abstract for the article.
`abstract_source`	string	Source for the abstract (e.g PUBMED).
`authors`	string[]	Author names.
`type`	string	`dataset` `book` `article` `news` `chapter` `clinical_trial_study_record`
`is_oa`	boolean	Deprecated.
`context`	object	See Context for more information.
`cited_by_fbwalls_count`	number	Number of walls that have mentioned the output on Facebook.
`cited_by_feeds_count`	number	Number of blogs that have mentioned the publication.
`cited_by_gplus_count`	number	Number of accounts that have shared on Google+.
`cited_by_msm_count`	number	Number of news sources that have mentioned the publication.
`cited_by_rdts_count`	number	Number of Redditors that have posted about this publication.
`cited_by_qna_count`	number	Number of forum and Stack Exchange based sites accounts that have mentioned this publication.
`cited_by_tweeters_count`	number	Number of twitter accounts that have tweeted this publication.
`cited_by_wikipedia_count`	number	Number of wikipedia pages that have cited this publication.
`cited_by_policies_count`	number	Number of policies that have mentioned this publication.
`cited_by_patents_count`	number	Number of patents that have mentioned this publication.
`cited_by_videos_count`	number	Number of Youtube channels.
`cited_by_accounts_count`	number	The number of unique sources referencing the research output and is the sum of all `cited_by_*` entries. This is equivalent to the sum of unique_users_count field for each source type when using the Fetch endpoint.
`cited_by_posts_count`	number	A `post` is any online document that links to one or more research outputs (i.e. a post is a single mention or a group of mentions). This field is the total number of individual posts for the requested research output. This is equivalent to counts.total.posts_count field when using the Fetch endpoint.
`last_updated`	number	Last time the score changed. In UNIX.
`score`	decimal	Current Altmetric Attention Score.
`history`	object	See History for more information.
`added_on`	number	Date when Altmetric first captured attention. In UNIX.
`scopus_subjects`	string[]	Initially imported from Scopus in 2011 (Deprecated).
`subjects`	string[]	Subjects for journal. Originally enriched from National Academy of Medicine (Deprecated).
`publisher_subjects`	object[]	See Publisher subjects for more information.
`readers`	object	See Readers for more information.
`readers_count`	number	Total number of unique users who have saved this article in Mendeley, CiteULike or Connotea.
`images`	object	See Images for more information.
`details_url`	string	URL to relevant Altmetric Details Page.
`authors_or_editors`	string[]	Author and editor names.
`attribution`	string	Source of data. For example Google Books.

Cohorts

Cohorts of users who have mentioned the publication on Twitter.

Key	Type	Description
`pub`	number	Somebody who doesn’t link to scholarly literature and doesn’t otherwise fit any of the categories below.
`sci`	number	Somebody who carries out academic or scientific research.
`com`	number	Somebody who links frequently to scientific articles from a variety of different journals / publishers.
`doc`	number	A clinician, or a researcher working in clinical science.

Context

Contains details of the Altmetric score and, where possible, provides some context. See Breakdown for a breakdown of context.

Key	Type	Description
`all`	object	Contains statistics about the entire Altmetric database.
`journal`	object	Contains statistics about all articles from the same journal that have been tracked by Altmetric.
`similar_age_3m`	object	Contains statistics about articles from any journal published within 6 weeks on either side of this one.
`similar_age_journal_3m`	object	Contains statistics about articles from the same journal and published within 6 weeks on either side of this one.

Note

Only research outputs that have a score greater than 0 and are associated with a journal (has an altmetric_jid) will have a score in context.

Breakdown

Available types are all journal similar_age_3m similar_age_journal_3m.

Key	Type	Description
`count`	number	Number of publications in this journal in this time period.
`mean`	decimal	Mean score for publications in this journal in this time period.
`rank`	number	Score in context rank within publications in the journal in this time period.
`pct`	number	% of publications from this journal with fewer mentions in this time period.
`higher_than`	number	Number of publications from this journal with fewer mentions in this time period.

Note

We split the representative sample in percentiles and put the highest score in each 10% into the spark-lines array. Thus the first element of that array is the highest scoring article in the sample set, the second element is the highest score in the 90th %ile, the third element in the 80th %ile and so on.

History

Provides details on how much of the score occurred in a given timeframe.

Key	Type	Description
`1y`	decimal	Score change in the last year.
`6m`	decimal	Score change in the last six months.
`3m`	decimal	Score change in the last 3 months.
`1m`	decimal	Score change in the last one month.
`1w`	decimal	Score change in the last week.
`6d`	decimal	Score change in the last six days.
`5d`	decimal	Score change in the last five days.
`4d`	decimal	Score change in the last four days.
`3d`	decimal	Score change in the last three days.
`2d`	decimal	Score change in the last two days.
`1d`	decimal	Score change in the last one day.
`at`	decimal	Current Altmetric Attention Score.

Publisher subjects

Subjects for journal set by the publisher.

Key	Type	Description
`name`	string	Name of subject
`scheme`	string	Available schemes are `era` `bmj` (Deprecated) `springer` `npg`

Readers

Note

Mendeley counts aren’t updated in real time and there can sometimes be lag of up to a week between the reader count reported by Altmetric and the count on mendeley.com.

Key	Type	Description
`mendeley`	number	Readers in Mendeley.
`connotea`	number	Readers in Connotea (no longer updated).
`citeulike`	number	Readers in CiteULike (no longer updated).

Images

Contains links to PNG versions of the donut.

Key	Type	Description
`small`	string	64px x 64px PNG of the donut.
`medium`	string	100px x 100px PNG of the donut.
`large`	string	180px x 180px PNG of the donut.

Example response

{
    "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",
            "dimensions_publication_id": "pub.1056456453",
            "added_on": 1314135172,
            "published_on": 1314054000,
            "subjects": [
                "science"
            ],
            "readers": {
                "mendeley": -1,
                "downloads": -1
            },        
            "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"
        }
    ]
}

Try it yourself

Click on any of the URLs below to view example responses for the listed scenarios.

Scenario	URL
To return the first 25 research outputs that have been mentioned in the past day	https://api.altmetric.com/v1/citations/1d
And then get the next 25	https://api.altmetric.com/v1/citations/1d?page=2
Get 100 research outputs mentioned in the past week ordered by the altmetric attention score for that week	https://api.altmetric.com/v1/citations/1w?num_results=100
Get 100 research outputs mentioned on Reddit in the past week	https://api.altmetric.com/v1/citations/1w?num_results=100&cited_in=reddit
Get 25 research outputs mentioned on Twitter in the past week ordered by the all time altmetric attention score	https://api.altmetric.com/v1/citations/1w?&cited_in=twitter&order_by=at_score
Get the top 10 research outputs where the score has changed in the last month for the journal History	https://api.altmetric.com/v1/citations/1m?num_results=10&issns=00182648&order_by=score