API docs by Redocly

EUsage Reports (v1)

getReportTitles

Get titles with links to KB. The response contains facets response with facet type "status" and counts for values "matched", "ignored", "unmatched. The resulting set can be limited by parameter query (CQL) as well as counterReportId and providerId (these are NOT part of CQL). The CQL query itself supports fields "cql.allRecords", "id", "counterReportTitle", "ISBN", "printISSN", "onlineISSN", "kbTitleId" and "kbManualMatch".

query Parameters
facets
string

facet names. Each facet is separted by comma.

limit
integer >= 0
Default: 10

Limit the number of elements returned in the response

query
string

CQL query

offset
integer >= 0
Default: 0

Skip over number of elements (default is first element)

counterReportId
string

limit titles associated with counter report (UUID)

providerId
string

limit titles associated with usage provider (UUID)

header Parameters
X-Okapi-Tenant
string

Okapi Tenant

X-Okapi-Token
string

Okapi Token

X-Okapi-Url
string

Okapi URL

Responses

Response samples

Content type
application/json
{
  • "titles": [
    ],
  • "resultInfo": {
    }
}

postReportTitles

POST titles with links to KB

query Parameters
facets
string

facet names. Each facet is separted by comma.

limit
integer >= 0
Default: 10

Limit the number of elements returned in the response

query
string

CQL query

offset
integer >= 0
Default: 0

Skip over number of elements (default is first element)

counterReportId
string

limit titles associated with counter report (UUID)

providerId
string

limit titles associated with usage provider (UUID)

header Parameters
X-Okapi-Tenant
string

Okapi Tenant

X-Okapi-Token
string

Okapi Token

X-Okapi-Url
string

Okapi URL

Request Body schema: application/json
required
Array of objects (reportTitle)

List of titles

Array
id
required
string <uuid>

title identifier

counterReportTitle
string

Title as it appears in counter report

kbTitleName
string

KB title name

kbTitleId
string <uuid>

KB title identifier. If not given, title is ignored (kbManualMatch=true) or unmatched (kbManualMatch=false)

kbManualMatch
boolean

whether the counter title to kb title is manually set or ignored

printISSN
string

ISSN for print instance

onlineISSN
string

ISSN for online instance

ISBN
string

ISBN-13 with hyphens

DOI
string

Digital Object identifier

publicationType
string

publication type from ERM ('serial', 'monograph')

object (resultInfo)

Common result set information for streaming response

totalRecords
integer

Total number of entries in response

Array of objects

Diagnostics for response

Array of objects

Array of facets

Responses

Request samples

Content type
application/json
{
  • "titles": [
    ],
  • "resultInfo": {
    }
}

Response samples

Content type
No sample

getReportPackages

Get KB title - package relationship.

query Parameters
offset
integer >= 0
Default: 0

Skip over number of elements (default is first element)

limit
integer >= 0
Default: 10

Limit the number of elements returned in the response

query
string

CQL query

header Parameters
X-Okapi-Tenant
string

Okapi Tenant

X-Okapi-Token
string

Okapi Token

X-Okapi-Url
string

Okapi URL

Responses

Response samples

Content type
application/json
{
  • "packages": [
    ],
  • "resultInfo": {
    }
}

postFromCounter

Parse counter reports

header Parameters
X-Okapi-Tenant
string

Okapi Tenant

X-Okapi-Token
string

Okapi Token

X-Okapi-Url
string

Okapi URL

Request Body schema: application/json
counterReportId
string <uuid>

Counter report identifier

providerId
string

Counter reports with given usage data provider ID

Responses

Request samples

Content type
application/json
{
  • "counterReportId": "e75de439-3144-4399-a13b-7df6393ebf21",
  • "providerId": "string"
}

Response samples

Content type
application/json
{ }

getTitleData

Get counter report title data.

query Parameters
offset
integer >= 0
Default: 0

Skip over number of elements (default is first element)

limit
integer >= 0
Default: 10

Limit the number of elements returned in the response

query
string

CQL query

header Parameters
X-Okapi-Tenant
string

Okapi Tenant

X-Okapi-Token
string

Okapi Token

X-Okapi-Url
string

Okapi URL

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "resultInfo": {
    }
}

getReportData

This returns data for parsed agreements.

query Parameters
offset
integer >= 0
Default: 0

Skip over number of elements (default is first element)

limit
integer >= 0
Default: 10

Limit the number of elements returned in the response

query
string

CQL query

header Parameters
X-Okapi-Tenant
string

Okapi Tenant

X-Okapi-Token
string

Okapi Token

X-Okapi-Url
string

Okapi URL

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "resultInfo": {
    }
}

postFromAgreement

Parse agreements and populate report data

header Parameters
X-Okapi-Tenant
string

Okapi Tenant

X-Okapi-Token
string

Okapi Token

X-Okapi-Url
string

Okapi URL

Request Body schema: application/json
agreementId
string <uuid>

Agreement Identifier

Responses

Request samples

Content type
application/json
{
  • "agreementId": "79458f91-82b5-4c38-a886-56df6a6b7980"
}

Response samples

Content type
application/json
{
  • "reportLinesCreated": 0
}

getUseOverTime

Return usage data over time, where usageDateRange falls within startDate, endDate

query Parameters
accessCountPeriod
string^(\d+[YM])|(auto)$
Default: "auto"

Group access according to this parameter. May be given in a number of months (nM) or in years (nY). The value "auto" makes it group as 1Y if startDate is given as YYYY; otherwise 1M.

agreementId
required
string <uuid>

Agreement identifier

csv
boolean
Default: false

whether to return CSV response with details.

startDate
required
string^[12]\d\d\d(-0[1-9]|-1[012])?$
Example: startDate=2019-04

first year for year reporting, or first month for month reporting

endDate
required
string^[12]\d\d\d(-0[1-9]|-1[012])?$
Example: endDate=2019-06

last year for year reporting, or last month for month reporting

format
string^(BOOK|JOURNAL|ALL)$

item format type

includeOA
boolean
Default: false

whether to include Open Access material

full
boolean
Default: true

whether to return full response or brief (summary) response

header Parameters
X-Okapi-Tenant
string

Okapi Tenant

X-Okapi-Token
string

Okapi Token

X-Okapi-Url
string

Okapi URL

Responses

Response samples

Content type
application/json
{
  • "agreementId": "20000000-0000-4000-8000-000000000000",
  • "accessCountPeriods": [
    ],
  • "totalItemRequestsTotal": 996,
  • "totalItemRequestsByPeriod": [
    ],
  • "uniqueItemRequestsTotal": 447,
  • "uniqueItemRequestsByPeriod": [
    ],
  • "items": [
    ]
}

getReqsByDateOfUse

Return requests by date of use; this is like use over time but additionally groups by publication year.

query Parameters
accessCountPeriod
string^(\d+[YM])|(auto)$
Default: "auto"

Group access according to this parameter. May be given in a number of months (nM) or in years (nY). The value "auto" makes it group as 1Y if startDate is given as YYYY; otherwise 1M.

agreementId
required
string <uuid>

Agreement identifier

csv
boolean
Default: false

whether to return CSV response with details.

startDate
required
string^[12]\d\d\d(-0[1-9]|-1[012])?$
Example: startDate=2019-04

first year for year reporting, or first month for month reporting

endDate
required
string^[12]\d\d\d(-0[1-9]|-1[012])?$
Example: endDate=2019-06

last year for year reporting, or last month for month reporting

format
string^(BOOK|JOURNAL|ALL)$

item format type

includeOA
boolean
Default: false

whether to include Open Access material

yopInterval
string^(\d+[YM])|(auto)$
Default: "auto"

a number of months or years for grouping publication dates

full
boolean
Default: true

whether to return full response or brief (summary) response

header Parameters
X-Okapi-Tenant
string

Okapi Tenant

X-Okapi-Token
string

Okapi Token

X-Okapi-Url
string

Okapi URL

Responses

Response samples

Content type
application/json
{
  • "agreementId": "string",
  • "accessCountPeriods": [
    ],
  • "totalItemRequestsTotal": 0,
  • "totalItemRequestsByPeriod": [
    ],
  • "totalRequestsPublicationYearsByPeriod": [
    ],
  • "totalRequestsPeriodsOfUseByPeriod": [
    ],
  • "uniqueItemRequestsTotal": 0,
  • "uniqueItemRequestsByPeriod": [
    ],
  • "uniqueRequestsPublicationYearsByPeriod": [
    ],
  • "uniqueRequestsPeriodsOfUseByPeriod": [
    ],
  • "items": [
    ],
  • "execution": { }
}

getReqsByPubYear

Return requests by publication year where usageDateRange falls within startDate, endDate. Grouping controlled by periodOfUse. "accessCountPeriods" array lists the publication years to be used as column labels for numbers in the "totalItemRequestsByPeriod", "uniqueItemRequestsByPeriod" and "accessCountsByPeriod" arrays.

query Parameters
accessCountPeriod
string^(\d+[YM])|(auto)$
Default: "auto"

Group access according to this parameter. May be given in a number of months (nM) or in years (nY). The value "auto" makes it group as 1Y if startDate is given as YYYY; otherwise 1M.

agreementId
required
string <uuid>

Agreement identifier

csv
boolean
Default: false

whether to return CSV response with details.

startDate
required
string^[12]\d\d\d(-0[1-9]|-1[012])?$
Example: startDate=2019-04

first year for year reporting, or first month for month reporting

endDate
required
string^[12]\d\d\d(-0[1-9]|-1[012])?$
Example: endDate=2019-06

last year for year reporting, or last month for month reporting

format
string^(BOOK|JOURNAL|ALL)$

item format type

includeOA
boolean
Default: false

whether to include Open Access material

periodOfUse
required
string^\d+[YM]$

a number of months or years for grouping

full
boolean
Default: true

whether to return full response or brief (summary) response

header Parameters
X-Okapi-Tenant
string

Okapi Tenant

X-Okapi-Token
string

Okapi Token

X-Okapi-Url
string

Okapi URL

Responses

Response samples

Content type
application/json
{
  • "agreementId": "string",
  • "accessCountPeriods": [
    ],
  • "totalItemRequestsTotal": 0,
  • "totalItemRequestsByPeriod": [
    ],
  • "totalRequestsPublicationYearsByPeriod": [
    ],
  • "totalRequestsPeriodsOfUseByPeriod": [
    ],
  • "uniqueItemRequestsTotal": 0,
  • "uniqueItemRequestsByPeriod": [
    ],
  • "uniqueRequestsPublicationYearsByPeriod": [
    ],
  • "uniqueRequestsPeriodsOfUseByPeriod": [
    ],
  • "items": [
    ],
  • "execution": { }
}

getCostPerUse

Return cost per where usageDateRange falls within startDate, endDate. The report is structured in periods, typically months, and the cost-per-use in a period is invoiced amount divided by download count (unique or total) and further divided in number of periods where any title has downloads. This way the cost for download is divided into periods (with non-zero use) and then evenly divided across titles within those periods. Consider agreement that has two titles, titleA and titleB where titleA has downloads in May and June. titleB has downloads in June only. In May, the title count is 1. In June, the title count is 2. The total periods where any title occurs is p = 2+1 = 3. Cost per download for titleA in May is (paidAmount/p) / downloads(TitleA,May) and in June (paidAmount/p) / downloads(TitleA,June). Cost per download for titleB in June is paidAmount/p / downloads(TitleB,June).

query Parameters
accessCountPeriod
string^(\d+[YM])|(auto)$
Default: "auto"

Group access according to this parameter. May be given in a number of months (nM) or in years (nY). The value "auto" makes it group as 1Y if startDate is given as YYYY; otherwise 1M.

agreementId
required
string <uuid>

Agreement identifier

csv
boolean
Default: false

whether to return CSV response with details.

startDate
required
string^[12]\d\d\d(-0[1-9]|-1[012])?$
Example: startDate=2019-04

first year for year reporting, or first month for month reporting

endDate
required
string^[12]\d\d\d(-0[1-9]|-1[012])?$
Example: endDate=2019-06

last year for year reporting, or last month for month reporting

format
string^(BOOK|JOURNAL|ALL)$

item format type

includeOA
boolean
Default: false

whether to include Open Access material

full
boolean
Default: true

whether to return full response or brief (summary) response

header Parameters
X-Okapi-Tenant
string

Okapi Tenant

X-Okapi-Token
string

Okapi Token

X-Okapi-Url
string

Okapi URL

Responses

Response samples

Content type
application/json
{
  • "accessCountPeriods": [
    ],
  • "amountEncumeredTotal": 0,
  • "amountPaidTotal": 0,
  • "costByPeriod": [
    ],
  • "items": [
    ],
  • "titleCountByPeriod": [
    ],
  • "totalItemRequestsByPeriod": [
    ],
  • "totalItemCostsPerRequestsByPeriod": [
    ],
  • "uniqueItemRequestsByPeriod": [
    ],
  • "uniqueItemCostsPerRequestsByPeriod": [
    ],
  • "execution": { }
}

getReportStatus

Return status of operation associated with identifier.

path Parameters
id
required
string <uuid>

agreement identifier

header Parameters
X-Okapi-Tenant
string

Okapi Tenant

X-Okapi-Token
string

Okapi Token

X-Okapi-Url
string

Okapi URL

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "lastUpdated": "string",
  • "active": true
}