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.

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",
            "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