All URIs are relative to https://ws.api.video
| Method | HTTP request | Description |
|---|---|---|
| getAggregatedMetrics | GET /data/metrics/{metric}/{aggregation} | Retrieve aggregated metrics |
| getMetricsBreakdown | GET /data/buckets/{metric}/{breakdown} | Retrieve metrics in a breakdown of dimensions |
| getMetricsOverTime | GET /data/timeseries/{metric} | Retrieve metrics over time |
AnalyticsAggregatedMetricsResponse getAggregatedMetrics(metric, aggregation).from(from).to(to).filterBy(filterBy).execute() okhttp3.Call executeAsync(callback) ApiResponse executeWithHttpInfo()
Retrieve aggregated metrics
Retrieve time-based and countable metrics like average watch time or the number of impressions over a certain period of time.
// Import classes:
import video.api.client.ApiVideoClient;
import video.api.client.api.ApiException;
import video.api.client.api.models.*;
import video.api.client.api.clients.AnalyticsApi;
import java.util.*;
public class Example {
public static void main(String[] args) {
ApiVideoClient client = new ApiVideoClient("YOUR_API_KEY");
// if you rather like to use the sandbox environment:
// ApiVideoClient client = new ApiVideoClient("YOUR_SANDBOX_API_KEY", Environment.SANDBOX);
AnalyticsApi apiInstance = client.analytics();
String metric = "play"; // Use this path parameter to select a metric that you want analytics for. - `play` is the number of times your content has been played. You can use the aggregations `count`, `rate`, and `total` with the `play` metric. - `start` is the number of times playback was started. You can use the aggregation `count` with this metric. - `end` is the number of times playback has ended with the content watch until the end. You can use the aggregation `count` with this metric. - `impression` is the number of times your content has been loaded and was ready for playback. You can use the aggregation `count` with this metric. - `impression-time` is the time in milliseconds that your content was loading for until the first video frame is displayed. You can use the aggregations `average` and `sum` with this metric. - `watch-time` is the cumulative time in seconds that the user has spent watching your content. You can use the aggregations `average` and `sum` with this metric.
String aggregation = "count"; // 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.
OffsetDateTime from = OffsetDateTime.parse("2024-02-05T00:00:00+01:00"); // 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`.
OffsetDateTime to = OffsetDateTime.parse("2024-02-06T00:00:00+01:00"); // 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.
FilterBy2 filterBy = new HashMap(); // 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](https://www.geonames.org/countries/). 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](https://www.geonames.org/countries/). 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](https://docs.api.video/vod/tags-metadata).
filterBy.setMediaId(Arrays.asList(Arrays.asList(Arrays.asList("vi4blUQJFrYWbaG44NChkH27")))); // Returns analytics based on the unique identifiers of a video or a live stream.
filterBy.setMediaType("""video"""); //
filterBy.setContinent(Arrays.asList(Arrays.asList(Arrays.asList("EU")))); // Returns analytics based on the viewers' continent. The list of supported continents names are based on the [GeoNames public database](https://www.geonames.org/countries/). You must use the ISO-3166 alpha2 format, for example `EU`.
filterBy.setCountry(Arrays.asList(Arrays.asList(Arrays.asList("FR")))); // Returns analytics based on the viewers' country. The list of supported country names are based on the [GeoNames public database](https://www.geonames.org/countries/). You must use the ISO-3166 alpha2 format, for example `FR`.
filterBy.setDeviceType(Arrays.asList(Arrays.asList(Arrays.asList("computer")))); // Returns analytics based on the type of device used by the viewers. Response values can include: `computer`, `phone`, `tablet`, `tv`, `console`, `wearable`, `unknown`.
filterBy.setOperatingSystem(Arrays.asList(Arrays.asList(Arrays.asList("windows")))); // Returns analytics based on the operating system used by the viewers. Response values can include `windows`, `mac osx`, `android`, `ios`, `linux`.
filterBy.setBrowser(Arrays.asList(Arrays.asList(Arrays.asList("firefox")))); // Returns analytics based on the browser used by the viewers. Response values can include `chrome`, `firefox`, `edge`, `opera`.
filterBy.setTag("""Cool videos"""); // 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](https://docs.api.video/vod/tags-metadata).
try {
AnalyticsAggregatedMetricsResponse result = apiInstance.getAggregatedMetrics(metric, aggregation)
.from(from)
.to(to)
.filterBy(filterBy)
.execute();
System.out.println(result);
} catch (ApiException e) {
System.err.println("Exception when calling AnalyticsApi#getAggregatedMetrics");
System.err.println("Status code: " + e.getCode());
System.err.println("Reason: " + e.getMessage());
System.err.println("Response headers: " + e.getResponseHeaders());
e.printStackTrace();
}
}
}| Name | Type | Description | Notes |
|---|---|---|---|
| metric | String | Use this path parameter to select a metric that you want analytics for. - `play` is the number of times your content has been played. You can use the aggregations `count`, `rate`, and `total` with the `play` metric. - `start` is the number of times playback was started. You can use the aggregation `count` with this metric. - `end` is the number of times playback has ended with the content watch until the end. You can use the aggregation `count` with this metric. - `impression` is the number of times your content has been loaded and was ready for playback. You can use the aggregation `count` with this metric. - `impression-time` is the time in milliseconds that your content was loading for until the first video frame is displayed. You can use the aggregations `average` and `sum` with this metric. - `watch-time` is the cumulative time in seconds that the user has spent watching your content. You can use the aggregations `average` and `sum` with this metric. | [enum: play, start, end, impression, impression-time, watch-time] |
| aggregation | String | 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. | [enum: count, rate, total, average, sum] |
| from | OffsetDateTime | 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`. | [optional] |
| to | OffsetDateTime | 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. | [optional] |
| filterBy | FilterBy2 | 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. | [optional] |
AnalyticsAggregatedMetricsResponse
- Content-Type: Not defined
- Accept: application/json
| Status code | Description | Response headers |
|---|---|---|
| 200 | Success | * X-RateLimit-Limit - The request limit per minute. * X-RateLimit-Remaining - The number of available requests left for the current time window. * X-RateLimit-Retry-After - The number of seconds left until the current rate limit window resets. |
| 400 | Bad request error | * X-RateLimit-Limit - The request limit per minute. * X-RateLimit-Remaining - The number of available requests left for the current time window. * X-RateLimit-Retry-After - The number of seconds left until the current rate limit window resets. |
| 404 | Unrecognized request URL | * X-RateLimit-Limit - The request limit per minute. * X-RateLimit-Remaining - The number of available requests left for the current time window. * X-RateLimit-Retry-After - The number of seconds left until the current rate limit window resets. |
| 429 | Too Many Requests | * X-RateLimit-Limit - The request limit per minute. * X-RateLimit-Remaining - The number of available requests left for the current time window. * X-RateLimit-Retry-After - The number of seconds left until the current rate limit window resets. |
AnalyticsMetricsBreakdownResponse getMetricsBreakdown(metric, breakdown).from(from).to(to).sortBy(sortBy).sortOrder(sortOrder).filterBy(filterBy).currentPage(currentPage).pageSize(pageSize).execute() okhttp3.Call executeAsync(callback) ApiResponse executeWithHttpInfo()
Retrieve metrics in a breakdown of dimensions
Retrieve detailed analytics play-rate and number of impressions segmented by dimensions like country or device type.
// Import classes:
import video.api.client.ApiVideoClient;
import video.api.client.api.ApiException;
import video.api.client.api.models.*;
import video.api.client.api.clients.AnalyticsApi;
import java.util.*;
public class Example {
public static void main(String[] args) {
ApiVideoClient client = new ApiVideoClient("YOUR_API_KEY");
// if you rather like to use the sandbox environment:
// ApiVideoClient client = new ApiVideoClient("YOUR_SANDBOX_API_KEY", Environment.SANDBOX);
AnalyticsApi apiInstance = client.analytics();
String metric = "play"; // 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.
String breakdown = "media-id"; // 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](https://www.geonames.org/countries/). 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](https://www.geonames.org/countries/). - `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`.
OffsetDateTime from = OffsetDateTime.parse("2024-02-05T00:00:00+01:00"); // 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`
OffsetDateTime to = OffsetDateTime.parse("2024-02-06T00:00:00+01:00"); // 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.
String sortBy = "metricValue"; // 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.
String sortOrder = "asc"; // 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`.
FilterBy2 filterBy = new HashMap(); // 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](https://www.geonames.org/countries/). 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](https://www.geonames.org/countries/). 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](https://docs.api.video/vod/tags-metadata).
filterBy.setMediaId(Arrays.asList(Arrays.asList(Arrays.asList("vi4blUQJFrYWbaG44NChkH27")))); // Returns analytics based on the unique identifiers of a video or a live stream.
filterBy.setMediaType("""video"""); //
filterBy.setContinent(Arrays.asList(Arrays.asList(Arrays.asList("EU")))); // Returns analytics based on the viewers' continent. The list of supported continents names are based on the [GeoNames public database](https://www.geonames.org/countries/). You must use the ISO-3166 alpha2 format, for example `EU`.
filterBy.setCountry(Arrays.asList(Arrays.asList(Arrays.asList("FR")))); // Returns analytics based on the viewers' country. The list of supported country names are based on the [GeoNames public database](https://www.geonames.org/countries/). You must use the ISO-3166 alpha2 format, for example `FR`.
filterBy.setDeviceType(Arrays.asList(Arrays.asList(Arrays.asList("computer")))); // Returns analytics based on the type of device used by the viewers. Response values can include: `computer`, `phone`, `tablet`, `tv`, `console`, `wearable`, `unknown`.
filterBy.setOperatingSystem(Arrays.asList(Arrays.asList(Arrays.asList("windows")))); // Returns analytics based on the operating system used by the viewers. Response values can include `windows`, `mac osx`, `android`, `ios`, `linux`.
filterBy.setBrowser(Arrays.asList(Arrays.asList(Arrays.asList("firefox")))); // Returns analytics based on the browser used by the viewers. Response values can include `chrome`, `firefox`, `edge`, `opera`.
filterBy.setTag("""Cool videos"""); // 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](https://docs.api.video/vod/tags-metadata).
Integer currentPage = 1; // Choose the number of search results to return per page. Minimum value: 1
Integer pageSize = 25; // Results per page. Allowed values 1-100, default is 25.
try {
Page<AnalyticsMetricsBreakdownResponseData> result = apiInstance.getMetricsBreakdown(metric, breakdown)
.from(from)
.to(to)
.sortBy(sortBy)
.sortOrder(sortOrder)
.filterBy(filterBy)
.currentPage(currentPage)
.pageSize(pageSize)
.execute();
System.out.println(result);
} catch (ApiException e) {
System.err.println("Exception when calling AnalyticsApi#getMetricsBreakdown");
System.err.println("Status code: " + e.getCode());
System.err.println("Reason: " + e.getMessage());
System.err.println("Response headers: " + e.getResponseHeaders());
e.printStackTrace();
}
}
}| Name | Type | Description | Notes |
|---|---|---|---|
| metric | String | 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. | [enum: play, play-rate, play-total, start, end, impression] |
| breakdown | String | 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`. | [enum: media-id, media-type, continent, country, device-type, operating-system, browser] |
| from | OffsetDateTime | 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` | [optional] |
| to | OffsetDateTime | 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. | [optional] |
| sortBy | String | 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. | [optional] [enum: metricValue, dimensionValue] |
| sortOrder | String | 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`. | [optional] [enum: asc, desc] |
| filterBy | FilterBy2 | 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. | [optional] |
| currentPage | Integer | Choose the number of search results to return per page. Minimum value: 1 | [optional] [default to 1] |
| pageSize | Integer | Results per page. Allowed values 1-100, default is 25. | [optional] [default to 25] |
Page<AnalyticsMetricsBreakdownResponseData>
- Content-Type: Not defined
- Accept: application/json
| Status code | Description | Response headers |
|---|---|---|
| 200 | Success | * X-RateLimit-Limit - The request limit per minute. * X-RateLimit-Remaining - The number of available requests left for the current time window. * X-RateLimit-Retry-After - The number of seconds left until the current rate limit window resets. |
| 400 | Bad request error | * X-RateLimit-Limit - The request limit per minute. * X-RateLimit-Remaining - The number of available requests left for the current time window. * X-RateLimit-Retry-After - The number of seconds left until the current rate limit window resets. |
| 404 | Unrecognized request URL | * X-RateLimit-Limit - The request limit per minute. * X-RateLimit-Remaining - The number of available requests left for the current time window. * X-RateLimit-Retry-After - The number of seconds left until the current rate limit window resets. |
| 429 | Too Many Requests | * X-RateLimit-Limit - The request limit per minute. * X-RateLimit-Remaining - The number of available requests left for the current time window. * X-RateLimit-Retry-After - The number of seconds left until the current rate limit window resets. |
AnalyticsMetricsOverTimeResponse getMetricsOverTime(metric).from(from).to(to).interval(interval).sortBy(sortBy).sortOrder(sortOrder).filterBy(filterBy).currentPage(currentPage).pageSize(pageSize).execute() okhttp3.Call executeAsync(callback) ApiResponse executeWithHttpInfo()
Retrieve metrics over time
Retrieve countable metrics like the number of plays or impressions, grouped by the time at which they occurred
// Import classes:
import video.api.client.ApiVideoClient;
import video.api.client.api.ApiException;
import video.api.client.api.models.*;
import video.api.client.api.clients.AnalyticsApi;
import java.util.*;
public class Example {
public static void main(String[] args) {
ApiVideoClient client = new ApiVideoClient("YOUR_API_KEY");
// if you rather like to use the sandbox environment:
// ApiVideoClient client = new ApiVideoClient("YOUR_SANDBOX_API_KEY", Environment.SANDBOX);
AnalyticsApi apiInstance = client.analytics();
String metric = "play"; // 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. - `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.
OffsetDateTime from = OffsetDateTime.parse("2024-02-05T00:00:00+01:00"); // 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`
OffsetDateTime to = OffsetDateTime.parse("2024-02-06T00:00:00+01:00"); // 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.
String interval = "hour"; // Use this query parameter to define how granularity of the data. Possible values: `hour`, `day`. - Default: If no interval specified and the period (different between from and to) ≤ 2 days then hour, otherwise 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`.
String sortBy = "metricValue"; // 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.
String sortOrder = "asc"; // 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`.
FilterBy2 filterBy = new HashMap(); // 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](https://www.geonames.org/countries/). 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](https://www.geonames.org/countries/). 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](https://docs.api.video/vod/tags-metadata).
filterBy.setMediaId(Arrays.asList(Arrays.asList(Arrays.asList("vi4blUQJFrYWbaG44NChkH27")))); // Returns analytics based on the unique identifiers of a video or a live stream.
filterBy.setMediaType("""video"""); //
filterBy.setContinent(Arrays.asList(Arrays.asList(Arrays.asList("EU")))); // Returns analytics based on the viewers' continent. The list of supported continents names are based on the [GeoNames public database](https://www.geonames.org/countries/). You must use the ISO-3166 alpha2 format, for example `EU`.
filterBy.setCountry(Arrays.asList(Arrays.asList(Arrays.asList("FR")))); // Returns analytics based on the viewers' country. The list of supported country names are based on the [GeoNames public database](https://www.geonames.org/countries/). You must use the ISO-3166 alpha2 format, for example `FR`.
filterBy.setDeviceType(Arrays.asList(Arrays.asList(Arrays.asList("computer")))); // Returns analytics based on the type of device used by the viewers. Response values can include: `computer`, `phone`, `tablet`, `tv`, `console`, `wearable`, `unknown`.
filterBy.setOperatingSystem(Arrays.asList(Arrays.asList(Arrays.asList("windows")))); // Returns analytics based on the operating system used by the viewers. Response values can include `windows`, `mac osx`, `android`, `ios`, `linux`.
filterBy.setBrowser(Arrays.asList(Arrays.asList(Arrays.asList("firefox")))); // Returns analytics based on the browser used by the viewers. Response values can include `chrome`, `firefox`, `edge`, `opera`.
filterBy.setTag("""Cool videos"""); // 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](https://docs.api.video/vod/tags-metadata).
Integer currentPage = 1; // Choose the number of search results to return per page. Minimum value: 1
Integer pageSize = 25; // Results per page. Allowed values 1-100, default is 25.
try {
Page<AnalyticsMetricsOverTimeResponseData> result = apiInstance.getMetricsOverTime(metric)
.from(from)
.to(to)
.interval(interval)
.sortBy(sortBy)
.sortOrder(sortOrder)
.filterBy(filterBy)
.currentPage(currentPage)
.pageSize(pageSize)
.execute();
System.out.println(result);
} catch (ApiException e) {
System.err.println("Exception when calling AnalyticsApi#getMetricsOverTime");
System.err.println("Status code: " + e.getCode());
System.err.println("Reason: " + e.getMessage());
System.err.println("Response headers: " + e.getResponseHeaders());
e.printStackTrace();
}
}
}| Name | Type | Description | Notes |
|---|---|---|---|
| metric | String | 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. - `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. | [enum: play, play-rate, start, end, impression] |
| from | OffsetDateTime | 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` | [optional] |
| to | OffsetDateTime | 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. | [optional] |
| interval | String | Use this query parameter to define how granularity of the data. Possible values: `hour`, `day`. - Default: If no interval specified and the period (different between from and to) ≤ 2 days then hour, otherwise 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`. | [optional] [enum: hour, day] |
| sortBy | String | 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. | [optional] [enum: metricValue, emittedAt] |
| sortOrder | String | 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`. | [optional] [enum: asc, desc] |
| filterBy | FilterBy2 | 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. | [optional] |
| currentPage | Integer | Choose the number of search results to return per page. Minimum value: 1 | [optional] [default to 1] |
| pageSize | Integer | Results per page. Allowed values 1-100, default is 25. | [optional] [default to 25] |
Page<AnalyticsMetricsOverTimeResponseData>
- Content-Type: Not defined
- Accept: application/json
| Status code | Description | Response headers |
|---|---|---|
| 200 | Success | * X-RateLimit-Limit - The request limit per minute. * X-RateLimit-Remaining - The number of available requests left for the current time window. * X-RateLimit-Retry-After - The number of seconds left until the current rate limit window resets. |
| 400 | Bad request error | * X-RateLimit-Limit - The request limit per minute. * X-RateLimit-Remaining - The number of available requests left for the current time window. * X-RateLimit-Retry-After - The number of seconds left until the current rate limit window resets. |
| 404 | Unrecognized request URL | * X-RateLimit-Limit - The request limit per minute. * X-RateLimit-Remaining - The number of available requests left for the current time window. * X-RateLimit-Retry-After - The number of seconds left until the current rate limit window resets. |
| 429 | Too Many Requests | * X-RateLimit-Limit - The request limit per minute. * X-RateLimit-Remaining - The number of available requests left for the current time window. * X-RateLimit-Retry-After - The number of seconds left until the current rate limit window resets. |