SUSHI help
The COUNTER_SUSHI API base URL for this service is https://www.annualreviews.org/counter5/sushi, the COUNTER documentation explains how this should be used to construct the URL for SUSHI requests and some worked examples are provided below.
Counter 5.1
The COUNTER documentation has a detailed description of each of the requests, but they can broadly be split into three categories, firstly the status call which requires no parameters:
| Report name | Path | Description |
|---|---|---|
| Server Status | /r51/status | Returns the current status of the reporting service(s) supported by the COUNTER API server. |
To construct a status call you merely need to combine the base URI (https://www.annualreviews.org/counter5/sushi) and the path (/r51/status), giving you https://www.annualreviews.org/counter5/sushi/r51/status.
The remaining COUNTER_SUSHI API are secured using a combination of customer_id and requestor_id - find your institution's customer_id and requestor_id here.
There are two calls which require just these two fields:
| Report name | Path | Description |
|---|---|---|
| Report List | /r51/reports | Returns the list of available reports, including the date range we hold data for |
| Member List | /r51/members | Members, the list of consortium members related to your customer ID |
If your requestor_id is R001 and your customer_id is C001 and you wanted the report list you would need to combine the base URI (https://www.annualreviews.org/counter5/sushi), the path (/r51/reports) and your requestor_id/customer_id (?requestor_id=R001&customer_id=C001), giving you https://www.annualreviews.org/counter5/sushi/r51/reports?requestor_id=R001&customer_id=C001.
The final type of calls are the reports, in addition to customer_id and requestor_id these require a begin_date (yyyy-MM) and end_date (yyyy-MM).
| Report name | Path | Description |
|---|---|---|
| PR - Platform Report | /r51/pr | A platform report shows usage aggregated across the entire site, this lets you see your general level of usage of the site as a whole. |
| PR_P1 - Platform Usage | /r51/pr_p1 | A standard platform report showing your basic usage. |
| TR - Title Report | /r51/tr | A title report breaks the usage down to individual titles, you can see which titles your users are reading or would like to read. |
| TR_J1 - Journal Requests (Controlled) | /r51/tr_j1 | A title report for journals, showing usage of books you have a subscription to, excluding free and open access. |
| TR_J2 - Journal Requests (Controlled) | /r51/tr_j2 | A title report for journals, showing books your users wanted to read but weren't able to because of access restrictions. |
| TR_J3 - Journal Usage by Access Type | /r51/tr_j3 | A title report for books broken down by access type (i.e. Controlled, Open, Free_To_Read). |
| TR_J4 - Journal Requests by YOP (Controlled) | /r51/tr_j4 | A title report for journal access broken down by year of publication, this gives you the details necessary to analyze usage of content in backfiles or covered by perpetual access agreement. |
| IR - Item Report | /r51/ir | A title report breaks the usage down to individual items, i.e. chapters or articles. |
| IR_A1 - Journal Article Requests | /r51/ir_a1 | A journal specific item report. |
The process for generating a SUSHI report request is the same as before but this time we also need a begin_date and end_date, you require an IR - Item Report for January 2025 you would create a URL like this https://www.annualreviews.org/counter5/sushi/r51/reports/ir?requestor_id=R001&customer_id=C001&begin_date=2025-01&end_date=2025-01.
Full details of COUNTER_SUSHI 5.1 are available here.
COUNTER_SUSHI is designed for automated retrieval of statistics into other software, the results of these reports are not primarily designed to human readable, COUNTER also supports tabular reports which you will be able to easily review in Excel - these are available in the Administration section.
Counter 5.0
The COUNTER documentation has a detailed description of each of the requests, but they can broadly be split into three categories, firstly the status call which requires no parameters:
| Report name | Path | Description |
|---|---|---|
| Server Status | /status | Returns the current status of the reporting service(s) supported by the COUNTER API server. |
To construct a status call you merely need to combine the base URI (https://www.annualreviews.org/counter5/sushi) and the path (/status), giving you https://www.annualreviews.org/counter5/sushi/status.
The remaining COUNTER_SUSHI API are secured using a combination of customer_id and requestor_id - find your institution's customer_id and requestor_id here.
There are two calls which require just these two fields:
| Report name | Path | Description |
|---|---|---|
| Report List | /reports | Returns the list of available reports |
| Member List | /members | Members, the list of consortium members related to your customer ID |
If your requestor_id is R001 and your customer_id is C001 and you wanted the report list you would need to combine the base URI (https://www.annualreviews.org/counter5/sushi), the path (/reports) and your requestor_id/customer_id (?requestor_id=R001&customer_id=C001), giving you https://www.annualreviews.org/counter5/sushi/reports?requestor_id=R001&customer_id=C001.
The final type of calls are the reports, in addition to customer_id and requestor_id these require a begin_date (yyyy-MM) and end_date (yyyy-MM).
| Report name | Path | Description |
|---|---|---|
| PR - Platform Report | /pr | A platform report shows usage aggregated across the entire site, this lets you see your general level of usage of the site as a whole. |
| PR_P1 - Platform Usage | /pr_p1 | A standard platform report showing your basic usage. |
| TR - Title Report | /tr | A title report breaks the usage down to individual titles, you can see which titles your users are reading or would like to read. |
| TR_J1 - Journal Requests (Controlled) | /tr_j1 | A title report for journals, showing usage of books you have a subscription to, excluding free and open access. |
| TR_J2 - Journal Requests (Controlled) | /tr_j2 | A title report for journals, showing books your users wanted to read but weren't able to because of access restrictions. |
| TR_J3 - Journal Usage by Access Type | /tr_j3 | A title report for books broken down by access type (i.e. Controlled, Open, Free_To_Read). |
| TR_J4 - Journal Requests by YOP (Controlled) | /tr_j4 | A title report for journal access broken down by year of publication, this gives you the details necessary to analyze usage of content in backfiles or covered by perpetual access agreement. |
| IR - Item Report | /ir | A title report breaks the usage down to individual items, i.e. chapters or articles. |
| IR_A1 - Journal Article Requests | /ir_a1 | A journal specific item report. |
The process for generating a SUSHI report request is the same as before but this time we also need a begin_date and end_date, you require an IR - Item Report for January 2025 you would create a URL like this https://www.annualreviews.org/counter5/sushi/reports/ir?requestor_id=R001&customer_id=C001&begin_date=2025-01&end_date=2025-01.
Full details of COUNTER_SUSHI 5.0 are available here.
COUNTER_SUSHI is designed for automated retrieval of statistics into other software, the results of these reports are not primarily designed to human readable, COUNTER also supports tabular reports which you will be able to easily review in Excel - these are available in the Administration section.
The COUNTER specification only mandates COUNTER 5.0 support until April 2025, if possible you should migrate to COUNTER 5.1.