Skip to content

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.

Warning

Calls to this endpoint are only available to license holders. If you call this endpoint without an authorized API key you'll get a 403 response. Contact us for pricing or to request use as a non-commercial entity.

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 in JSON format.
400 Bad Request The request was invalid or malformed. Response body is in text format.
403 Forbidden You aren't authorized for this call. All requests require an API key. Response body is in text format.
404 Not Found Altmetric doesn't have any details for the research output or set of research outputs you requested. Response body is in text format.
429 Too Many Requests You are being rate limited. If you haven't already then apply for an API key. Response body is in text format.
502 Bad Gateway The API version you are using is currently down for maintenance. Response body is in text format.

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. Keys are omitted from the response when there is no data for them, so your code should not assume that every key below is present.

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_bluesky_count number Number of Bluesky accounts that have posted this publication.
cited_by_wikipedia_count number Number of wikipedia pages that have cited this publication.
cited_by_policies_count number Number of policy-issuing organizations that have mentioned this publication, counted once per organization however many policy documents mention it.
cited_by_guidelines_count number Number of guideline-issuing organizations that have mentioned this publication, counted once per organization however many guideline documents mention it.
cited_by_patents_count number Number of patents that have mentioned this publication.
cited_by_videos_count number Number of Youtube channels.
cited_by_podcasts_count number Number of podcast shows that have mentioned this publication, counted once per show however many episodes mention it.
cited_by_seminars_count number Number of seminar series that have mentioned this publication, counted once per series however many seminars mention it.
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. Returned unrounded; see Attention Score for the rounding Altmetric applies when displaying it.
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 or on Bluesky.

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 (Deprecated)

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.

Merged records

Altmetric records are occasionally merged when we determine that two records describe the same research output. The merged record is removed and its attention data is combined into the surviving record.

When you request a merged Altmetric ID, the API returns 200 with the surviving record's data and adds a top-level merged_into key. Note that the altmetric_id in the response body is the surviving ID, not the ID you requested.

Key Type Description
altmetric_id number Altmetric ID of the surviving record that the requested record was merged into.

Example response fragment:

{
  "altmetric_id": 182846636,
  "merged_into": {
    "altmetric_id": 182846636
  }
}

The merged_into key is absent for records that have not been merged. An Altmetric ID that has never existed still returns 404.

Tip

If you store Altmetric IDs, use merged_into to detect merges and update your stored ID to the surviving one. This only applies to lookups by Altmetric ID — requests by a persistent identifier such as a DOI, arXiv ID or PMID always resolve to the surviving record directly and therefore never return merged_into. As noted above, we recommend using persistent identifiers rather than Altmetric IDs.

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