APIs in IRUS are implemented using a REST model implemented over HTTPS.
- The Custom IRUS API returns reports from the COUNTER-conformant data in IRUS with additional custom content, and these reports can be output as JSON, or in tabular form (using either comma or tab separated variables.)
- The IRUS-OAPEN API is like the Custom IRUS API though also returns some OAPEN specific content.
The following hold true for all APIs:
- Requests are submitted using HTTPS GET
- Requests and responses can contain Unicode characters
- Request parameters must be URL-encoded
- Requests must include an institution specific Requestor_ID - to obtain a Requestor_ID please contact our helpdesk with 'IRUS API' as the subject.
Custom IRUS API
Request Syntax
Following the REST model, the Custom IRUS API request uses the following general syntax:
{BaseURL}/{Path}?{Report_Parameters}
where:
{BaseURL}:https://irus.jisc.ac.uk/api/irus{Path}: always required and determines the operation that the API will carry out. Available paths are:/reports/[report_id]
{Report_Parameters}: a list of parameters as dictated by the path (operation).
The following sections give further details for each supported path:
/reports/irus_pr
This path returns a custom Platform Master Report for a specific repository (defined by the platform parameter).
Request parameters
| Parameter | Mandatory or optional | Description |
|---|---|---|
| requestor_id | Mandatory | Identifies who is making the request - to obtain a Requestor_ID please contact our helpdesk with 'IRUS API' as the subject. |
| platform | Mandatory | IRUS identifier of the repository (Platform) for which the data is being requested. Possible values can be seen in the Repository_ID column of the Participants table. |
| begin_date | Mandatory | Usage start date in the form of yyyy-mm |
| end_date | Mandatory | Usage end date in the form of yyyy-mm |
| country_code | Optional | Optional Report Filter to limit usage to customers from a specified country by supplying an ISO 3166 Alpha-2 code, e.g., GB for United Kingdom of Great Britain and Northern Ireland (the), and AU for Australia. Multiple values are delimited with a | character. Omitting this parameter will return statistics for users anywhere in the world that have usage. |
| irus_type_id | Optional | Optional Report Filter. Permitted parameter values are IRUS item type ids, as can be seen in the Item_Type_ID column of the Item Types table. Multiple values are delimited with a | character. Omitting this parameter will return statistics for items with any IRUS item type that have usage. |
| metric_type | Optional | Optional Report Filter. A list of Metric_Types to return. Multiple values are delimited with a | character. Omitting this parameter will return statistics for all metric_types with usage. |
| attributes_to_show | Optional | Optional Report Attribute. A list of attributes to include as separate elements in response (usage will be broken out by attribute values). Multiple attribute names are delimited with a | character. Options are Country and Irus_Item_Type. When fields are included usage will be presented for each value of that field (with usage) otherwise usage will be rolled up for all values of a given field. |
| granularity | Optional | Optional Report Attribute. Include this parameter to allow usage to be retrieved with a granularity of 'month' (default if omitted) or 'totals' |
| content_type | Optional | Optional Report Attribute. Permitted values are: json, csv or txt (where txt returns a tabular report with tab-separated values). Omitting this attribute will return JSON. |
| pretty | Optional | Only for use with the JSON format. Presents the JSON response in a human-readable form for viewing in a browser while testing. DO NOT USE in production requests. |
Note: Parameters may be provided in any order.
Examples
-
Custom Platform Master Report, with no optional Filters or Attributes_To_Show:
[JSON]
https://irus.jisc.ac.uk/api/irus/reports/irus_pr/?requestor_id={institutional Requestor_ID}&platform={IRUS Repository_ID}&begin_date=2020-01&end_date=2020-02&pretty[CSV]https://irus.jisc.ac.uk/api/irus/reports/irus_pr/?requestor_id={institutional Requestor_ID&platform={IRUS Repository_ID}&begin_date=2020-01&end_date=2020-02&content_type=csv -
Custom Platform Master Report, with usage split by IRUS Item_Type (view the Item types policy for details of IRUS Item_Types):
[JSON]
https://irus.jisc.ac.uk/api/irus/reports/irus_pr/?requestor_id={institutional Requestor_ID}&platform={IRUS Repository_ID}&begin_date=2020-01&end_date=2020-02&attributes_to_show=Irus_Item_Type&pretty -
Custom Platform Master Report, with usage for just the Article and Book IRUS Item_Types (view the Item Types table for relevant details):
[CSV]
https://irus.jisc.ac.uk/api/irus/reports/irus_pr/?requestor_id={institutional Requestor_ID}&platform={IRUS Repository_ID}&begin_date=2020-01&end_date=2020-02&irus_type_id=2|4&content_type=csv -
Custom Platform Master Report, with usage split by country:
[JSON]
https://irus.jisc.ac.uk/api/irus/reports/irus_pr/?requestor_id={institutional Requestor_ID}&platform={IRUS Repository_ID}&begin_date=2020-01&end_date=2020-02&attributes_to_show=Country&pretty -
Custom Platform Master Report, for usage from just Australia (AU):
[TXT]
https://irus.jisc.ac.uk/api/irus/reports/irus_pr/?requestor_id={institutional Requestor_ID}&platform={IRUS Repository_ID}&begin_date=2020-01&end_date=2020-02&country_code=AU&content_type=txt -
Custom Platform Master Report, with all optional Attributes_To_Show values:
[JSON]
https://irus.jisc.ac.uk/api/irus/reports/irus_pr/?requestor_id={institutional Requestor_ID}&platform={IRUS Repository_ID}&begin_date=2020-01&end_date=2020-02&attributes_to_show=Irus_Item_Type|Country&pretty
/reports/irus_ir
This path returns a custom Item Master Report for a specific repository (defined by the platform parameter).
Request parameters
| Parameter | Mandatory or optional | Description |
|---|---|---|
| requestor_id | Mandatory | Identifies who is making the request - to obtain a Requestor_ID please contact our helpdesk with 'IRUS API' as the subject. |
| platform | Mandatory | IRUS identifier of the repository (Platform) for which the data is being requested. Possible values can be seen in the Repository_ID column of the Participants table. |
| begin_date | Mandatory | Usage start date in the form of yyyy-mm |
| end_date | Mandatory | Usage end date in the form of yyyy-mm |
| country_code | Optional | Optional Report Filter to limit usage to customers from a specified country by supplying an ISO 3166 Alpha-2 code, e.g., GB for United Kingdom of Great Britain and Northern Ireland (the), and AU for Australia. Multiple values are delimited with a | character. Omitting this parameter will return statistics for users anywhere in the world that have usage. |
| irus_type_id | Optional | Optional Report Filter. Permitted parameter values are IRUS item type ids, as can be seen in the Item_Type_ID column of the Item Types table. Multiple values are delimited with a | character. Omitting this parameter will return statistics for items with any IRUS item type that have usage. |
| item_id | Optional | Optional Report Filter to limit usage to a single item. Permitted parameter values are IRUS item identifier, DOI or OAI identifier. Omitting this parameter will return statistics for all items with usage. |
| metric_type | Optional | Optional Report Filter. A list of Metric_Types to return. Multiple values are delimited with a | character. Omitting this parameter will return statistics for all metric_types with usage. |
| yop | Optional | Optional Report Filter. Permitted parameter values are any valid 4-digit year. Limits returned statistics to the items published in the requested year(s). Multiple values are delimited with a | character. Omitting this parameter will return statistics for all available years of publication with usage. |
| attributes_to_show | Optional | Optional Report Attribute. A list of attributes to include as separate elements in response (usage will be broken out by attribute values). Currently the only option is Country. When fields are included usage will be presented for each value of that field (with usage) otherwise usage will be rolled up for all values of a given field. |
| granularity | Optional | Optional Report Attribute. Include this parameter to allow usage to be retrieved with a granularity of 'month' (default if omitted) or 'totals' |
| content_type | Optional | Optional Report Attribute. Permitted values are: json, csv or txt (where txt returns a tabular report with tab-separated values). Omitting this attribute will return JSON. |
| pretty | Optional | Only for use with the JSON format. Presents the JSON response in a human-readable form for viewing in a browser while testing. DO NOT USE in production requests. |
Note: Parameters may be provided in any order.
Examples
-
Custom Item Master Report, with no optional Filters or Attributes_To_Show:
[JSON]
https://irus.jisc.ac.uk/api/irus/reports/irus_ir/?requestor_id={institutional Requestor_ID}&platform={IRUS Repository_ID}&begin_date=2020-01&end_date=2020-02&pretty[CSV]https://irus.jisc.ac.uk/api/irus/reports/irus_ir/?requestor_id={institutional Requestor_ID}&platform={IRUS Repository_ID}&begin_date=2020-01&end_date=2020-02&content_type=csv -
Custom Item Master Report, with usage for just the Article and Book IRUS Item_Types (view the Item Types table for relevant details):
[TXT]
https://irus.jisc.ac.uk/api/irus/reports/irus_ir/?requestor_id={institutional Requestor_ID}&platform={IRUS Repository_ID}&begin_date=2020-01&end_date=2020-02&irus_type_id=2|4&content_type=txt -
Custom Item Master Report, with usage split by country:
[JSON]
https://irus.jisc.ac.uk/api/irus/reports/irus_ir/?requestor_id={institutional Requestor_ID}&platform={IRUS Repository_ID}&begin_date=2020-01&end_date=2020-02&attributes_to_show=Country&pretty -
Custom Item Master Report, for usage from just Australia (AU):
[CSV]
https://irus.jisc.ac.uk/api/irus/reports/irus_ir/?requestor_id={institutional Requestor_ID}&platform={IRUS Repository_ID}&begin_date=2020-01&end_date=2020-02&country_code=AU&content_type=csv -
Custom Item Master Report, for usage for a given item (specified using an IRUS Item_ID):
[JSON]
https://irus.jisc.ac.uk/api/irus/reports/irus_ir/?requestor_id={institutional Requestor_ID}&platform={IRUS Repository_ID}&begin_date=2020-01&end_date=2020-02&item_id=123456&pretty -
Custom Item Master Report, for usage from just Australia (AU) for a given item (specified using an OAI identifier):
[CSV]
https://irus.jisc.ac.uk/api/irus/reports/irus_ir/?requestor_id={institutional Requestor_ID}&platform={IRUS Repository_ID}&begin_date=2020-01&end_date=2020-02&country_code=AU&item_id=oai:example.ac.uk/1234/56789&content_type=csv -
Custom Item Master Report, for usage split by country for a given item (specified by a DOI):
[TXT]
https://irus.jisc.ac.uk/api/irus/reports/irus_ir/?requestor_id={institutional Requestor_ID}&platform={IRUS Repository_ID}&begin_date=2020-01&end_date=2020-02&item_id=10.1234/56789&attributes_to_show=Country&content_type=txt
IRUS-OAPEN API
Security Considerations
The information returned in the IRUS-OAPEN response is sensitive and considered private. To protect this data:
- The IRUS-OAPEN API implementation uses HTTPS to secure the data channel
- The IRUS-OAPEN server implements authentication challenges using a combination of
- Requestor ID
- API Key
Request Syntax
Following the REST model, the IRUS-OAPEN API request uses the following general syntax:
{BaseURL}/{Path}?{Report_Parameters}
where:
{BaseURL}:https://irus.jisc.ac.uk/api/oapen{Path}: always required and determines the operation that the API will carry out. Available paths are:/reports/[report_id]
{Report_Parameters}: a list of parameters as dictated by the path (operation).
The following sections give further details for each supported path:
/reports/oapen_pr
This path returns a custom Platform Master Report for OAPEN.
Request parameters
| Parameter | Mandatory or optional | Description |
|---|---|---|
| requestor_id | Mandatory | Identifies who is making the request - to obtain a Requestor_ID please contact our helpdesk with 'IRUS-OAPEN API' as the subject. |
| api_key | Mandatory | Confirms identity of requestor - to obtain an API_Key please contact our helpdesk with 'IRUS-OAPEN API' as the subject. |
| platform | Mandatory | IRUS identifier of the repository (Platform) for which the data is being requested. Possible values can be seen in the Repository_ID column of the Participants table. |
| begin_date | Mandatory | Usage start date in the form of yyyy-mm |
| end_date | Mandatory | Usage end date in the form of yyyy-mm |
| country_code | Optional | Optional Report Filter to limit usage to customers from a specified country by supplying an ISO 3166 Alpha-2 code, e.g., GB for United Kingdom of Great Britain and Northern Ireland (the), and AU for Australia. Multiple values are delimited with a | character. Omitting this parameter will return statistics for users anywhere in the world that have usage. |
| metric_type | Optional | Optional Report Filter. A list of Metric_Types to return. Multiple values are delimited with a | character. Omitting this parameter will return statistics for all metric_types with usage. |
| publisher | Optional | Optional Report Filter to limit usage to certain publishers, specified by OAPEN Publisher UUID(s). Multiple values are delimited with a | character. Omitting this parameter will return statistics for all publishers with usage. |
| attributes_to_show | Optional | Optional Report Attribute. A list of attributes to include as separate elements in response (usage will be broken out by attribute values). Multiple attribute names are delimited with a | character. Options available are Country and Publisher. When fields are included usage will be presented for each value of that field (with usage) otherwise usage will be rolled up for all values of a given field. |
| granularity | Optional | Optional Report Attribute. Include this parameter to allow usage to be retrieved with a granularity of 'month' (default if omitted) or 'totals' |
| content_type | Optional | Optional Report Attribute. Permitted values are: json, csv or txt (where txt returns a tabular report with tab-separated values). Omitting this attribute will return JSON. |
| pretty | Optional | Only for use with the JSON format. Presents the JSON response in a human-readable form for viewing in a browser while testing. DO NOT USE in production requests. |
Note: Parameters may be provided in any order.
Examples
-
OAPEN Platform Master Report, with no optional Filters or Attributes_To_Show:
[JSON]
https://irus.jisc.ac.uk/api/oapen/reports/oapen_pr/?requestor_id={institutional Requestor_ID}&platform={IRUS Repository_ID}&begin_date=2021-01&end_date=2021-02&pretty[CSV]https://irus.jisc.ac.uk/api/oapen/reports/oapen_pr/?requestor_id={institutional Requestor_ID&platform={IRUS Repository_ID}&begin_date=2021-01&end_date=2021-02&content_type=csv -
OAPEN Platform Master Report, with usage split by publisher:
[TXT]
https://irus.jisc.ac.uk/api/oapen/reports/oapen_pr/?requestor_id={your Requestor_ID}&api_key={your API_Key}&platform={IRUS Repository_ID}&begin_date=2021-01&end_date=2021-02&attributes_to_show=Publisher&content_type=txt -
OAPEN Platform Master Report, with usage split by country:
[JSON]
https://irus.jisc.ac.uk/api/oapen/reports/oapen_pr/?requestor_id={your Requestor_ID}&api_key={your API_Key}&platform={IRUS Repository_ID}&begin_date=2021-01&end_date=2021-02&attributes_to_show=Country&pretty -
OAPEN Platform Master Report, for usage from just Australia (AU):
[TXT]
https://irus.jisc.ac.uk/api/oapen/reports/oapen_pr/?requestor_id={your Requestor_ID}&api_key={your API_Key}&platform={IRUS Repository_ID}&begin_date=2021-01&end_date=2021-02&country_code=AU&content_type=txt -
OAPEN Platform Master Report, with all optional Attributes_To_Show values:
[JSON]
https://irus.jisc.ac.uk/api/oapen/reports/oapen_pr/?requestor_id={your Requestor_ID}&api_key={your API_Key}&platform={IRUS Repository_ID}&begin_date=2021-01&end_date=2021-02&attributes_to_show=Country|Publisher&pretty
/reports/oapen_ir
This path returns a custom Item Master Report for OAPEN.
Request parameters
| Parameter | Mandatory or optional | Description |
|---|---|---|
| requestor_id | Mandatory | Identifies who is making the request - to obtain a Requestor_ID please contact our helpdesk with 'IRUS-OAPEN API' as the subject. |
| api_key | Mandatory | Confirms identity of requestor - to obtain an API_Key please contact our helpdesk with 'IRUS-OAPEN API' as the subject. |
| platform | Mandatory | IRUS identifier of the repository (Platform) for which the data is being requested. Possible values can be seen in the Repository_ID column of the Participants table. |
| begin_date | Mandatory | Usage start date in the form of yyyy-mm |
| end_date | Mandatory | Usage end date in the form of yyyy-mm |
| country_code | Optional | Optional Report Filter to limit usage to customers from a specified country by supplying an ISO 3166 Alpha-2 code, e.g., GB for United Kingdom of Great Britain and Northern Ireland (the), and AU for Australia. Multiple values are delimited with a | character. Omitting this parameter will return statistics for users anywhere in the world. |
| funder | Optional | Optional Report Filter to limit usage to certain funders, specified by OAPEN Funder UUID(s). Multiple values are delimited with a | character. Omitting this parameter will return statistics for all funders with usage. |
| item_id | Optional | Optional Report Filter to limit usage to a single item. Permitted parameter values are IRUS item identifier, DOI or OAI identifier. Omitting this parameter will return statistics for all items with usage. |
| metric_type | Optional | Optional Report Filter. A list of Metric_Types to return. Multiple values are delimited with a | character. Omitting this parameter will return statistics for all metric_types with usage. |
| publisher | Optional | Optional Report Filter to limit usage to certain publishers, specified by OAPEN Publisher UUID(s). Multiple values are delimited with a | character. Omitting this parameter will return statistics for all publishers with usage. |
| attributes_to_show | Optional | Optional Report Attribute. A list of attributes to include as separate elements in response (usage will be broken out by attribute values). Multiple attribute names are delimited with a | character. Options available are Country and Client_IP. When fields are included usage will be presented for each value of that field (with usage) otherwise usage will be rolled up for all values of a given field. |
| granularity | Optional | Optional Report Attribute. Include this parameter to allow usage to be retrieved with a granularity of 'month' (default if omitted) or 'totals' |
| content_type | Optional | Optional Report Attribute. Permitted values are: json, csv or txt (where txt returns a tabular report with tab-separated values). Omitting this attribute will return JSON. |
| pretty | Optional | Only for use with the JSON format. Presents the JSON response in a human-readable form for viewing in a browser while testing. DO NOT USE in production requests. |
Note: Parameters may be provided in any order.
Examples
-
OAPEN Item Master Report, with no optional Filters or Attributes_To_Show:
[JSON]
https://irus.jisc.ac.uk/api/oapen/reports/oapen_ir/?requestor_id={your Requestor_ID}&api_key={your API_Key}&platform={IRUS Repository_ID}&begin_date=2020-01&end_date=2020-02&pretty[CSV]https://irus.jisc.ac.uk/api/oapen/reports/oapen_ir/?requestor_id={your Requestor_ID}&api_key={your API_Key}&platform={IRUS Repository_ID}&begin_date=2020-01&end_date=2020-02&content_type=csv -
OAPEN Item Master Report, with usage split by country:
[TXT]
https://irus.jisc.ac.uk/api/oapen/reports/oapen_ir/?requestor_id={your Requestor_ID}&api_key={your API_Key}&platform={IRUS Repository_ID}&begin_date=2020-01&end_date=2020-02&attributes_to_show=Country&content_type=txt -
OAPEN Item Master Report, for usage from just Australia (AU):
[CSV]
https://irus.jisc.ac.uk/api/oapen/reports/oapen_ir/?requestor_id={your Requestor_ID}&api_key={your API_Key}&platform={IRUS Repository_ID}&begin_date=2020-01&end_date=2020-02&country_code=AU&content_type=csv -
OAPEN Item Master Report, for usage for a given item (specified using an IRUS Item_ID):
[JSON]
https://irus.jisc.ac.uk/api/oapen/reports/oapen_ir/?requestor_id={your Requestor_ID}&api_key={your API_Key}&platform={IRUS Repository_ID}&begin_date=2020-01&end_date=2020-02&item_id=123456&pretty -
OAPEN Item Master Report, for usage from just Australia (AU) for a given item (specified using an OAI identifier):
[CSV]
https://irus.jisc.ac.uk/api/oapen/reports/oapen_ir/?requestor_id={institutional Requestor_ID}&platform={IRUS Repository_ID}&begin_date=2020-01&end_date=2020-02&country_code=AU&item_id=oai:example.ac.uk/1234/56789&content_type=csv -
OAPEN Item Master Report, for usage split by country for a given item (specified by a DOI):
[TXT]
https://irus.jisc.ac.uk/api/oapen/reports/oapen_ir/?requestor_id={institutional Requestor_ID}&platform={IRUS Repository_ID}&begin_date=2020-01&end_date=2020-02&item_id=10.1234/56789&attributes_to_show=Country&content_type=txt