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:

HTTP status codes:

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.

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.

Response object¶

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

Query object¶

Results object¶

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

Cohorts¶

Cohorts of users who have mentioned the publication on Twitter or on Bluesky.

Context¶

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

Breakdown¶

Available types are all journal similar_age_3m similar_age_journal_3m.

History¶

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

Publisher subjects¶

Subjects for journal set by the publisher.

Readers¶

Images¶

Contains links to PNG versions 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.