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