API Version 0

1. Limits and authentication

The REST API gives anyone free, programmatic access to all of our data. There's no rate limit, but if you need more than 100k calls/day you may want to download the datasets instead.

Requests must include your email, so that we can get in touch if something breaks, and so we can report usage to our funders. Add the email as a parameter at the end of the URL, like this: ?email=YOUR_EMAIL.

If you're using the API, we recommend you subscribe to the mailing list in order to stay up-to-date when there are changes or new features.

2. Endpoints

GET /
Description Gets an API status object that describes this API.
Returns API Status object
Example https://api.paperbuzz.org/v0/?email=test@example.com
GET /:doi
Description Gets attention metrics, metadata, and open access status for a given DOI-assigned resource.
Accepts A valid DOI.
Returns DOI object
Example https://api.paperbuzz.org/v0/doi/10.1038/nature12373?email=test@example.com

3. Response objects

These are the JSON objects returned by the API.

3.1 API Status object

Describes status of this API.

documentation_url String Where you can find documentation for this version.
msg String Relevant messages.
version String Version string. Example: 0.0.1

3.2 DOI object

This is the main response object for the API, used for reporting the altmetrics and other information about a given DOI.

altmetrics_sources List List of AltmetricsSource objects.

Empty list if there are no online impact events for this article.

crossref_event_data_url String URL you can use to query the Crossref Event Data API for this article.

This is the query we used to obtain all the altmetrics data in a given response. So this URL can be used as part of a provenance chain for the data.

doi String The DOI of this resource. This is always lowercase.
metadata Object DOI metadata as reported by the Crossref API. Includes title, authors, and so on. The response format is the same as what the Crossref API returns, so see the Crossref API docs for details.
open_access Object Open Access information as reported by the oaDOI API. Reports any locations where the article can legally be read free of charge. The response format is the same what the oaDOI API returns, so see the oaDOI API docs for more details.

3.3 AltmetricsSource object

Describes online mentions of a DOI from certain altmetrics source (for example, Twitter or Reddit are both sources).

events List List of Event objects.

events_count Integer The number of Event objects.

Convenience property, same as events.length

first_event_date String Date of the first event found. Represented as an ISO8601 timestamp.
events_count_by_day List List of objects describing event counts binned by day. Each day is represented by its own object, which has two properties: count and date (represented as an ISO8601 timestamp). Days with zero events are not included.
events_count_by_month List List of objects describing event counts binned by month. Each day is represented by its own object, which has two properties: count and date (represented as an ISO8601 timestamp). Months with zero events are not included.
events_count_by_year List List of objects describing event counts binned by year. Each day is represented by its own object, which has two properties: count and date (represented as an ISO8601 timestamp). Years with zero events are not included.
source_id String Name of this source. We use the names defined by the Crossref Event Data schema. Also represented in the source object, but maintained here for backwards compability.
source List Source details. The source object has three properties:
source_id is the name of the source as defined by the Crossref Event Data schema. .
display_name is a properly formatted source name for display to end users in a client application or GUI.
icon_url returns an image link to the source logo or watermark icon.

3.4 Event object

Describes a time when someone interacted with DOI-assigned resource by mentioning it or linking to it online. For example, a tweet is an Event; so is a Reddit post. This Event object is a simplified version of the Event object served by the Crossref Event Data API.

author String Name of author.

Where possible, this string is a URL. For Twitter, for example, it's a URL pointing to the author's Twitter profile.

occurred_at String Time the event occured. Represented as an ISO8601 timestamp.
url String Location of the event. For example, if this Event is a tweet, this URL would resolve to the tweet itself. This is the end of the provenance chain for altmetrics counts, since users can see and read the invocation of a given DOI, here at this URL.