Skip to main content
Skip table of contents

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.

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

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.