Fetching raw statistics data via the API

This function is in beta and may change. Documentation may sometimes lag behind any changes.

As well as a mechanism to return aggregated reports, an API call can also be used to retrieve raw 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 each organisation and sub-organisation you will be querying
The key will need either the reports API permission (recommended) or the full access permission.

Request

As with the other reports, this is a two step operation.

Perform a GET request to the following URL: https://reports.openathens.net/api/v1/example.org/rawreport?date=<date>

Where example.org is your OpenAthens API name and date is the requested date (format yyyy-MM-dd between yesterday and 30 days ago)

Response payload

The response will be an application/vnd.eduserv.iam.reports.task-v1+json object.

If the job completes in under 5 seconds, it will have a status of FINISHED and a href to the report - see downloading below.

If the job is still running after 5 seconds, it will return a status of RUNNING and a href back to the task status.

Your application will need to allow for both types of response. 20s is a reasonable wait time to code if you get a running response.

Example - still running

CODE

GET https://reports.openathens.net/api/v1/example.org/rawreport?date=2023-05-22 
Authorization: OAApiKey <api-key>

Response: HTTP/1/1 200 OK
Content-Type: application/vnd.eduserv.iam.reports.task-v1+json
  {
    "percentComplete": 40, 
    "status": "RUNNING", 
    "links": [ 
      { 
        "href": "https://reports.openathens.net/api/v1/example.org/rawtask/a11b5fff-6170-38e3-b4bb-560bee3e6985",
        "rel": "SELF",
        "type": "application/vnd.eduserv.iam.reports.task-v1+json",
        "method": "get" 
      } 
    ], 
    "id": "a11b5fff-6170-38e3-b4bb-560bee3e6985" 
  }

Example - finished

CODE

  GET https://reports.openathens.net/api/v1/example.org/rawtask/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/rawreport/a11b5fff-6170-38e3-b4bb-560bee3e6985",
       "rel": "DOWN",
       "type": "application/vnd.eduserv.iam.reports.report-v1+json",
       "method": "get"
      }
    ],
    "id": "a11b5fff-6170-38e3-b4bb-560bee3e6985"
  }

Downloading the linked report

Depending on your method you may optionally add a filename parameter to the download URL, e.g. https://reports.openathens.net/api/v1/athens/rawreport/a11b5fff-6170-38e3-b4bb-560bee3e6985?filename=rawstats_2023-06-20.csv.

Report format

The reports can be very large, so they’re downloaded as a zipped CSV file (MIME types application/gzip and text/csv). Not all fields will have data for all actions:

Heading	Comment
date	UTC Timestamp e.g. `06/06/2023T19:29:16`
action	What happened (see next table)
status	The status of the action e.g. `SUCCESS`, `ACCOUNT_ERROR_BAD_PASSWORD`
account.authsystemname	Local connector name e.g. `Student login`
account.authsystemid	Local connector ID e.g. `5859e555-ecf1-5afb-ba05-852355423ea6`
account.permissionsets	Permission set names connected to the user e.g. `demo#default, demo#extra`
account.organisation	The parent organisation of the account e.g. `123456`
account.accountid	The ID of the account e.g. `07e70182-e565-4be8-b6b1-f2765f13164c`
account.type	e.g. `LOCAL`, `PERSONAL`
account.status	The status of the account e.g. `PENDING`, `INVALID,` `ACTIVE`
account.expiry	OpenAthens account expiry date e.g. `2024-12-06`
location.isp	The user's ISP (where identifiable) e.g. `virginm.net`, `Btcentralplus`
request.countrycode	The ISO country code of the user's location e.g. `GB`, `US`
request.useragent	The user agent string from the user’s browser e.g. `Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:108.0) Gecko/20100101 Firefox/108.0`
request.ipaddress	The IP address the user was at e.g. `13.248.204.98`
attribute.resourceid	The entityID of the resource e.g. `https://sp.coolresource.co/entity`
attribute.federationctx	A federation identifier e.g. `oafed`, `ukfed` Custom SAML resources appear as your own OpenAthens API name
attribute.resourcetitle	The resource title (at the time) e.g. `Cool Stuff Inc.`
Plus all fields marked as reportable in your Schema editor as attribute.attributename …

Actions

Action	Comment
AUTHENTICATE	An OpenAthens account has authenticated
LOCAL_AUTHENTICATE	A local account has authenticated
FEDERATED_TRANSFER	An OpenAthens accounts has been sent to a resource
LOCAL_FEDERATED_TRANSFER	A local account has been sent to a resource

Anything to watch out for?

Changes to the reportable state of attributes in your schema will only affect items recorded after the change is saved.

The report will only cover the organisation where the API key sits, so if you have sub-organisations you will need an API key from each.

All times and dates are UTC.

Location data

This product includes GeoLite2 data created by MaxMind, available from https://www.maxmind.com