General

The Statistics API is available since API version 1.3.0.

GET /api/statistics/providers

Returns a list of statistics providers.

The following query string parameters are supported to filter the returned list:

Query String Parameter Type Description
filter string A comma-separated list of filters to limit the results with (see Filtering). See the below table for the list of available filters
Filter Name Description
resourceType Filter statistics provider by resource type (either episode, series or organization)

This request additionally supports the following query string parameters to include additional information directly in the response:

Query String Parameter Type Description
withparameters boolean Whether support parameters should be included in the response

Sample request

https://opencast.domain.com/api/statistics/providers?filter=resourceType:episode

Response

200 (OK): A (potentially empty) list of providers is returned as a JSON array containing JSON objects describing the series:

Field Type Description
identifier string The unique identifier of the provider
title string The title of the provider
description string The description of the provider
type* string The type of the provider
resourceType string The resource type of the provider
parameters array[parameter] Supported query parameters (optional)

* Currently, only the timeseries type is supported

Example

[
  {
    "identifier": "influxdb-episode-views-provider",
    "title": "Episode Views",
    "description": "Episode Views, Lorem Ipsum",
    "type": "timeSeries",
    "resourceType": "episode"
  }
]

GET /api/statistics/providers/{providerId}

Returns a statistics provider.

This request additionally supports the following query string parameters to include additional information directly in the response:

Query String Parameter Type Description
withparameters boolean Whether support parameters should be included in the response

Sample request

https://opencast.domain.com/api/statistics/providers/a-timeseries-provider?withparameters=true

Response

200 (OK): A (potentially empty) list of providers is returned as a JSON array containing JSON objects describing the series:

Field Type Description
identifier string The unique identifier of the provider
title string The title of the provider
description string The description of the provider
type* string The type of the provider
resourceType string The resource type of the provider
parameters array[parameter] Supported query parameters (optional)

* Currently, only the timeSeries type is supported

Example

{
  "identifier": "a-timeseries-provider",
  "title": "Episode Views",
  "description": "Episode Views, Lorem Ipsum",
  "type": "timeseries",
  "resourceType": "episode",
  "parameters": [
    {
      "name": "resourceId",
      "optional": false,
      "type": "string"
    },
    {
      "name": "from",
      "optional": false,
      "type": "datetime"
    },
    {
      "name": "to",
      "optional": false,
      "type": "datetime"
    },
    {
      "values": [
        "daily",
        "weekly",
        "monthly",
        "yearly"
      ],
      "name": "dataResolution",
      "optional": false,
      "type": "enumeration"
    }
  ]
}

POST /api/statistics/data/query

Retrieves statistical data from one or more providers

Form Parameters Required Type Description
data yes array[object] A JSON array describing the statistics queries to request (see below)

The JSON array consists of query JSON objects. A query JSON object contains information about a statistics query to be executed:

Field Required Type Description
provider yes property A JSON object with information about the statistics provider to be queried
parameters yes property A JSON object containing the parameters

The JSON object provider has the following fields:

Field Required Type Description
identifier yes string A JSON object with information about the statistics provider to be queried

The format of the JSON object parameters depends on the provider type that is queried, and is described separately for each provider in the next section.

Example

[
  {
    "provider": {
      "identifier": "a-statistics-provider"
    },
    "parameters": {
      "resourceId": "93213324-5d29-428d-bbfd-369a2bae6700"
    }
  },
  {
    "provider": {
      "identifier": "a-timeseries-provider"
    },
    "parameters": {
      "resourceId": "23413432-5a15-328e-aafe-562a2bae6800",
      "from": "2019-04-10T13:45:32Z",
      "to": "2019-04-12T00:00:00Z",
      "dataResolution": "daily"
    }
  }
]

Response

200 (OK): A (potentially empty) list of query results is returned as a JSON array containing JSON objects 400 (BAD REQUEST): The request was not valid

Field name Type Description
provider property A JSON object describing the statistics provider as described below
parameters property A JSON object describing the query parameters
data property A JSON object containing the query result

Here, a statistics provider JSON object has the following fields:

Field Type Description
identifier string The unique identifier of the provider
type* string The type of the provider
resourceType string The resource type of the provider

Note that the format of data is implied by the type of the statistics provider.

Example

[
  {
    "provider": {
      "identifier": "a-statistics-provider",
      "type": "someType",
      "resourceType": "episode",
    },
    "parameters": {
      "resourceId": "93213324-5d29-428d-bbfd-369a2bae6700"
    },
    "data": {
      "value": "1"
    },
  {
    "provider": {
      "identifier": "a-timeseries-provider",
      "type": "timeseries",
      "resourceType": "episode",
    },
    "parameters": {
      "resourceId": "23413432-5a15-328e-aafe-562a2bae6800",
      "from": "2019-04-10T13:45:32Z",
      "to": "2019-04-12T00:00:00Z",
      "dataResolution": "daily"
    },
    "data": {
      "labels": ["2019-04-10T13:45:32Z", "2019-04-11T00:00:00Z", "2019-04-12T00:00:00Z"],
      "values": [20, 100, 300],
      "total": 420
    }
]

Time Series Statistics Provider

Time Series Statistics Providers (type = timeseries) support some well-defined parameters and deliver a well-defined data format.

Parameters:

Field name Type Description
resourceId string The technical identifier of the resource the data relates to
from datetime Start of time period this query relates to
to datetime End of time period this query relates to
dataResolution string hourly, daily, monthly or yearly (as described by provider)

Query Result Data Field:

Field name Type Description
labels array[datetime] The dates of the measurement points
values array[integer] The values of the measurement points
total integer The sum of all values

POST /api/statistics/data/export.csv

Retrieves statistical data in csv format.

Form Parameters Required Type Description
data yes array[object] A JSON object describing the statistics query to request (see below)
filter no string A comma-separated list of filters to limit the results with (see Filtering). All standard dublin core meta data fields are filterable.
limit no integer The maximum number of resources to return (see Pagination)
offset no integer The index of the first resource to return (see Pagination)

Note that limit and offset relate to the resource here, not CSV lines. There can be multiple lines in a CSV for a resource, e.g. an event. However, you cannot limit by lines, but only by e.g. events.

A query JSON object contains information about a statistics query to be executed:

Field Required Type Description
provider yes property A JSON object with information about the statistics provider to be queried
parameters yes property A JSON object containing the parameters

Here, a statistics provider JSON object has the following fields:

Field Type Description
identifier string The unique identifier of the provider
resourceType string The resource type of the provider

There parameters are the same as described above, but with one additional field:

Field name Type Description
detailLevel string EPISODE, SERIES, or ORGANIZATION (only available for CSV exports)

Example

data:

    {
      "parameters": {
        "resourceId": "mh_default_org",
        "detailLevel": "EPISODE",
        "from": "2018-12-31T23:00:00.000Z",
        "to": "2019-12-31T22:59:59.999Z",
        "dataResolution": "YEARLY"
      },
      "provider": {
        "identifier": "organization.views.sum.influx",
        "resourceType": "organization"
      }
    }

filter:

    presenters:Hans Dampf

Response

200 (OK): A (potentially empty) CSV file containing the resource statistics with all available meta data 400 (BAD REQUEST): The request was not valid