Fetching detailed article level metrics for an article

 

The /fetch call returns detailed article level metrics for a given identifier. In this Solution, we'll walk through the API data returned for this journal article. 

 

You might also want to learn more about human-readable data that's available in Altmetric Details Pages, or to examine the full JSON response for the article from our API in our full technical documentation.

 

A /fetch call made using the DOI for an article returns a response in JSON format whose top level keys are:

  • altmetric_id

  • counts

  • citation

  • altmetric_score

  • demographics

  • posts

 

We'll go through each of these below.


Please note within the API X data will still be referred to as Twitter. This will be updated shortly



Altmetric ID key

 

Each article in the Altmetric database has a unique identifier which we include for reference in the altmetric_id key.


{
    "altmetric_id": 597705
}


Counts key

 

The counts key includes statistics on the number of social media shares, news mentions, online reference manager saves and, where available, downloads for an article (see also Adding download counts to your articles). 

 

Within counts, the downloads key contains download counts for this article on the publisher site and PubMed Central, where applicable.

  • unique_ips is the sum of the unique visitor count to any version of this article (full text, abstract, XML...) since PMC logs began in Jan 2010 or the article's publication date, whichever was more recent. 

  • full_text is the sum of the number of full text views 

  • pdf is the sum of the number of PDF downloads 

  • abstract is the sum of the number of abstract only views 

  • The timeline lists unique_ip counts broken down by month.


    "counts": {
        "downloads": {
            "pmc": {
                "unique_ips": 237,
                "full_text": 253,
                "pdf": 179,
                "abstract": 4,
                "timeline": {
                    "2012-05": "42",
                    "2012-04": "65",
                    "2012-03": "93",
                    "2012-02": "37"
                }
            }

The publisher part of the downloads key contains statistics from the publisher's own platform, where available. Altmetric tries to break down views by full text (full_text), PDF (pdf) and abstract only (abstract). The timeline again breaks total views count down month by month. 


            "publisher": {
                "full_text": 25949,
                "pdf": 2821,
                "abstract": 0,
                "timeline": {
                    "2012-02": 23006,
                    "2012-03": 2221,
                    "2012-04": 1402,
                    "2012-05": 1161,
                    "2012-06": 953,
                    "2012-07": 27
                }
            }
        },


In the readers key you'll find the total number of unique users who have saved this article in Mendeley, CiteULike or Connotea.

 

Note that 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.


        "readers": {
            "mendeley": "22",
            "citeulike": "0",
            "connotea": "0"
        },

The remainder of the counts key covers social media shares and news mentions. 

 

Each source that has mentioned the article gets its own key. In the example below, there have been mentions on Reddit and Twitter.

 

Possible keys are:

  • twitter 

  • facebook 

  • google+ 

  • blogs 

  • news (includes all media mentions) 

  • pinterest 

  • reddit 

  • q&a (includes forums and Stack Exchange based sites) 

  • reviews (includes F1000 reviews and Research Highlight articles in NPG journals)

  • misc (everything else) 


        "total": {
            "posts_count": 502
        },
        "reddit": {
            "unique_users_count": 1,
            "posts_count": 1
        },
        "twitter": {
            "unique_users_count": 353,
            "posts_count": 501
        }

In each case:

  • unique_users_count is simply the count of those users.  

  • posts_count is the number of unique items created by those users that mention this article. 

 

Note that the same user could blog, tweet or otherwise share the same article more than once, so posts_count can be greater than unique_users_count. 

 

Citation key

 

The citation key contains bibliographic metadata about the research output.

  • first_seen_on is the date that Altmetric first tracked a share or mention of this article.  

  • altmetric_jid is an internal database identifier for the journal that the article comes from. 

  • links is an array of URLs that all lead to versions of this article.

  

  "citation": {
        "title": "Potent PPARα Activator Derived from Tomato Juice, 13-oxo-9,11-Octadecadienoic Acid, Decreases Plasma and Hepatic Triglyceride in Obese Diabetic Mice",
        "authors": [
            "Young-il Kim",
            "Shizuka Hirai", ...,
            "Nobuyuki Takahashi",
            "Teruo Kawada"
        ],
        "pubdate": "2012-02-09T00:00:00+00:00",
        "volume": "7",
        "issue": "2",
        "startpage": "e31317",
        "doi": "10.1371/journal.pone.0031317",
        "journal": "PLoS ONE",
        "altmetric_jid": "4f6fa5313cf058f6100043e3",
        "publisher": "Public Library of Science",
        "links": [
            "http://www.plosone.org/article/info%3Adoi%2F10.1371%2Fjournal.pone.0031317", ...,
            "http://dx.plos.org/10.1371/journal.pone.0031317"
        ],
        "first_seen_on": "2012-02-10T02:51:52+00:00",
        "pdf_url": "http://dx.plos.org/10.1371/journal.pone.0031317.pdf"
    },


Altmetric Attention Score key

 

The altmetric_score key carries details of the articles current Altmetric Attention Score and score history. Where possible it also includes information to help apps put that score in context. 

 

  • score is the current Altmetric Attention Score of this article 

  • score_history allows you to see how the score has developed over time. In the example below the article has added:

    • 0.5 to its score in the past month

    • 2.7 in the past three months

    • 307.8 in the past six months

 

  • context_for_score tells you how this score compares to other scores, for example in the entire database (all)  or the same journal (this_journal, in this case PLOS ONE)

    • all contains statistics about the entire Altmetric database

    • this_journal contains statistics about all articles from the same journal that have been tracked by Altmetric

    • similar_age_this_journal_3m contains statistics about articles from the same journal and published within 6 weeks on either side of this one

    • similar_age_3m shows statistics about articles from any journal published within 6 weeks on either side of this one

 

Under each category in context_for_score, we make some other useful data available:

  • mean is the mean score for these articles

  • median is the median score for these articles

  • total_number_of_other_articles is the number of articles in the set

  • sample_size is the size of the representative sample we use to produce the mean and other metrics

  • this_scored_higher_than is the estimated number of articles that have scored the same or lower than this one

  • this_scored_higher_than_pct is the above but expressed as a percentage

  • we split the representative sample in percentiles and put the highest score in each 10% into the sparklines 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.

    "altmetric_score": {
        "score": 307.85,
        "score_history": {
            "1d": 0.5,
            "2d": 0.5,
            "3d": 0.5,
            "4d": 0.5,
            "5d": 0.5,
            "6d": 0.5,
            "1w": 0.5,
            "1m": 0.5,
            "3m": 2.7,
            "6m": 307.85,
            "1y": 307.85,
            "at": 307.85
        },
        "context_for_score": {
            "all": {
                "mean": 2.864,
                "median": 1,
                "sample_size": 10000,
                "sparkline": [514.3,6.76,2.5,1.5,1,1,0.75,0.5,0.25,0.25],
                "total_number_of_other_articles": 627406,
                "this_scored_higher_than": 627278,
                "this_scored_higher_than_pct": "99.98"
            },
            "this_journal": {
                "mean": 3.99,
                "median": 1,
                "sample_size": 10000,
                "sparkline": [991.336,9.08,3.5,2,1.25,1,0.75,0.5,0.25,0.25],
                "total_number_of_other_articles": 12681,
                "this_scored_higher_than": 12678,
                "this_scored_higher_than_pct": "99.98"
            },
            "similar_age_this_journal_3m": {
                "mean": 3.43,
                ...
            },
            "similar_age_3m": {
                "mean": 3.34,
                ...
            }
        }
    },

Demographics key

 

Altmetric derives demographic information from the profiles of people who share links to articles of interest. You can find that information in the demographics key.

 

In the case of Twitter, we look at keywords in profile descriptions, the types of journals that users link to, and friends lists to assign each profile a category. For Twitter, these are:

  • member of the public - somebody who doesn't link to scholarly literature and doesn't otherwise fit any of the categories below 

  • researcher - somebody who is familiar with the literature 

  • practitioner - a clinician, or a researcher working in clinical science 

  • science communicator - somebody who links frequently to scientific articles from a variety of different journals / publishers

 

As of October 2014, we also display Mendeley readership data; specifically we show geographical information and also some demographics (disciplines of scholars, professional statuses of scholars). All readership data pertain to specific articles, and come from the Mendeley API.

 

Note that the poster_types key holding Twitter user categories is now deprecated in favor of users.twitter.cohorts and will be removed from the API in the near future.

 

We also geolocate users based on information in their profiles from corresponding sources. The geo key is a straightforward breakdown of where in the world users who share an article come from, grouped by sharing medium. In the example below the vast majority of people sharing the article on Twitter came from Japan. However, most of the Mendeley readers who saved this article came from the UK.

"demographics": {
        "users": {
            "twitter": {
                "cohorts": {
                    "Members of the public": 280,
                    "Scientists": 211,
                    "Practitioners (doctors, other healthcare professionals)": 1,
                    "Science communicators (journalists, bloggers, editors)": 1
                }
            },
            "mendeley": {
                "by_status": {
                    "Ph.D. Student": 201,
                    "Researcher (at an Academic Institution)": 198,
                    "Student (Bachelor)": 37,
                    "Doctoral student": 2
                },
                "by_discipline": {
                    "Medicine": 172,
                    "Biological Sciences": 59,
                    "Chemistry": 16
                }
            }
        },
        "geo": {
            "twitter": {
                "US": 19,
                "JP": 402,
                "MN": 1,
                "DE": 2,
                "TW": 5,
                "NL": 1,
                "TG": 1,
                "TL": 1,
                "GB": 1,
                "IT": 1,
                "ZZ": 2,
                "CN": 4,
                "CA": 1,
                "FI": 1
            },
            "mendeley": {
                "UK": 372,
                "US": 34,
                "RU": 29
            }
        }
    },

Posts key

 

The posts key contains titles, links, published on dates and snippets for any posts that mention the article. 

 

Each data source gets its own key containing an array of mentions within posts. 

 

With the exception of Twitter each mention has the same format:

  • title - an optional post title, where available (e.g. the title of a blog post) 

  • summary - a snippet for the post, where available (e.g. the first paragraph of a blog post) 

  • url - the link to the post 

  • posted_on - the date that the post was created 

  • author - information about the author of the post - typically a name, portrait and profile link. 

 

X/Twitter posts are treated differently. The Twitter ID and User ID are supplied for the tweet; you must fetch any other information yourself from Twitter using their public APIs and abiding by their terms of service and Developer Policy. If you are going to display the tweet anywhere you should pay particular attention to their display requirements. Please see this article for more information about Twitter data.

 

More information about the Twitter API can be found on their website.


    "posts": {
        "twitter": [
            {
                "tweet_id": "168847676971040768"
            },
            {
                "tweet_id": "169777614855208961"
            }, .... ],
        "reddit": [
            {
                "title": "Chemical derived from tomato juice reduces blood and liver fats associated with obesity.",
                "url": "http://www.reddit.com/r/science/comments/q04fk/chemical_derived_from_tomato_juice_reduces_blood/",
                "posted_on": "2012-02-22T00:26:20+00:00",
                "author": {
                    "id_on_source": "DarwinDanger"
                }
            }
        ]
    }
}

Additional example: Facebook post 

 

Facebook wall posts have an additional field for author information - id_on_source - which contains the Facebook ID for the user or page in question. 


{
    "title": "PLoS Biology: Reconstructing Speech from Human Auditory Cortex",
    "url": "https://www.facebook.com/permalink.php?story_fbid=101980059928665&id=340698088050",
    "posted_on": "2012-02-01T19:05:42+00:00",
    "summary": "I meant to do this.",
    "author": {
        "name": "The L.A.B. Lab",
        "url": "https://www.facebook.com/340698088050",
        "image": "https://graph.facebook.com/340698088050/picture",
        "id_on_source": "340698088050"
    }
}

Additional 


{
    "title": "Hirnströme: Forscher machen Gedanken hörbar",
    "url": "http://www.spiegel.de/wissenschaft/mensch/0,1518,812562,00.html#ref=rss",
    "posted_on": "2012-02-01T07:42:00+00:00",
    "summary": "Filme, die allein aus Gedanken entstanden sind, gibt es bereits - jetzt kommt der Ton dazu. Anhand von Hirnströmen haben Forscher rekonstruiert, was Menschen zuvor gehört haben. Gelähmte könnten so eines Tages wieder eine Stimme bekommen.",
    "author": {
        "name": "Der Speigel",
        "url": "http://www.spiegel.de",
        "image": "http://www.altmetric.com/images/msm_logos/der_spiegel.png"
    }
}