Retrieve COUNTER5 Reports with SUSHI

Institutional administrators can retrieve COUNTER5 reports using SUSHI (the Standardized Usage Statistics Harvesting Initiative protocol defined in the ANSI/NISO Z39.93 standard).

To retrieve a report with SUSHI, use the following URL format:

https://{publisher_site}/reports/{report_ID}?{report_parameters}

Reports are returned in JSON format.

COUNTER5 SUSHI Parameters

SUSHI COUNTER5 Parameter Description
{publisher_site} The domain of the publisher's website.
{report_ID} The identifier for the report you want to run. The Counter5 Report Reference provides a list of reports and their identifiers.
Important: Use lowercase for the identifier.
{report_parameters}

The report parameters required depend on the type of report you are requesting.

All reports require customer_id, begin_date, and end_date. Master reports require additional parameters. Refer to the COUNTER_SUSHI5_0 API documentation for a list of the parameters required for each report.

Note: You do not need to provide the platform parameter.

SUSHI Authentication for COUNTER5

The method of authentication for SUSHI access is dependent on where you are located.

If you are making a SUSHI request from within your institution's associated IP range, you need only provide your Customer ID to authenticate.

However, you must provide your Requester ID along with your Customer ID if you:

  • Are outside of the IP range associated with your institution, or
  • Do not have an associated IP range, or
  • Are using a SUSHI client

Example of a SUSHI call from within an IP range

In this example:

  • The Customer ID is 00000000
  • The request is issued from the IP address associated with the customer number
  • The request is for Journal Article Requests, a standard view of the Item Master report, for January through March of 2019
https://www.example.com/reports/ir_a1?customer_id=00000000
&begin_date=2019-01&end_date=2019-03

Example of a SUSHI call from outside an associated IP range

In this example:

  • The Requester ID is [email protected]
  • The Customer ID is 00000000
  • The request is for Platform Usage, a standard view of the Platform Master report, for December of 2018
https://www.example.com/reports/[email protected]
&customer_id=00000000&begin_date=2018-12-01&end_date=2018-12-31

Examples of COUNTER5 SUSHI Retrieval

Examples show how to retrieve a COUNTER5 standard view and a master report.

Retrieving a Standard View Report

Standard views are predefined COUNTER5 reports that require fewer parameters than master reports.

This example assumes:

  • The Literatum site is example.com
  • The Customer ID is 00000000
  • The requester wants to retrieve the Journal Requests (Excluding OA_ Gold) report, also known as TR_J1, for November through December of 2018
  • The requester is within the associated IP range for the institution and, as a result, does not need to provide a Requester ID

URL format:

https://www.example.com/reports/tr_j1?customer_id=00000000&begin_date=2018-11
&end_date=2018-12

Retrieving a Master Report

Master reports are highly customizable and so they require a number of additional parameters. The COUNTER_SUSHI5_0 API documentation provides details of the parameters for each master report. This example assumes:

  • The Literatum site is example.com
  • The Customer ID is 00000000
  • The requester wants to retrieve an Item Master Report for all of 2019, providing details on total article investigations for articles published in 2019 which had controlled access and used the regular access method, and wants the report to show the access method and use a monthly granularity
  • The requester is within the associated IP range for the institution, which means the Requester ID is not required

URL format:

https://www.example.com/reports/ir?customer_id=00000000&begin_date=2019-01-01
&end_date=2019-12-31&metric_type=Total_Item_Investigations&data_type=Article
&yop=2019&access_type=Controlled&access_method=Regular&attributes_to_show
=Access Method&granularity=month