latestOpenAPI 3.0.02026-07-175989869.3 KB

45ec26f342b6

Analytics

Retrieve metrics in a breakdown of dimensions

Retrieve detailed analytics play-rate and number of impressions segmented by dimensions like country or device type.

get/data/buckets/{metric}/{breakdown}

Path parameters

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

play is the number of times your content has been played.
play-rate is the ratio that calculates the number of plays your content receives divided by its impressions.
play-total is the total number of times a specific content has been played. You can only use the media-id breakdown with this metric.
start is the number of times playback was started.
end is the number of times playback has ended with the content watch until the end.
impression is the number of times your content has been loaded and was ready for playback.
ccv-peak is the highest number of concurrent viewers in the timeframe of your request.
ccv-average is the average number of concurrent viewers in the timeframe of your request.
view is the total number of viewers until this point in time.

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

These are the available dimensions:

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 and 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.
operating-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.
referrer: Returns the URL where the view originates from, for example a website where the video is embedded. View events from Android and iOS return empty strings as the value for referrer.

Query parameters

fromstring date-time

Use this query parameter to define the starting date-time of the period you want analytics for.

If you do not set a value for from, the default assigned value is 1 day ago, based on the to parameter.
The maximum value is 30 days ago.
The value you provide should follow the ATOM date-time format: 2024-02-05T00:00:00+01:00

tostring date-time

Use this query parameter to define the ending date-time of the period you want analytics for.

If you do not set a value for to, the default assigned value is now.
The value for to is a non-inclusive value: the API returns data before the date-time that you set.

sortBy'metricValue' | 'dimensionValue'

Use this parameter to choose which field the API will use to sort the analytics data.

These are the available fields to sort by:

metricValue: Sorts the results based on the metric you selected in your request.
dimensionValue: Sorts the results based on the dimension you selected in your request.

sortOrder'asc' | 'desc'

Use this parameter to define the sort order of results.

These are the available sort orders:

asc: Sorts the results in ascending order: A to Z and 0 to 9.
desc: Sorts the results in descending order: Z to A and 9 to 0.

uniqueboolean

Use this query parameter to control how viewer data is counted:

true means that a single user watching multiple times counts as 1 unique viewer
false means that all views count, even if from the same user.

The API accepts this parameter only when you use the ccv-peak, ccv-average, or view metric.

Viewers are unique for 1 day.

The API determines uniqueness based on a viewer's user-agent and IP address. This means that the API can filter viewers using multiple tabs to watch the same video multiple times, but cannot filter for viewers who use multiple browsers to watch the same content multiple times.

viewDuration'3s' | '5s' | '10s' | '30s'

Use this query parameter to define how many seconds a view has to last to be counted in analytics data.

You can only use this parameter together with the view metric.
The accepted values are 3s, 5s, 10s, and 30s.
If you do not set this parameter, the API defaults to 5s.

currentPageinteger

Choose the number of search results to return per page. Minimum value: 1

pageSizeinteger

Results per page. Allowed values 1-100, default is 25.

Parameters

#/components/parameters/filterBy_2 — unresolved $ref

Response

Success

Example response

{
  "pagination": {
    "itemsTotal": 123,
    "pagesTotal": 7,
    "pageSize": 20,
    "currentPage": 3,
    "currentPageItems": 20,
    "links": {
      "first": {
        "rel": "first",
        "uri": "/videos/search?currentPage=1&pageSize=20"
      },
      "previous": {
        "rel": "previous",
        "uri": "/videos/search?currentPage=2&pageSize=20"
      },
      "next": {
        "rel": "next",
        "uri": "/videos/search?currentPage=4&pageSize=20"
      },
      "last": {
        "rel": "last",
        "uri": "/videos/search?currentPage=6&pageSize=20"
      }
    }
  },
  "data": [
    {
      "dimensionValue": "dimensionValue",
      "metricValue": 0.8008282
    },
    {
      "dimensionValue": "dimensionValue",
      "metricValue": 0.8008282
    }
  ],
  "context": {
    "timeframe": {
      "from": "2024-05-28T11:15:07Z",
      "to": "2024-05-29T11:15:07Z"
    },
    "metric": "impression",
    "breakdown": "country"
  }
}