Fetching detailed article level metrics for an article


The /fetch call returns detailed article level metrics for a given identifier. Let's walk through the data returned for this article (see also the human readable details page or some actual JSON output, which can be downloaded as "response.json" at the bottom of this article):


Potent PPARα Activator Derived from Tomato Juice, 13-oxo-9,11-Octadecadienoic Acid, Decreases Plasma and Hepatic Triglyceride in Obese Diabetic Mice  (PLoS ONE) 


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

  • altmetric_id
  • counts
  • selected_quotes
  • citation
  • altmetric_score
  • demographics
  • posts

We'll go through each of these below.


Altmetric ID key


{
    "altmetric_id": 597705,


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


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. 


Selected quotes key


Altmetric tries to identify 'interesting' snippets of conversations about articles - these can sometimes be useful in putting the article in context.

Your mileage may vary: to a great extend the usefulness of the selected quotes system depends on the number and type of people talking about the article.

    "selected_quotes": [
        "Tomatoes are nearly sold out in Japan?",
        "And the price of tomato juice is expected to spike after this hits the news",
        "This is the link of the original article regarding tomato juice effects if you are interested in. ;) =",
        "Potent PPARα Activator Derived from Tomato Juice, 13-oxo-9,11-Octadecadienoic Acid...  "
    ],


Citation key


The citation key contains bibliographic metadata about the article. 


  • 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 in the entire database (all) and the same journal (this_journal, in this case PLoS ONE) 

    • all contains statistics about the entire Altmetric database. 

      • mean is the mean score for these articles, median is the median andtotal_number_of_other_articles is the number of articles in the set. We take representative samples to produce to mean etc. - the size of that sample is in sample_size.
      • we split the representative sample in percentiles and put the highest score in each 10% into thesparklines 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.
      • 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.
    • 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.


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

I

n 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 favour ofusers.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. 

Twitter posts are treated differently. Altmetric supplies the date on which the mention was added to our database  (in the posted_on field) and Twitter ID for the tweet; you must fetch any other information yourself from Twitter using their public APIs and abiding by their T&Cs. If you are going to display the tweet anywhere you should pay particular attention to their display requirements.
 
More information about the Twitter API can be found here:
 
REST API documentation


Twitter Developer Rules of the Road 


    "posts": {
        "twitter": [
            {
                "posted_on": "2012-02-13T00:03:17+00:00",
                "tweet_id": "168847676971040768"
            },
            {
                "posted_on": "2012-02-15T13:38:32+00:00",
                "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 example: News


{
    "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"
    }
}