ImpactStory logo

api & embed code

recommended approach: embed code

The easiest way to include ImpactStory metrics in a webpage is through embed code. To use the ImpactStory embed code in your webapge, simply include the code below in a webpage, exactly as given, subtituting the placeholder "doi:10.1371/journal.pcbi.1000355" string with your doi or other valid "namespace:id" string.

We plan to refine and simplify this embed code in response to feedback: please let us know what you think, and join the if you'd like to be informed of changes (we're in the process of renaming this).

To use, embed this code on the page that has the item you want to track (currently only works for one item per page). The item's id (url, doi, etc.) goes in the #ti-id span; results will be put in the #ti-data div. 

<script type="text/javascript" src="http://impactstory.it/static/js/total-impact-item.js"></script><span id="ti-id">doi:10.1371/journal.pcbi.1000355</span><div id="ti-data"><!--ImpactStory puts data here--></div>

Here's the code above, embedded live on this page:

doi:10.1371/journal.pcbi.1000355

more versatile approach: REST api.

If the embed code described above doesn't meet your needs, you can use our api directly. The ImpactStory webapp itself is built directly on top of this api.

  • api calls return JSON
  • api calls return return 500 in case of internal error
  • Cross-Origin Resource Sharing (CORS) is enabled
  • after an item has been assigned a ImpactStory id (tiid), ImpactStory will periodically update its metric values.

Here are the API methods:

GET /

Welcome to the API.

returns

A welcome message.

example

curl -i -X GET http://api.impactstory.it{    "contact": "",    "hello": "world",     "message": "Congratulations! You have found the ImpactStory API.",    "moreinfo": "http://total-impact.tumblr.com/",    "version": "jean-claude"}

POST /item/:namespace/:namespaceid

Assign a ImpactStory ID (tiid) to an item if it doesn't have one yet. Returns the assigned tiid.

returns

Return the tiid for the item (return code 201).

example

curl -i -X POST -H "Content-Type: application/json" -d '{}' http://api.total-impact.org/tiid/doi/10.1371/journal.pcbi.1000361"1b2f4fc2bea711e1bdf912313d1a5e63"

GET /tiid/:namespace/:namespaceid

Get the ImpactStory ID (tiid) of an item.

returns

The tiid for an item if one has been previously assigned (return code 303), otherwise an error.

errors

  • 404 if no tiid found for that item

example

curl -i -X GET http://api.impactstory.it/tiid/doi/10.1371/journal.pcbi.1000361"1b2f4fc2bea711e1bdf912313d1a5e63"

GET /item/:tiid

Get the metrics for items, given its ImpactStory ID (tiid).

returns

An item object. Response code 210 if it is currently being updated, 200 otherwise.

errors

  • 404 if no tiid found for an item

example

curl -i -X GET http://api.total-impact.org/item/0df8aa0eb2c911e19e181231381b0f5a{    "_id": "1b2f4fc2bea711e1bdf912313d1a5e63",    "_rev": "251-ddcc8266fa0c9a61035a270ce0c67c84",    "aliases": {        "created": "2012-06-25T09:21:12.272747",        "doi": [            "10.1371/journal.pcbi.1000361"        ],        "last_modified": "2012-07-29T02:00:34.889973",        "title": [            "Adventures in Semantic Publishing: Exemplar Semantic Enhancements of a Research Article"        ],        "url": [            "http://www.ncbi.nlm.nih.gov/pubmed/19381256",            "http://dx.plos.org/10.1371/journal.pcbi.1000361",            "http://dx.doi.org/10.1371/journal.pcbi.1000361"        ]    },    "biblio": {        "authors": "Shotton, Portwin, Klyne, Miles",        "genre": "article",        "h1": "Adventures in Semantic Publishing: Exemplar Semantic Enhancements of a Research Article",        "journal": "PLoS Comput Biol",        "title": "Adventures in Semantic Publishing: Exemplar Semantic Enhancements of a Research Article",        "year": 2009    },    "created": "2012-06-25T09:21:12.272733",    "currently_updating": false,    "last_modified": "2012-06-25T09:21:12.272733",    "metrics": {        "citeulike:bookmarks": {            "provenance_url": "http://www.citeulike.org/doi/10.1371/journal.pcbi.1000361",            "static_meta": {                "description": "Number of users who have bookmarked this item.",                "display_name": "bookmarks",                "icon": "http://citeulike.org/favicon.ico",                "provider": "CiteULike",                "provider_url": "http://www.citeulike.org/"            },            "values": {                "nih": [                    91,                    99                ],                "raw": 59            }        },        "delicious:bookmarks": {            "provenance_url": "http://www.delicious.com/url/5c760b706cde2538e558e8643da51ac4",            "static_meta": {                "description": "The number of bookmarks to this artifact (maximum=100).",                "display_name": "bookmarks",                "icon": "http://www.delicious.com/favicon.ico",                "provider": "Delicious",                "provider_url": "http://www.delicious.com/"            },            "values": {                "raw": 1            }        },...}

POST /collection

Create a collection given a list of ImpactStory IDs.

input data

{ aliases:[ ["namespace1", "id1"], ["namespace1", "id2"], ...] title: "My Collection", owner:{} }

returns

The collection header information

errors

  • 404 if not found

example

GET /collection/:collectionId [?include_items=false] [.csv]

Get the items and metadata associated with a given collection

returns

A collection object, which includes both collection metadata and the items in the collection (pass include_items=false to leave the items out). Format is json by default, but appending .csv returns a csv file, with one row per item.

return codes

  • 404 if not found
  • 200 if all the collections objects are found and are done updating.
  • 210 if all the collection's objects are found, but some are still updating.
  • (not sure of code yet) if one of the items is not found.

example

curl -i -X GET http://api.total-impact.org/collection/8iwgwi{    "_id": "kn5auf",    "_rev": "8-69fdd2a34464f0ca9d02748ef057b1e8",    "created": "2012-06-25T09:21:12.673503",    "items": [        {            "_id": "dr3nrhlex36g9xy4idyn7v3f",            "_rev": "164-9631084108ed21dc56fa0e26b6a91fe6",            "aliases": {                "doi": [                    "10.1371/journal.pbio.1000056"                ],                "pmid": [                    "19278298"                ],                "title": [                    "Amazonian Amphibian Diversity Is Primarily Derived from Late Miocene Andean Lineages"                ],                "url": [                    "http://biology.plosjournals.org/perlserv/?request=get-document&doi=10.1371%2Fjournal.pbio.1000056",                    "http://www.pubmedcentral.nih.gov/articlerender.fcgi?artid=2653552&tool=pmcentrez&rendertype=abstract",                    "http://www.ncbi.nlm.nih.gov/pubmed/19278298"                ]            },            "biblio": {                "authors": "Santos, Coloma, Summers, Caldwell, Ree, Cannatella",                "genre": "article",                "journal": "Plos Biol",                "title": "Amazonian Amphibian Diversity Is Primarily Derived from Late Miocene Andean Lineages",                "year": 2009            },            "created": "2012-08-02T14:56:14.151655",            "currently_updating": false,            "last_modified": "2012-08-02T14:56:14.151655",            "metrics": {                "mendeley:career_stage": {...

GET /provider

Get all metadata for the providers.

returns

A dictionary of providers and their metadata.

errors

  • 404 if not found

example

curl -i -X GET http://api.impactstory.it/provider{    "bibtex": {        "descr": "",         "provides_aliases": false,         "provides_metrics": false,         "url": ""    },     "citeulike": {        "descr": "CiteULike is a free service to help you to store, organise and share the scholarly papers you are reading.",         "metrics": {            "bookmarks": {                "description": "Number of users who have bookmarked this item.",                 "display_name": "bookmarks",                 "icon": "http://citeulike.org/favicon.ico",                 "provider": "CiteULike",                 "provider_url": "http://www.citeulike.org/"            }        },         "provides_aliases": false,         "provides_metrics": true,         "url": "http://www.citeulike.org/"    },     "crossref": {        "descr": "An official Digital Object Identifier (DOI) Registration Agency of the International DOI Foundation.",         "provides_aliases": true,         "provides_metrics": false,         "url": "http://www.crossref.org/"    },     "delicious": {        "descr": "Online social bookmarking service",         "metrics": {            "bookmarks": {                "description": "The number of bookmarks to this artifact (maximum=100).",                 "display_name": "bookmarks",                 "icon": "http://www.delicious.com/favicon.ico",                 "provider": "Delicious",                 "provider_url": "http://www.delicious.com/"            }        },         "provides_aliases": false,         "provides_metrics": true,         "url": "http://www.delicious.com"    },     "dryad": {        "descr": "An international repository of data underlying peer-reviewed articles in the basic and applied biology.",         "metrics": {            "most_downloaded_file": {                "description": "Dryad most downloaded file: number of downloads of the most commonly downloaded data package component",                 "display_name": "most downloaded file",                 "icon": "http:\\/\\/datadryad.org\\/favicon.ico",                 "provider": "Dryad",                 "provider_url": "http:\\/\\/www.datadryad.org\\/"            },             "package_views": {                "description": "Dryad package views: number of views of the main package page",                 "display_name": "package views",                 "icon": "http:\\/\\/datadryad.org\\/favicon.ico",                 "provider": "Dryad",                 "provider_url": "http:\\/\\/www.datadryad.org\\/"            },             "total_downloads": {                "description": "Dryad total downloads: combined number of downloads of the data package and data files",                 "display_name": "total downloads",                 "icon": "http:\\/\\/datadryad.org\\/favicon.ico",                 "provider": "Dryad",                 "provider_url": "http:\\/\\/www.datadryad.org\\/"            }        },         "provides_aliases": true,         "provides_metrics": true,         "url": "http://www.datadryad.org"    },     ...     "wikipedia": {        "descr": "The free encyclopedia that anyone can edit.",         "metrics": {            "mentions": {                "description": "The number of Wikipedia articles that mentioned this object.",                 "display_name": "mentions",                 "icon": "http://wikipedia.org/favicon.ico",                 "provider": "Wikipedia",                 "provider_url": "http://www.wikipedia.org/"            }        },         "provides_aliases": false,         "provides_metrics": true,         "url": "http://www.wikipedia.org/"    }}