Using the ALM API

Article-Level Metrics RESTful API

The Article-Level Metrics application provides a RESTful API for accessing article information. RESTful API URLs generally correspond to HTML URLs. You can usually add “.xml” or “.json” to the HTML (unsuffixed) URL and perform a GET request. Both XML and JSON formats are provided, although the attribute arrangement might be different between the two formats (and might differ from the information included in the HTML presentation generated without the format suffix).

Retrieving Data for a Single Article

To retrieve data for a single article, the following parameters can be passed to the API:

Options:

  • source=(name) – Only include one source’s information. Here is the list of currently available sources
  • events=1 – Also include the individual citing document URIs, grouped by source.
  • history=1 – Also include a historical record of citation counts per month (cumulative), grouped by source.
  • api_key – Your PLoS API key. To obtain a key, please register for a key.
  • (Deprecated in ALM 2.0)citations=1 – Also include the individual citing document URIs, grouped by source.

Formats:

  • .xml – Returns an data in XML format.
  • .json – Returns an data in JSON format. Support for JSONP is included by using the “callback” parameter in the request.
  • .csv – Returns an data in CSV format.

Examples for Retrieving Single Articles

1. For article journal.pbio.0000012, return data for the source “CrossRef” in XML format:
alm.plos.org/articles/info:doi%2F10.1371%2Fjournal.pbio.0000012.xml?source=CrossRef&api_key=plos_api_test

2. For article journal.pbio.0000012, return the history for the source “Counter” in CSV format:
alm.plos.org/articles/info:doi%2F10.1371%2Fjournal.pbio.0000012.csv?history=1&source=Counter&api_key=plos_api_test

More examples are available at Article-Level Metrics Examples.

Retrieving Data for Multiple Articles

The Article-Level Metrics API can be used to retrieve data for a subset of articles or all articles. Retrieving data for all articles aren’t intended for high-volume use and can take several seconds to execute. If these are the types of requests that you will be performing, please contact us at api@plos.org to discuss your options.

To retrieve data for multiple articles, the following parameters can be passed to the API:

  • cited=1,0 – If set to “1″, then the results only include articles that have at least one citation. If set to “0″, then only the results only include articles that have no citations.
  • query=journal.pbio – Only include articles whose DOI includes this substring. This turns a query into a “like %journal.pbio%” query.
  • order=doi,published_on – Sort the results. Options include “doi” and “published_on”.
  • page=# – Return results from page #. 30 results are returned per page.
  • api_key – Your PLoS API key. To obtain a key, please register for a key.

Formats:

  • .xml – Returns an data in XML format.
  • .json – Returns an data in JSON format. Support for JSONP is included by using the “callback” parameter in the request.
  • .csv – Returns an data in CSV format.

An Example for Retrieving Multiple Articles

1. For all articles published in PLoS Biology, return PubMed Central citation counts for all articles with citations, ordered by DOI, in XML format:
alm.plos.org/articles.xml?query=journal.pbio&cited=1&order=doi&api_key=plos_api_test

Note:This query returns the first 30 results. To get the next 30 results, add the page=# parameter. For example, to return the next 30 results:
alm.plos.org/articles.xml?query=journal.pbio&cited=1&order=doi&page=2&api_key=plos_api_test

More examples are available at Article-Level Metrics Examples.

RESPONSE ATTRIBUTES

Every article stored in Article-Level Metrics has the following attributes. These attributes will be returned with every request:

  • doi - The article’s DOI.
  • pub_med - The article’s PubMed ID. This attribute may not be immediately available for recently published articles.
  • pub_med_central - The article’s PubMed Central ID. This attribute may not be immediately available for recently published articles.
  • title - The title of the article.
  • events_count - The sum of count attribute of all individual sources.
  • published - The publication date of the article in datetime format. Example: ”2009-07-08T00:00:00-07:00″
  • (Deprecated in ALM 2.0) citations_count - The total number of data points that we’ve recorded for this article from all sources.
  • (Deprecated in ALM 2.0) updated_at - A timestamp representing the date when data from any source was last retrieved for the article.