EUsage Reports (v1)

getReportTitles

Get titles with links to KB

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

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
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

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

List of titles

object

Common result set information

Responses

Request samples

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

Response samples

Content type
No sample

getReportPackages

Get KB packages

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

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

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
{
  • "titles": [
    ],
  • "resultInfo": {
    }
}

getTitleData

Get 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

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

Return report 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

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

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

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": [
    ]
}

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

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": [
    ]
}

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

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": [
    ]
}

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
}