APIs in IRUS are implemented using a REST model implemented over HTTPS. Currently just one API is available.
- 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 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/v3/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.
Request parameters
Parameter | Mandatory or optional | Description |
---|---|---|
begin_date | Mandatory | Usage start date in the form of yyyy-mm |
end_date | Mandatory | Usage end date in the form of yyyy-mm |
requestor_id | Mandatory | Identifies who is making the request - to obtain a Requestor_ID please contact our helpdesk with 'IRUS API' as the subject. Available to participating organisations only. |
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. |
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. |
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. |
granularity | Optional | Optional Report Attribute. Include this parameter to allow usage to be retrieved with a granularity of 'month' (default if omitted) or 'totals' |
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. |
platform | Optional | 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. |
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/v3/irus/reports/irus_pr/?requestor_id={institutional Requestor_ID}&platform={IRUS Repository_ID}&begin_date=2024-09&end_date=2024-10&pretty
[CSV]https://irus.jisc.ac.uk/api/v3/irus/reports/irus_pr/?requestor_id={institutional Requestor_ID&platform={IRUS Repository_ID}&begin_date=2024-09&end_date=2024-10&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/v3/irus/reports/irus_pr/?requestor_id={institutional Requestor_ID}&platform={IRUS Repository_ID}&begin_date=2024-09&end_date=2024-10&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/v3/irus/reports/irus_pr/?requestor_id={institutional Requestor_ID}&platform={IRUS Repository_ID}&begin_date=2024-09&end_date=2024-10&irus_type_id=2|4&content_type=csv
-
Custom Platform Master Report, with usage split by country:
[JSON]
https://irus.jisc.ac.uk/api/v3/irus/reports/irus_pr/?requestor_id={institutional Requestor_ID}&platform={IRUS Repository_ID}&begin_date=2024-09&end_date=2024-10&attributes_to_show=Country&pretty
-
Custom Platform Master Report, for usage from just Australia (AU):
[TXT]
https://irus.jisc.ac.uk/api/v3/irus/reports/irus_pr/?requestor_id={institutional Requestor_ID}&platform={IRUS Repository_ID}&begin_date=2024-09&end_date=2024-10&country_code=AU&content_type=txt
-
Custom Platform Master Report, with all optional Attributes_To_Show values:
[JSON]
https://irus.jisc.ac.uk/api/v3/irus/reports/irus_pr/?requestor_id={institutional Requestor_ID}&platform={IRUS Repository_ID}&begin_date=2024-09&end_date=2024-10&attributes_to_show=Irus_Item_Type|Country&pretty
/reports/irus_ir
This path returns a custom Item Master Report.
Request parameters
Parameter | Mandatory or optional | Description |
---|---|---|
begin_date | Mandatory | Usage start date in the form of yyyy-mm |
end_date | Mandatory | Usage end date in the form of yyyy-mm |
requestor_id | Mandatory | Identifies who is making the request - to obtain a Requestor_ID please contact our helpdesk with 'IRUS API' as the subject. Available to participating organisations only. |
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. |
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. |
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. |
granularity | Optional | Optional Report Attribute. Include this parameter to allow usage to be retrieved with a granularity of 'month' (default if omitted) or 'totals' |
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. Note that an item_id must be specified if a platform isn't. |
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. |
platform | Optional | 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. Note that an item_id must be specified if a platform isn't. |
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. |
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. |
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/v3/irus/reports/irus_ir/?requestor_id={institutional Requestor_ID}&platform={IRUS Repository_ID}&begin_date=2024-09&end_date=2024-10&pretty
[CSV]https://irus.jisc.ac.uk/api/v3/irus/reports/irus_ir/?requestor_id={institutional Requestor_ID}&platform={IRUS Repository_ID}&begin_date=2024-09&end_date=2024-10&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/v3/irus/reports/irus_ir/?requestor_id={institutional Requestor_ID}&platform={IRUS Repository_ID}&begin_date=2024-09&end_date=2024-10&irus_type_id=2|4&content_type=txt
-
Custom Item Master Report, with usage split by country:
[JSON]
https://irus.jisc.ac.uk/api/v3/irus/reports/irus_ir/?requestor_id={institutional Requestor_ID}&platform={IRUS Repository_ID}&begin_date=2024-09&end_date=2024-10&attributes_to_show=Country&pretty
-
Custom Item Master Report, for usage from just Australia (AU):
[CSV]
https://irus.jisc.ac.uk/api/v3/irus/reports/irus_ir/?requestor_id={institutional Requestor_ID}&platform={IRUS Repository_ID}&begin_date=2024-09&end_date=2024-10&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/v3/irus/reports/irus_ir/?requestor_id={institutional Requestor_ID}&platform={IRUS Repository_ID}&begin_date=2024-09&end_date=2024-10&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/v3/irus/reports/irus_ir/?requestor_id={institutional Requestor_ID}&platform={IRUS Repository_ID}&begin_date=2024-09&end_date=2024-10&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/v3/irus/reports/irus_ir/?requestor_id={institutional Requestor_ID}&platform={IRUS Repository_ID}&begin_date=2024-09&end_date=2024-10&item_id=10.1234/56789&attributes_to_show=Country&content_type=txt
/reports/irus_ir_daily
This path returns a custom Item Master Report containing provisional recent daily statistics.
Request parameters
Parameter | Mandatory or optional | Description |
---|---|---|
begin_date | Mandatory | Usage start date in the form of yyyy-mm-dd |
end_date | Mandatory | Usage end date in the form of yyyy-mm-dd |
requestor_id | Mandatory | Identifies who is making the request - to obtain a Requestor_ID please contact our helpdesk with 'IRUS API' as the subject. Available to participating organisations only. |
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. |
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. |
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. |
granularity | Optional | Optional Report Attribute. Include this parameter to allow usage to be retrieved with a granularity of 'day' (default if omitted) or 'totals' |
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. Note that an item_id must be specified if a platform isn't. |
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. |
platform | Optional | 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. Note that an item_id must be specified if a platform isn't. |
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. |
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. |
Note: Parameters may be provided in any order.
Examples
-
Custom Item Master Report containing provisional recent daily statistics, with no optional Attributes_To_Show:
[JSON]
https://irus.jisc.ac.uk/api/v3/irus/reports/irus_ir_daily/?requestor_id={institutional Requestor_ID}&platform={IRUS Repository_ID}&begin_date=2024-11-17&end_date=2024-11-24&pretty
[CSV]https://irus.jisc.ac.uk/api/v3/irus/reports/irus_ir_daily/?requestor_id={institutional Requestor_ID}&platform={IRUS Repository_ID}&begin_date=2024-11-17&end_date=2024-11-24&content_type=csv
-
Custom Item Master Report containing provisional recent daily statistics, 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/v3/irus/reports/irus_ir_daily/?requestor_id={institutional Requestor_ID}&platform={IRUS Repository_ID}&begin_date=2024-11-17&end_date=2024-11-24&irus_type_id=2|4&content_type=txt
-
Custom Item Master Report containing provisional recent daily statistics, with usage broken down by country:
[JSON]
https://irus.jisc.ac.uk/api/v3/irus/reports/irus_ir_daily/?requestor_id={institutional Requestor_ID}&platform={IRUS Repository_ID}&begin_date=2024-11-17&end_date=2024-11-24&attributes_to_show=Country&pretty
-
Custom Item Master Report containing provisional recent daily statistics, for all usage from Australia (AU):
[JSON]
https://irus.jisc.ac.uk/api/v3/irus/reports/irus_ir_daily/?requestor_id={institutional Requestor_ID}&platform={IRUS Repository_ID}&begin_date=2024-11-17&end_date=2024-11-24&country_code=AU&pretty
-
Custom Item Master Report containing provisional recent daily statistics, for all usage from Australia (AU) for a given item:
[JSON]
https://irus.jisc.ac.uk/api/v3/irus/reports/irus_ir_daily/?requestor_id={institutional Requestor_ID}&platform={IRUS Repository_ID}&begin_date=2024-11-17&end_date=2024-11-24&country_code=AU&item_id=123456&pretty