ImpactStory

api & widget

Warning! ImpactStory's performance on your current browser (Internet Explorer) is shady; the examples on this page may display incorrectly or not at all. We're working on it. In the meantime, you can try a supported browser like Firefox, Safari, or Google Chrome.

Recommended approach: JavaScript widget

The easiest way to include ImpactStory metrics on a webpage is via our JavaScript widget, shown below. There are two steps:

  1. Paste this script at the top of your page: 
    <script type="text/javascript" src="http://impactstory.org/embed/v1/impactstory.js"></script>
  2. Paste this div where you want the badges to show. 
    <div class="impactstory-embed" data-id="19210768" data-id-type="pmid" data-api-key="API-DOCS"></div>

To use the widget, get your free API key and embed the widget on your page. Your free API key works to track metrics on 1000 unique products. If you've got more than that, hang in there; we're working to increase this limit as we scale to meet demand.

Example

To the left, you can see the result, embedded live on this page: metrics for a sample article, "Mega-phylogeny approach for comparative biology: an alternative to supertree and supermatrix approaches." Hover over each badge to see a brief description; to dive in deeper, click and you'll reach the item page, which has more details, explanation, and context.

You can embed badges next to multiple items on the same page, which is handy for CVs or tables of contents; for example, here are badges for another article, Multistep correlations via covariance processing of COSY/GCOSY spectra: opportunities and artifacts . You can display badges inline like this by embedding them as a span instead of a div (keeping everything else the same).

Required attributes

The JavaScript widget requires three parameters, which are fed in via data- attributes in the embedded div:

  • data-id uniquely identifies the items you want metrics form. We accept several types of ID, including PubMed IDand DOI. You can also use a url (expressed with http:// prefix) if the only identifier for a research object is its webpage url (SlideShare slides, GitHub software repository, articles without DOIs). If there's another type of identifier you'd like to see supported, let us know; we'll be adding more.
  • data-id-type is the type of identifier you've used; it must be one of doi, pmid, or url.
  • data-api-key is the unique key we've assigned your organization. It's easy and free to get one; just submit a ticket or drop us an email. Of course, since the key will be served along with your page, it's not really secret, but it's helpful for us in debugging and tracking usage.

Optional attributes

You can also customize the display of badges using one of several of optional data- attributes:

AttributeDoesLooks like
data-badge-size

Set to "small" to display smaller badges.
data-badge-type

Set to "icon" to display icons showing engagement type, rather than the word; useful for if you don't have a lot of space. Solid-colored badges still denote 75th percentile.
data-on-finish

The name of a javascript callback to run, defined in the global (window) namespace. The function will be fed two arguments: a dict object that includes all underlaying data used in assigning the badges, and a div$ jQuery object representing this div. For instance, if you define this script: 

countBadges = function(awards, div$) {
   div$.append(
      "<div>" +awards.length+ " badges!</div>"
   )
}
and then include data-on-finish="countBadges" in your ImpactStory div, the countBadges function runs when the badges are done loading.
data-verbose-badges

Set to true to make badges explicitly report the audience they apply to, instead of just relying on color-coding and tooltips.
data-show-logo

Set to false to hide the ImpactStory logo.
data-badge-palette

Set to grayscale for grayscale badges. This makes it impossible to distinguish between scholarly and public badges, so verbose-badges is automatically set to true.
data-show-badges

Set to false to hide the ImpactStory badges. Clicking the logo will still open a new tab showing this item's report page on impactstory.org.

Notes

  • Scopus and CiteULike metrics are not available in the widget.
  • The embed code loads our javascript widget source (this file on GitHub plus bundled libraries), css, images, and makes an analytics logging call.
  • If you've got any feedback, ideas, or questions, let us know!
  • For a slew of extra features, check out phayes's very nice Javascript client library. We'll acutally be rolling some of these into the main codebase presently.

More versatile approach: REST api.

If the JavaScript widget 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.

Documentation for current version of the REST API (/v1).