Counts

This endpoint provides information about individual research outputs. For example, you can query this endpoint using a DOI and retrieve the relevant Altmetric data. The API is optimized for querying for a single identifier or a strictly defined search.

Request

GET /{version}/{identifier_type}/{id}

Fetch a research output using the supplied identifier type and identifier

Example request:

GET /v1/doi/10.1038/news.2011.490 HTTP/1.1
Host: api.altmetric.com

Query parameters:

Parameter	Required	Accepts	Description
`version`	Yes	`v1`	See Versioning
`identifier type`	Yes	`dimensions_publication_id` `doi` `handle` `pmid` `arxiv` `ads` `ssrn` `repec` `isbn` `id` `nct_id` `urn` `uri`	A valid identifier type.
`identifier`	Yes	A valid identifier of the type specified by `identifier_type`	Identifiers should not be URL-encoded.

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.

Warning

Altmetric IDs are transient and unstable over the medium term. For long term application it is recommended that persistent IDs such as DOIs, arXiv IDs or PMIDs are used instead.

Response object

A GET request to the Counts Only endpoint returns a JSON object with the following keys where available.

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

{
    "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
Fetch a research output by its Altmetric Id	https://api.altmetric.com/v1/id/241939
Fetch a research output by its Dimensions Publication Id	https://api.altmetric.com/v1/dimensions_publication_id/pub.1091500321
Fetch a research output by its Digital Object Identifier	https://api.altmetric.com/v1/doi/10.1038/news.2011.490
Fetch a research output by its PubMed Id	https://api.altmetric.com/v1/pmid/21148220
Fetch a research output by its arXiv Id	https://api.altmetric.com/v1/arxiv/1108.2455
Fetch a research output by its bibcode Id	https://api.altmetric.com/v1/ads/2012apphl.100y3104b
Fetch a research output by its ISBN number	https://api.altmetric.com/v1/isbn/978-3-319-25557-6