Analytics

Analytics

get/data/metrics/{metric}/{aggregation}

Retrieve aggregated metrics

Retrieve time-based and countable metrics like average watch time or the number of impressions over a certain period of time.

fromstring

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
The API ignores this parameter when you call /data/metrics/play/total.

Format: date-time
Example: "2024-02-05T00:00:00+01:00"

tostring

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 API ignores this parameter when you call /data/metrics/play/total.
The value for to is a non-inclusive value: the API returns data before the date-time that you set.

Format: date-time
Example: "2024-02-06T00:00:00+01:00"

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 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.

Example: true

viewDurationstring

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 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.

Enum: 3s
5s
10s
30s
Example: "5s"

filterByobject

Use this parameter to filter the API's response based on different data dimensions. You can serialize filters in your query to receive more detailed breakdowns of your analytics.

If you do not set a value for filterBy, the API returns the full dataset for your project.
The API only accepts the mediaId and mediaType filters when you call /data/metrics/play/total or /data/buckets/play-total/media-id.

These are the available breakdown dimensions:

mediaId: Returns analytics based on the unique identifiers of a video or a live stream.
mediaType: 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. You must use the ISO-3166 alpha2 format, for example EU. 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. You must use the ISO-3166 alpha2 format, for example FR.
deviceType: Returns analytics based on the type of device used by the viewers. Response values can include: computer, phone, tablet, tv, console, wearable, unknown.
operatingSystem: 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.
tag: Returns analytics for videos using this tag. This filter only accepts a single value and is case sensitive. Read more about tagging your videos here.
referrer: Filters data based on the URL where the view is originating from. Accepts an empty string as a value to filter view events where no referrer is available.

Example: "filterBy[country]=FR&filterBy[operatingSystem]=windows&filterBy[browser][]=firefox&filterBy[browser][]=chrome&filterBy[tag]=Cool videos"

mediaIdarray

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

Example: [ "vi4blUQJFrYWbaG44NChkH27" ]

mediaTypestring

Enum: video
live-stream
Example: "video"

continentarray

Returns analytics based on the viewers' continent. The list of supported continents names are based on the GeoNames public database. You must use the ISO-3166 alpha2 format, for example EU.

Example: [ "EU" ]

countryarray

Returns analytics based on the viewers' country. The list of supported country names are based on the GeoNames public database. You must use the ISO-3166 alpha2 format, for example FR.

Example: [ "FR" ]

deviceTypearray

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

Example: [ "computer" ]

operatingSystemarray

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

Example: [ "windows" ]

browserarray

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

Example: [ "firefox" ]

tagstring

Returns analytics for videos using this tag. This filter only accepts a single value and is case sensitive. Read more about tagging your videos here.

Example: "Cool videos"

referrerarray

Filters data based on the URL where the view is originating from. This filter parameter accepts an empty string to filter view events where no referrer is available.

The API filters for exact matches. Include the trailing / characters if needed.
The URLs you add must be URL encoded.

Example: [ "https%3A%2F%2Fmy-awesome-videos.com" ]

Responses

Request examples

FilterBy2 filterBy = new FilterBy2();

filterBy.setBrowser(Collections.singletonList("Chrome"));
filterBy.setContinent(Arrays.asList(FilterBy2.ContinentEnum.NA, FilterBy2.ContinentEnum.EU));
filterBy.setMediaType(FilterBy2.MediaTypeEnum.VIDEO);
filterBy.setTag("test");


AnalyticsAggregatedMetricsResponse res = apiClient.analytics().getAggregatedMetrics("play", "total").filterBy(filterBy).execute();
System.out.println(res.getData());

Response examples

Success

{
  "context": {
    "metric": "impression",
    "aggregation": "count",
    "timeframe": {
      "from": "2024-05-28T11:15:07+00:00",
      "to": "2024-05-29T11:15:07+00:00"
    }
  },
  "data": 346.5
}

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

Retrieve metrics in a breakdown of dimensions

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

fromstring

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

Format: date-time
Example: "2024-02-05T00:00:00+01:00"

tostring

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.

Format: date-time
Example: "2024-02-06T00:00:00+01:00"

sortBystring

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.

Enum: metricValue
dimensionValue
Example: "metricValue"

sortOrderstring

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.

Enum: asc
desc
Example: "asc"

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.

Example: true

viewDurationstring

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.

Enum: 3s
5s
10s
30s

filterByobject

Use this parameter to filter the API's response based on different data dimensions. You can serialize filters in your query to receive more detailed breakdowns of your analytics.

If you do not set a value for filterBy, the API returns the full dataset for your project.
The API only accepts the mediaId and mediaType filters when you call /data/metrics/play/total or /data/buckets/play-total/media-id.

These are the available breakdown dimensions:

mediaId: Returns analytics based on the unique identifiers of a video or a live stream.
mediaType: 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. You must use the ISO-3166 alpha2 format, for example EU. 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. You must use the ISO-3166 alpha2 format, for example FR.
deviceType: Returns analytics based on the type of device used by the viewers. Response values can include: computer, phone, tablet, tv, console, wearable, unknown.
operatingSystem: 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.
tag: Returns analytics for videos using this tag. This filter only accepts a single value and is case sensitive. Read more about tagging your videos here.
referrer: Filters data based on the URL where the view is originating from. Accepts an empty string as a value to filter view events where no referrer is available.

Example: "filterBy[country]=FR&filterBy[operatingSystem]=windows&filterBy[browser][]=firefox&filterBy[browser][]=chrome&filterBy[tag]=Cool videos"

mediaIdarray

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

Example: [ "vi4blUQJFrYWbaG44NChkH27" ]

mediaTypestring

Enum: video
live-stream
Example: "video"

continentarray

Returns analytics based on the viewers' continent. The list of supported continents names are based on the GeoNames public database. You must use the ISO-3166 alpha2 format, for example EU.

Example: [ "EU" ]

countryarray

Returns analytics based on the viewers' country. The list of supported country names are based on the GeoNames public database. You must use the ISO-3166 alpha2 format, for example FR.

Example: [ "FR" ]

deviceTypearray

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

Example: [ "computer" ]

operatingSystemarray

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

Example: [ "windows" ]

browserarray

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

Example: [ "firefox" ]

tagstring

Returns analytics for videos using this tag. This filter only accepts a single value and is case sensitive. Read more about tagging your videos here.

Example: "Cool videos"

referrerarray

Filters data based on the URL where the view is originating from. This filter parameter accepts an empty string to filter view events where no referrer is available.

The API filters for exact matches. Include the trailing / characters if needed.
The URLs you add must be URL encoded.

Example: [ "https%3A%2F%2Fmy-awesome-videos.com" ]

currentPageint

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

Default: 1
Example: 2

pageSizeint

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

Default: 25
Example: 30

Responses

Request examples

FilterBy2 filterBy = new FilterBy2();

filterBy.setBrowser(Collections.singletonList("Chrome"));
filterBy.setContinent(Arrays.asList(FilterBy2.ContinentEnum.NA, FilterBy2.ContinentEnum.EU));
filterBy.setMediaType(FilterBy2.MediaTypeEnum.VIDEO);
filterBy.setTag("test");

Page<AnalyticsMetricsBreakdownResponseData> res = apiClient.analytics().getMetricsBreakdown("play", "media-id").filterBy(filterBy).pageSize(30).execute();
for (AnalyticsMetricsBreakdownResponseData item : res.getItems()) {
    System.out.println(item.getDimensionValue() + ": " + item.getMetricValue());
}

Response examples

Success

{
  "context": {
    "metric": "play",
    "breakdown": "country",
    "timeframe": {
      "from": "2024-04-28T07:15:05+00:00",
      "to": "2024-05-29T11:25:37+00:00"
    }
  },
  "data": [
    {
      "metricValue": 7,
      "dimensionValue": "FR"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "currentPageItems": 1,
    "pageSize": 25,
    "pagesTotal": 1,
    "itemsTotal": 1,
    "links": [
      {
        "rel": "self",
        "uri": "/data/buckets/play/country?from=2024-04-28T09%3A15%3A05%2B02%3A00&currentPage=1&pageSize=25"
      },
      {
        "rel": "first",
        "uri": "/data/buckets/play/country?from=2024-04-28T09%3A15%3A05%2B02%3A00&currentPage=1&pageSize=25"
      },
      {
        "rel": "last",
        "uri": "/data/buckets/play/country?from=2024-04-28T09%3A15%3A05%2B02%3A00&currentPage=1&pageSize=25"
      }
    ]
  }
}

get/data/timeseries/{metric}

Retrieve metrics over time

Retrieve countable metrics like the number of plays or impressions, grouped by the time at which they occurred

fromstring

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

Format: date-time
Example: "2024-02-05T00:00:00+01:00"

tostring

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.

Format: date-time
Example: "2024-02-06T00:00:00+01:00"

intervalstring

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

If you do not set a value for interval, and the period you set using the from and to parameters is less than or equals to 2 days, then the default assigned value is hour. Otherwise the API sets it to day.
When you set minute as interval, the timeframe you define with the from and to parameters must be less than 60 minutes.

Enum: minute
hour
day
Example: "hour"

sortBystring

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.
emittedAt: Sorts the results based on the timestamp of the event in ATOM date-time format.

Enum: metricValue
emittedAt
Example: "metricValue"

sortOrderstring

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.

Enum: asc
desc
Example: "asc"

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.

Example: true

viewDurationstring

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.

Enum: 3s
5s
10s
30s

filterByobject

Use this parameter to filter the API's response based on different data dimensions. You can serialize filters in your query to receive more detailed breakdowns of your analytics.

If you do not set a value for filterBy, the API returns the full dataset for your project.
The API only accepts the mediaId and mediaType filters when you call /data/metrics/play/total or /data/buckets/play-total/media-id.

These are the available breakdown dimensions:

mediaId: Returns analytics based on the unique identifiers of a video or a live stream.
mediaType: 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. You must use the ISO-3166 alpha2 format, for example EU. 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. You must use the ISO-3166 alpha2 format, for example FR.
deviceType: Returns analytics based on the type of device used by the viewers. Response values can include: computer, phone, tablet, tv, console, wearable, unknown.
operatingSystem: 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.
tag: Returns analytics for videos using this tag. This filter only accepts a single value and is case sensitive. Read more about tagging your videos here.
referrer: Filters data based on the URL where the view is originating from. Accepts an empty string as a value to filter view events where no referrer is available.

Example: "filterBy[country]=FR&filterBy[operatingSystem]=windows&filterBy[browser][]=firefox&filterBy[browser][]=chrome&filterBy[tag]=Cool videos"

mediaIdarray

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

Example: [ "vi4blUQJFrYWbaG44NChkH27" ]

mediaTypestring

Enum: video
live-stream
Example: "video"

continentarray

Returns analytics based on the viewers' continent. The list of supported continents names are based on the GeoNames public database. You must use the ISO-3166 alpha2 format, for example EU.

Example: [ "EU" ]

countryarray

Returns analytics based on the viewers' country. The list of supported country names are based on the GeoNames public database. You must use the ISO-3166 alpha2 format, for example FR.

Example: [ "FR" ]

deviceTypearray

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

Example: [ "computer" ]

operatingSystemarray

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

Example: [ "windows" ]

browserarray

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

Example: [ "firefox" ]

tagstring

Returns analytics for videos using this tag. This filter only accepts a single value and is case sensitive. Read more about tagging your videos here.

Example: "Cool videos"

referrerarray

Filters data based on the URL where the view is originating from. This filter parameter accepts an empty string to filter view events where no referrer is available.

The API filters for exact matches. Include the trailing / characters if needed.
The URLs you add must be URL encoded.

Example: [ "https%3A%2F%2Fmy-awesome-videos.com" ]

currentPageint

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

Default: 1
Example: 2

pageSizeint

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

Default: 25
Example: 30

Responses

Request examples

FilterBy2 filterBy = new FilterBy2();

filterBy.setBrowser(Collections.singletonList("Chrome"));
filterBy.setContinent(Arrays.asList(FilterBy2.ContinentEnum.NA, FilterBy2.ContinentEnum.EU));
filterBy.setMediaType(FilterBy2.MediaTypeEnum.VIDEO);
filterBy.setTag("test");

Page<AnalyticsMetricsOverTimeResponseData> res = apiClient.analytics().getMetricsOverTime("play").filterBy(filterBy).pageSize(30).execute();
for (AnalyticsMetricsOverTimeResponseData item : res.getItems()) {
    System.out.println(item.getEmittedAt() + ": " + item.getMetricValue());
}

Response examples

Success

{
  "context": {
    "metric": "play",
    "interval": "hour",
    "timeframe": {
      "from": "2024-05-28T11:08:39+00:00",
      "to": "2024-05-29T11:08:39+00:00"
    }
  },
  "data": [
    {
      "emittedAt": "2024-05-29T07+00:00:00:00",
      "metricValue": 2
    },
    {
      "emittedAt": "2024-05-29T08+00:00:00:00",
      "metricValue": 1
    },
    {
      "emittedAt": "2024-05-29T09+00:00:00:00",
      "metricValue": 1
    }
  ],
  "pagination": {
    "currentPage": 1,
    "currentPageItems": 3,
    "pageSize": 25,
    "pagesTotal": 1,
    "itemsTotal": 3,
    "links": [
      {
        "rel": "self",
        "uri": "/data/timeseries/play?currentPage=1&pageSize=25"
      },
      {
        "rel": "first",
        "uri": "/data/timeseries/play?currentPage=1&pageSize=25"
      },
      {
        "rel": "last",
        "uri": "/data/timeseries/play?currentPage=1&pageSize=25"
      }
    ]
  }
}

Was this page helpful?