Fetching detailed information about an article or dataset
Fetch detailed alt-metrics information about a particular article or dataset. This call returns much more information about each mention than the standard query calls.
Parameters
| Parameter | Required | Accepts | Description |
| identifier type | Yes | A valid identifier type | Types currently accepted are: doi, handle, pmid, arxiv_id, ads_id, ssrn, repec, id |
| identifier | Yes | A valid identifier of the type specified by identifier type | e.g. the actual DOI, PubMed ID etc. |
| include_sources | No | Comma delimited list of post types to include data for in response. | Defaults to including everything. |
| exclude_sources | No | Comma delimited list of post types to exclude data for in response. | Defaults to exclude nothing. |
| include_sections | No | Comma delimited list of response object sections to include. | Defaults to including everything. Current sections are: counts, citation, altmetric_score, demographics, posts. See descriptions below. |
| post_types | No | Comma delimited list of additional filters on post types. | Defaults to including everything. Current filters are original_tweets. In this case, retweets are excluded from response. Counts section is unaffected. |
Response object
See this knowledgebase article for a walkthrough of the response object.
| Section | Notes |
| counts | Provides number of mentions and unique authors in each relevant source type (e.g. blogs, twitter, news) as well as reference manager reader counts and downloads, where available. |
| citation | Bibliographic metadata about the article in question. You'll find third party identifiers (DOI, arXiv ID etc.) here. |
| altmetric_score | Contains details of the Altmetric score and, where possible, provides some context. |
| demographics | Altmetric categorizes users from some sources based on their posting history and profile information. Counts for each category are included in this section along with geolocation data. |
| posts |
The posts object has post types (blog post, tweet, Facebook wall post etc.) as keys and the posts of that type where a mention was found in arrays of post objects as the values. Titles, snippets and author information are included for each mention when available. Use the include_sources or exclude_sources parameter if you only want details from certain sources. For tweets you'll receive only tweet IDs and user IDs, not the content of the tweet itself or other details about user profiles. You should use tweet IDs to fetch more data from the Twitter API using your own developer account or embed tweets directly on your website. A maximum of 1,500,000 tweet IDs can be retrieved in any rolling 30 day period. Thereafter you'll get an error message: to continue using this call use the exclude_sources parameter to exclude tweets from your results. If you are interested in original tweets, only use post_types parameter to exclude retweets from your results and delay reaching the maximum tweet IDs limit. Note that when fetching and displaying tweets you should be adhering to Twitter's display guidelines and developer policy. |
Example
To return detailed information about the article with ID 2068207:
curl 'https://api.altmetric.com/v1/fetch/doi/10.1038/nature.2014.14583?key=xxx'
Below is a sample API response in JSON format, real responses may contain more keys and more data.
{
"altmetric_id": 2068207,
"counts": {
"readers": {
"mendeley": 0,
"citeulike": 0,
"connotea": 0
},
"facebook": {
"unique_users_count": 865,
"unique_users": [
"Balram Bodhi",
"Carolyn T. Ensley"
],
"posts_count": 897
},
"blogs": {
"unique_users_count": 13,
"unique_users": [
52133,
788
],
"posts_count": 13
},
"googleplus": {
"unique_users_count": 48,
"unique_users": [
"Giovanni Cozzolongo",
"La vuelta a Londres en siete días"
],
"posts_count": 48
},
"news": {
"unique_users_count": 26,
"unique_users": [
"nature",
"phys_org"
],
"posts_count": 29
},
"total": {
"posts_count": 4764
},
"reddit": {
"unique_users_count": 15,
"unique_users": [
"techwrek12",
"Notmyrealname"
],
"posts_count": 15
},
"twitter": {
"unique_users_count": 3583,
"posts_count": 3762
}
},
"citation": {
"title": "Stephen Hawking questions nature of black holes",
"authors": [
"Zeeya Merali"
],
"pubdate": "2014-01-24T00:00:00+00:00",
"doi": "10.1038/nature.2014.14583",
"journal": "Nature",
"altmetric_jid": "4f6fa50a3cf058f610003160",
"links": [
"http://www.nature.com/news/stephen-hawking-questions-nature-of-black-holes-1.14583",
"http://www.nature.com/news/stephen-hawking-there-are-no-black-holes-1.14583?utm_content=buffercd96b&utm_medium=social&utm_source=twitter.com&utm_campaign=buffer"
],
"first_seen_on": "2014-01-24T00:35:57+00:00"
},
"altmetric_score": {
"score": 4115.44,
"score_history": {
"1d": 0,
"2d": 0,
"3d": 0,
"4d": 0,
"5d": 0,
"6d": 0,
"1w": 0,
"1m": 4115.44,
"3m": 4115.44,
"6m": 4115.44,
"1y": 4115.44,
"at": 4115.44
},
"context_for_score": {
"all": {
"rank": 2,
"mean": 27.043795620438,
"median": 8,
"sample_size": 274,
"sparkline": [
4115.44,
40,
32,
8,
8,
8,
1,
1,
0.25,
0
],
"total_number_of_other_articles": 274,
"this_scored_higher_than": 273,
"this_scored_higher_than_pct": 100,
"percentile": 99,
"rank_type": "exact"
},
"similar_age_3m": {
"rank": 2,
"mean": 149.41379310345,
"median": 8,
"sample_size": 29,
"sparkline": [
4115.44,
16,
16,
8,
8,
8,
8,
1,
1,
1
],
"total_number_of_other_articles": 29,
"this_scored_higher_than": 28,
"this_scored_higher_than_pct": 97,
"percentile": 96,
"rank_type": "exact"
},
"this_journal": {
"rank": 2,
"mean": 38.666666666667,
"median": 1,
"sample_size": 114,
"sparkline": [
4115.44,
8,
8,
1,
1,
1,
1,
1,
1,
0.25
],
"total_number_of_other_articles": 114,
"this_scored_higher_than": 113,
"this_scored_higher_than_pct": 100,
"percentile": 99,
"rank_type": "exact"
},
"similar_age_this_journal_3m": {
"rank": 2,
"mean": 191.5,
"median": 8,
"sample_size": 22,
"sparkline": [
4115.44,
8,
8,
8,
8,
8,
1,
1,
1,
1
],
"total_number_of_other_articles": 22,
"this_scored_higher_than": 21,
"this_scored_higher_than_pct": 96,
"percentile": 95,
"rank_type": "exact"
}
}
},
"demographics": {
"users": {
"twitter": {
"cohorts": {
"Members of the public": 3583
}
},
"mendeley": {
"by_status": {
"PhD Student": 367,
"Researcher (at an Academic Institution)": 549
},
"by_discipline": {
"Physics": 734,
"Astronomy": 578
}
}
},
"geo": {
"twitter": {
"US": 357
},
"mendeley": {
"US": 294,
"UK": 143
}
}
},
"posts": {
"twitter": [
{
"citation_ids": [
2068207
],
"author": {
"tweeter_id": "77488855"
},
"tweet_id": "427349187978489856"
},
{
"citation_ids": [
2068207
],
"author": {
"tweeter_id": "390473158"
},
"tweet_id": "427278352768970752"
}
],
"facebook": [
{
"title": "Stephen Hawking: 'There are no black holes'",
"url": "https://www.facebook.com/1288798742/posts/10201402755092686",
"posted_on": "2014-01-25T15:45:32+00:00",
"license": "public",
"author": {
"name": "Balram Bodhi",
"url": "https://www.facebook.com/1288798742",
"facebook_wall_name": false,
"image": "https://graph.facebook.com/1288798742/picture",
"id_on_source": "1288798742"
}
},
{
"title": "Stephen Hawking: 'There are no black holes'",
"url": "https://www.facebook.com/1610593333/posts/10202441295666278",
"posted_on": "2014-01-26T03:19:09+00:00",
"license": "public",
"summary": "Love this brain",
"author": {
"name": "Benjamin Albert",
"url": "https://www.facebook.com/1610593333",
"facebook_wall_name": false,
"image": "https://graph.facebook.com/1610593333/picture",
"id_on_source": "1610593333"
}
}
],
"reddit": [
{
"title": "\"I_call_it_a_Hawking_Hole.\"",
"url": "http://www.reddit.com/r/futurama/comments/1w39qd/i_call_it_a_hawking_hole/",
"posted_on": "2014-01-25T03:40:24+00:00",
"author": {
"id_on_source": "techwrek12"
}
},
{
"title": "Stephen Hawking: 'There are no black holes'",
"url": "http://www.reddit.com/r/EverythingScience/comments/1w4ii7/stephen_hawking_there_are_no_black_holes/",
"posted_on": "2014-01-25T17:12:46+00:00",
"author": {
"id_on_source": "deadlittlepuppy"
}
}
],
"news": [
{
"title": "Stephen Hawking questions nature of black holes",
"url": "http://www.nature.com/news/stephen-hawking-questions-nature-of-black-holes-1.14583",
"posted_on": "2014-01-24T00:00:00+00:00",
"license": "public",
"summary": "Notion of 'event horizon' from which nothing can escape is incompatible with quantum theory, physicist claims.",
"author": {
"name": "Nature",
"url": "http://www.nature.com/nature",
"image": "http://s3.amazonaws.com/weyland.altmetric.com/news_sources/logos/000/000/076/normal/image.png?1369859733"
}
},
{
"title": "Stephen Hawking Challenges Black Hole Theory",
"url": "http://www.realclearscience.com/2014/01/24/stephen_hawking_challenges_black_hole_theory_257193.html?utm_medium=widget&utm_campaign=rss",
"posted_on": "2014-01-24T07:24:45+00:00",
"license": "public",
"summary": "Zeeya Merali, Nature Most physicists foolhardy enough to write a paper claiming that “there are no black holes” — at least not in the sense we usually imagine — would likely be dismissed as cranks. But when the call to redefine these cosmic crunchers comes",
"author": {
"name": "Real Clear Science",
"url": "http://www.realclearscience.com/",
"image": "http://s3.amazonaws.com/weyland.altmetric.com/news_sources/logos/000/000/189/normal/image.png?1369928343"
}
}
],
"googleplus": [
{
"title": "\"This is an interesting reading by the journal \"Nature\", about Black Hole: http://www.nature.com/news...",
"url": "https://plus.google.com/109364519381166351389/posts/YyRPCdarJie",
"posted_on": "2014-01-24T16:29:46+00:00",
"summary": "\"This is an interesting reading by the journal \"Nature\", about Black Hole: http://www.nature.com/news... "This is an interesting reading by the journal "Nature", about Black Hole: http://www.nature.com/news/stephen-hawking-questions-nature-o"
},
{
"title": "Stephen Hawking questions nature of black holes Notion of 'event horizon' from which nothing can escape...",
"url": "https://plus.google.com/117414802027879520048/posts/j3KdBZi6PeE",
"posted_on": "2014-01-24T04:11:38+00:00",
"summary": "Stephen Hawking questions nature of black holes Notion of 'event horizon' from which nothing can escape... Stephen Hawking questions nature of black holesNotion of 'event horizon' from which nothing can escape is incompatible with quantum theory, p"
}
],
"blogs": [
{
"title": "Black Holes No More? Not Quite.",
"url": "http://www.universetoday.com/108561/black-holes-no-more-not-quite/",
"posted_on": "2014-01-24T22:55:00+00:00",
"summary": "Artist concept of matter swirling around a black hole. (NASA/Dana Berry/SkyWorks Digital)\nNature News has announced that there are no black holes. This claim is made by none other than Stephen Hawking, so does this mean black holes are no more? It depend",
"author": {
"id_on_source": "Brian Koberlein"
}
},
{
"title": "Stephen Hawking: “The Absence of Event Horizons Means There are No Black Holes"",
"url": "http://www.dailygalaxy.com/my_weblog/2014/01/stephen-hawking-there-are-no-black-holes.html?utm_source=feedburner&utm_medium=feed&utm_campaign=Feed%3A+TheDailyGalaxyNewsFromPlanetEarthBeyond+%28The+Daily+Galaxy+--Great+Discoveries+Channel%3A+Sci%2C+Space%2C+Tech.%29",
"posted_on": "2014-01-24T18:49:00+00:00",
"summary": " \r\n\r\n \r\nStephen Hawking has set the world of physics back on its heels by reversing his lifetime’s work and a pillar of modern physics claiming that black holes do not exist – saying that the idea of an event horizon, the invisible boundary thought to shro",
"author": {
"id_on_source": "dailygalaxy.com"
}
}
]
},
"score": 4115.44,
"images": {
"small": "https://badges.altmetric.com/?size=64&score=4116&types=mbtttrfg",
"medium": "https://badges.altmetric.com/?size=100&score=4116&types=mbtttrfg",
"large": "https://badges.altmetric.com/?size=180&score=4116&types=mbtttrfg"
}
}