AIOZ Stream API
Analytics

Retrieve aggregated metrics

This endpoint will allow you to retrieve time-based and countable metrics like average watch time or the number of impressions over a certain period of time.

The request body when you want to retrieve data will look like this:

{
  "from": 1726001314,
  "to": 1726201314,
  "filter_by": {
    "media_ids": ["media123", "media456"],
    "media_type": "video",
    "continents": ["EU", "NA"],
    "countries": ["FR", "US"],
    "device_types": ["computer", "phone"],
    "os": ["windows", "android"],
    "browsers": ["chrome", "firefox"],
    "tags": ["tag1", "tag2"]
  }
}

For example, this would be a simplified body for this request:

{
  "from": 1726001314,
  "to": 1726201314
}

Path parameters:

- metric: Use this path parameter to select a metric that you want analytics for. - play : The number of times your content has been played. Aggregations: count ,rate ,total

  • start: The number of times playback was started. Aggregation: count

  • end: The number of times playback has ended with the content watched until the end. Aggregation: count

  • impression: The number of times your content has been loaded and was ready for playback. Aggregation: count

  • watch_time: The cumulative time in seconds that the user has spent watching your content. Aggregations: average ,sum

  • view: The number of times your content has been watched in playback. Aggregations: count

- aggregation: Use this path parameter to define a way of collecting data for the metric that you want analytics for.

  • count: returns the overall number of events for the play metric.

  • rate: returns the ratio that calculates the number of plays your content receives divided by its impressions. This aggregation can be used only with the play metric.

  • total: calculates the total number of events for the play metric.

  • average: calculates an average value for the selected metric.

  • sum: adds up the total value of the select metric.

Body parameters:

- from: Use this query parameter to define the starting date time in UNIX timestamp format of the period you want analytics for.

- to: Use this query parameter to define the ending date time in UNIX timestamp format of the period you want analytics for.

- media_ids: Returns analytics based on the unique identifiers of a video or a live stream.

- media_type: Returns analytics based on the type of content. Possible values: video ,live-stream.

- continents: Returns analytics based on the viewers' continent. The list of supported continent names is based on the GeoNames public database. Possible values: AS ,AF ,NA ,SA ,AN ,EU ,AZ.

- device_types: Returns analytics based on the type of device used by the viewers. Response values can include: computer ,phone ,tablet ,tv ,console ,wearable ,unknown.

- os: Returns analytics based on the operating system used by the viewers. Response values can include:windows ,mac osx ,android ,ios ,linux.

- os: Returns analytics based on the operating system used by the viewers. Response values can include:windows ,mac osx ,android ,ios ,linux.

- browsers: Returns analytics based on the browser used by the viewers. Response values can include: chrome ,firefox ,edge ,opera.

- tags: Returns analytics for videos using this tag.
POSThttps://api.aiozstream.network/api/analytics/metrics/data/:metric/:aggregation

Parameters

metric* The metric that you want to analytics
aggregation* The way to collect your data for the metric that you want

Headers

Authorization Bearer your_access_token_here
stream-public-key your_public_key_here
stream-secret-key your_secret_key_here

Body

from The starting date time in UNIX timestamp format of the period you want
to The ending date time in UNIX timestamp format of the period you want
filter_by The filter for your data

Response

200: OK
{
    "status": "success",
    "data": {
        "context": {
            "metric": "start",
            "aggregation": "count",
            "time_frame": {
                "from": "2024-09-11T03:48:34+07:00",
                "to": "2024-09-13T11:21:54+07:00"
            }
        },
        "data": 0
    }
}
curl --location 'https://api.aiozstream.network/api/analytics/metrics/data/start/count' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--data '{
    "from": 1726001314,
    "to": 1726201314
}'

Retrieve metrics in a breakdown of dimensions

This endpoint will allow you to retrieve countable metrics like the number of plays or impressions, grouped by the time at which they occurred.

The request body when you want to retrieve data will look like this:

{
  "from": 1726001314,
  "to": 1726201314,
  "sort_by": "metric_value",
  "filter_by": {
    "media_ids": ["media123", "media456"],
    "media_type": "video",
    "continents": ["EU", "NA"],
    "countries": ["FR", "US"],
    "device_types": ["computer", "phone"],
    "os": ["windows", "android"],
    "browsers": ["chrome", "firefox"],
    "tags": ["tag1", "tag2"]
  }
}

For example, this would be a simplified body for this request:

{
  "from": 1726001314,
  "to": 1726201314
}

Path parameters:

- metric: Use this path parameter to select a metric that you want analytics for.

  • play : The number of times your content has been played.

  • play_rate : The ratio that calculates the number of plays your content receives divided by its impressions.

  • start: The number of times playback was started.

  • end: The number of times playback has ended with the content watched until the end.

  • impression: The number of times your content has been loaded and was ready for playback.

  • watch_time: The cumulative time in seconds that the user has spent watching your content.

  • retension: The total amount of time a user has continuously engaged with your content.

  • view: The number of times your content has been watched in playback.

- breakdown: Use this path parameter to define a dimension for segmenting analytics data. You must use kebab-case for path parameters.

  • media-id: Returns analytics based on the unique identifiers of a video or a live stream.

  • media-type: Returns analytics based on the type of content. Possible values: video ,live-stream.

  • continent: Returns analytics based on the viewers' continent. The list of supported continents names are based on the GeoNames public database. Possible values are: AS ,AF ,NA ,SA ,AN ,EU ,AZ.

  • country: Returns analytics based on the viewers' country. The list of supported country names are based on the GeoNames public database.

  • device-type: Returns analytics based on the type of device used by the viewers. Response values can include: computer ,phone ,tablet ,tv ,console ,wearable ,unknown.

  • operator-system: Returns analytics based on the operating system used by the viewers. Response values can include windows ,mac osx ,android ,ios ,linux.

  • browser: Returns analytics based on the browser used by the viewers. Response values can include chrome ,firefox ,edge ,opera.

Body parameters:

- from: Use this query parameter to define the starting date time in UNIX timestamp format of the period you want analytics for.

- to: Use this query parameter to define the ending date time in UNIX timestamp format of the period you want analytics for.

- limit: Use this query parameter to define the maximum number of records to retrieve for the specified analytics period.

- offset: Use this query parameter to specify the starting position (number of records to skip) for the analytics query.

- media_ids: Returns analytics based on the unique identifiers of a video or a live stream.

- media_type: Returns analytics based on the type of content. Possible values: video ,live-stream.

- sort_by: Use this parameter to choose which field the API will use to sort the analytics data. These are the available fields to sort by: metric_value ,dimension_value.

- order_by: Use this parameter to choose how the API orders the analytics data. These are the available fields to sort by: asc ,desc.

- continents: Returns analytics based on the viewers' continent. The list of supported continent names is based on the GeoNames public database. Possible values: AS ,AF ,NA ,SA ,AN ,EU ,AZ.

- countries: Returns analytics based on the viewers' country. The list of supported country names is based on the GeoNames public database.

- device_types: Returns analytics based on the type of device used by the viewers. Response values can include: computer ,phone ,tablet ,tv ,console ,wearable ,unknown.

- os: Returns analytics based on the operating system used by the viewers. Response values can include:windows ,mac osx ,android ,ios ,linux.

- browsers: Returns analytics based on the browser used by the viewers. Response values can include: chrome ,firefox ,edge ,opera.

- tags: Returns analytics for videos using this tag.
POSThttps://api.aiozstream.network/api/analytics/metrics/bucket/:metric/:breakdown

Parameters

metric* The metric that you want to analytics
breakdown* The way to segment your data for the metric that you want

Headers

Authorization Bearer your_access_token_here
stream-public-key your_public_key_here
stream-secret-key your_secret_key_here

Body

from The starting date time in UNIX timestamp format of the period you want
to The ending date time in UNIX timestamp format of the period you want
limit The number of records to retrieve
offset The starting position for the analytics query
filter_by The filter for your data
sort_by The field or property to sort by
order_by The field or property used to determine how the result set should be sorted. Use "asc" for ascending order and "desc" for descending order.

Response

200: OK
{
    "status": "success",
    "data": {
        "context": {
            "metric": "impression",
            "time_frame": {
                "from": "2024-09-01T00:00:00Z",
                "to": "2024-09-30T00:00:00Z"
            },
            "breakdown": "media_id"
        },
        "total": 2,
        "data": [
            {
                "metric_value": 1,
                "dimension_value": "media_id_1",
                "emitted_at": "2024-09-11T16:33:38.381387+07:00"
            },
            {
                "metric_value": 1,
                "dimension_value": "media_id_2",
                "emitted_at": "2024-09-11T16:31:16.047798+07:00"
            }
        ]
    }
}
curl --location 'https://api.aiozstream.network/api/analytics/metrics/bucket/impression/media_id' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--data '{
  "from": 1726001314,
  "to": 1726201314
}'

Retrieve metrics over time

This endpoint will allow you to retrieve countable metrics like the number of plays or impressions, grouped by the time at which they occurred

The request body when you want to retrieve data will look like this:

{
  "from": 1726001314,
  "to": 1726201314,
  "sort_by": "metric",
  "filter_by": {
    "media_ids": ["media123", "media456"],
    "media_type": "video",
    "continents": ["EU", "NA"],
    "countries": ["FR", "US"],
    "device_types": ["computer", "phone"],
    "os": ["windows", "android"],
    "browsers": ["chrome", "firefox"],
    "tags": ["tag1", "tag2"]
  }
}

For example, this would be a simplified body for this request:

{
  "from": 1726001314,
  "to": 1726201314,
  "sort_by": "metric"
}

Path parameters:

- metric: Use this path parameter to select a metric that you want analytics for. - play : The number of times your content has been played.

  • play_rate : The ratio that calculates the number of plays your content receives divided by its impressions.

  • start: The number of times playback was started.

  • end: The number of times playback has ended with the content watched until the end.

  • impression: The number of times your content has been loaded and was ready for playback.

    • retension: The total amount of time a user has continuously engaged with your content.

    • watch_time: The cumulative time in seconds that the user has spent watching your content.

  • view: The number of times your content has been watched in playback.

Body parameters:

- from: Use this query parameter to define the starting date time in UNIX timestamp format of the period you want analytics for.

- to: Use this query parameter to define the ending date time in UNIX timestamp format of the period you want analytics for.

- limit: Use this query parameter to define the maximum number of records to retrieve for the specified analytics period.

- offset: Use this query parameter to specify the starting position (number of records to skip) for the analytics query.

- interval: Use this query parameter to define how granularity of the data. Possible values: hour ,day.

- media_ids: Returns analytics based on the unique identifiers of a video or a live stream.

- media_type: Returns analytics based on the type of content. Possible values: video ,live-stream.

- sort_by: Use this parameter to choose which field the API will use to sort the analytics data. These are the available fields to sort by: metric_value ,dimension_value.

- order_by: Use this parameter to choose how the API orders the analytics data. These are the available fields to sort by: asc ,desc.

- continents: Returns analytics based on the viewers' continent. The list of supported continent names is based on the GeoNames public database. Possible values: AS ,AF ,NA ,SA ,AN ,EU ,AZ.

- countries: Returns analytics based on the viewers' country. The list of supported country names is based on the GeoNames public database.

- device_types: Returns analytics based on the type of device used by the viewers. Response values can include: computer ,phone ,tablet ,tv ,console ,wearable ,unknown.

- os: Returns analytics based on the operating system used by the viewers. Response values can include:windows ,mac osx ,android ,ios ,linux.

- browsers: Returns analytics based on the browser used by the viewers. Response values can include: chrome ,firefox ,edge ,opera.

- tags: Returns analytics for videos using this tag.
POSThttps://api.aiozstream.network/api/analytics/metrics/timeseries/:metric

Parameters

metric* The metric that you want to analytics
interval* How granularity of the data (allow: day, hour)

Headers

Authorization Bearer your_access_token_here
stream-public-key your_public_key_here
stream-secret-key your_secret_key_here

Body

from The starting date time in UNIX timestamp format of the period you want
to The ending date time in UNIX timestamp format of the period you want
limit The number of records to retrieve
offset The starting position for the analytics query
filter_by The filter for your data
sort_by The field or property to sort by
order_by The field or property used to determine how the result set should be sorted. Use "asc" for ascending order and "desc" for descending order.

Response

200: OK
{
    "status": "success",
    "data": {
        "context": {
            "metric": "impression",
            "time_frame": {
                "from": "2024-09-01T00:00:00Z",
                "to": "2024-09-30T00:00:00Z"
            },
            "interval": "day"
        },
        "total": 6,
        "data": [
            {
                "metric_value": 1,
                "emitted_at": "2024-09-11T23:00:00+07:00"
            },
            {
                "metric_value": 10,
                "emitted_at": "2024-09-10T23:00:00+07:00"
            },
            {
                "metric_value": 15,
                "emitted_at": "2024-09-08T23:00:00+07:00"
            },
            {
                "metric_value": 28,
                "emitted_at": "2024-09-05T23:00:00+07:00"
            },
            {
                "metric_value": 31,
                "emitted_at": "2024-09-04T23:00:00+07:00"
            },
            {
                "metric_value": 8,
                "emitted_at": "2024-09-03T23:00:00+07:00"
            }
        ]
    }
}
curl --location 'https://api.aiozstream.network/api/analytics/metrics/timeseries/impression/day' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--data '{
  "from": 1726001314,
  "to": 1726201314,
}'
PreviousPlayersNextPayments