Fetching statistics reports via the API
The API can provide a mechanism to query the reporting data. This gives a flat report in CSV format you can use in analysis tools such as Tableau, Power BI and others.
Prerequisites
The optional reports API functionality to be enabled for your organisation - your account manager will be happy to discuss pricing with you
An API Key from the domain organisation or sub-organisation the reports will cover.
The key will need either the reports API permission (recommended) or the full access permission.
A basic practical knowledge of APIs and coding
Procedure
Perform a GET request to the following URL:
https://reports.openathens.net/api/v1/example.org/report?type=<type>&from=<from>&to=<to>&by=<by>[&resource=<resource>][&scope=<scope>][&andBy=<andBy>][&granularity=<granularity>]
Where example.org is your OpenAthens API name and:
Parameter | Required | Accepted values | Default if omitted |
---|---|---|---|
type | Y |
(other report types will be added in the future) | |
from | Y |
| yyyy-MM (default if no granularity is set) |
to | Y |
| yyyy-MM (default if no granularity is set) |
by | Y |
| |
resource | N | Specify a single resource by entityID Can not be used with | All resources |
scope | N |
All includes all the sub-organisations below the authenticated user | The organisation of the authenticated user |
andBy | N |
Optional. Can only be used with | |
granularity | N |
If Hourly or Daily: 'from' and 'to' date format should be yyyy-MM-ddTHH:mm If Monthly: 'from' and 'to' date format can be yyyy-MM |
|
The maximum date range you can query depends on the granularity, as follows:
Granularity | Maximum date range | Example |
---|---|---|
HOURLY | 7 days |
Provides the week from 1 April 2020 07:00 UTC through 7 April 2020 06:00 UTC |
DAILY | 1 month |
Provides the month from 1 April 2020 through 30 April 2020 |
MONTHLY | 12 months |
Provides the 12 months from April 2019 through March 2010 |
Response codes
HTTP Response Code | Description |
---|---|
200 | The request was successful |
204 | No data |
400 | Bad request - e.g. date out of range |
401 | The requester does not have permission to perform this operation |
403 | The API key was valid, but the organisation is not enabled to use the reporting API |
404 | Not found |
Response payload
Since reports can take some time to run, the response is an application/vnd.eduserv.iam.reports.task-v1+json
object containing a href to the task status. Your application will need to monitor this until the task completes (20s is a reasonable wait time to code).
Once the task is complete, the object will have a status of FINISHED and a percentComplete of 100, and a link to the report.
Example
Request:
GET https://reports.openathens.net/api/v1/example.org/report?type=RESOURCE_USAGE&from=2020-01&to=2020-01&by=RESOURCE&scope=ALL_ORGANISATIONS
Authorization: OAApiKey <api-key>
Response:
HTTP/1/1 200 OK
Content-Type: application/vnd.eduserv.iam.reports.task-v1+json
{
"percentComplete": 0,
"status": "RUNNING",
"links": [
{
"href": "https://reports.openathens.net/api/v1/example.org/task/a11b5fff-6170-38e3-b4bb-560bee3e6985",
"rel": "SELF",
"type": "application/vnd.eduserv.iam.reports.task-v1+json",
"method": "get"
}
],
"id": "a11b5fff-6170-38e3-b4bb-560bee3e6985"
}
When finished, the response will have updated to include a link to the report
Request:
GET https://reports.openathens.net/api/v1/example.org/task/a11b5fff-6170-38e3-b4bb-560bee3e6985
Authorization: OAApiKey <api-key>
Response:
HTTP/1/1 200 OK
Content-Type: application/vnd.eduserv.iam.reports.task-v1+json
{
"percentComplete": 100,
"status": "FINISHED",
"links": [
{
"href": "https://reports.openathens.net/api/v1/athens/report/a11b5fff-6170-38e3-b4bb-560bee3e6985",
"rel": "DOWN",
"type": "application/vnd.eduserv.iam.reports.report-v1+json",
"method": "get"
}
],
"id": "a11b5fff-6170-38e3-b4bb-560bee3e6985"
}
Report format
The downloaded report will be a CSV file (MIME type text/csv
) with these headings:
Domain,Organisation number,Organisation name,DateTime,<by>,[<andyby>,]Count
where:
Domain
is your API name (as per the request). This will be constant for the reportOrganisation number
is the numeric identifier of the organisation (or sub-organisations where scope=ALL_ORGANISATIONS in the request). See below if you have more than one in the report.DateTime
is the date/time of the record as yyyy-MM for monthly granularity, yyyy-MM-dd for daily, and yyyy-MM-ddTHH:mmZ for hourly (ISO 8601)<by>
will be replaced by RESOURCE, GROUPS, PERMISSION_SETS, or ATTRIBUTE:<targetname> as per the request<andBy>
(where present) will similarly be replaced by the secondary breakdown identifierCount
will be the number of transfers
Unique users
When a report mentions a number of unique users, it is counting only one authentication per user in the granule (hour, day, month). This shows you how many accounts were responsible for each of the totals in that granule - adding up unique users will not work as the same user can appear in several granules and you'll end up with a number bigger than your total number of accounts - you should use a larger granule instead. For example the number of unique users on any given day (e.g daily granularity) is very unlikely to match the number of unique users at monthly granularity as those who sign in on Monday might or might not on Tuesday.
Anything to watch out for?
When using ATTRIBUTE:<target name>
with the by
or andBy
parameters, the target name of the attribute must be normalised to lower case of the request will fail with a 400 error
Daily granularity reports are inclusive of the start and end date
API keys respect the hierarchy of the organisation structure - if you only want data from a specific sub-organisation or branch, create the API key under the relevant sub-organisation
Querying certain dates will produce an error:
dates before your organisation joined OpenAthens
dates before January 2018
dates more than 48 months in the past