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