diff --git a/CHANGELOG.md b/CHANGELOG.md index 6941e60..ff81482 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,9 +1,6 @@ # Changelog All changes to this project will be documented in this file. -## [2.6.7] - 2024-11-04 -- Analytics updates (ccv, views, ...) - ## [2.6.6] - 2024-10-21 - Add summary feature diff --git a/docs/api/AnalyticsApi.md b/docs/api/AnalyticsApi.md index f3bd618..399b8da 100644 --- a/docs/api/AnalyticsApi.md +++ b/docs/api/AnalyticsApi.md @@ -19,13 +19,11 @@ Retrieve time-based and countable metrics like average watch time or the number | Name | Type | Required | Description | | ------------- | ------------- | ------------- | ------------- | - | **metric** | **'play' \| 'start' \| 'end' \| 'impression' \| 'impression-time' \| 'watch-time' \| 'ccv' \| 'view'**| **yes**| 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. - `ccv`: is the number of concurrent viewers, or users watching at the same time. - `view`: the total number of viewers until this point in time. | - | **aggregation** | **'count' \| 'rate' \| 'total' \| 'average' \| 'sum' \| 'peak' \| 'live'**| **yes**| 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. - `peak` shows the highest value of the `ccv` metric in the timeframe of your request. You can use this aggregation only with the `ccv` metric. - `live` shows the highest value of the `ccv` metric from the last 20 seconds. You can use this aggregation only with the `ccv` metric. | + | **metric** | **'play' \| 'start' \| 'end' \| 'impression' \| 'impression-time' \| 'watch-time'**| **yes**| 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. | + | **aggregation** | **'count' \| 'rate' \| 'total' \| 'average' \| 'sum'**| **yes**| 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. | | **from** | **Date**| no| 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`. | | **to** | **Date**| no| 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. | - | **unique** | **boolean**| no| Use this query parameter to control how viewer data is counted: - `true` means that a single user watchig 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'**| no| 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`. | - | **filterBy** | [**FilterBy2**](../model/.md)| no| 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). - `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. | + | **filterBy** | [**FilterBy2**](../model/.md)| no| 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). | ### Return type @@ -47,15 +45,13 @@ Retrieve detailed analytics play-rate and number of impressions segmented by dim | Name | Type | Required | Description | | ------------- | ------------- | ------------- | ------------- | - | **metric** | **'play' \| 'play-rate' \| 'play-total' \| 'start' \| 'end' \| 'impression' \| 'ccv-peak' \| 'ccv-average' \| 'view'**| **yes**| 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. | - | **breakdown** | **'media-id' \| 'media-type' \| 'continent' \| 'country' \| 'device-type' \| 'operating-system' \| 'browser' \| 'referrer'**| **yes**| 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`. - `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 referrer. | + | **metric** | **'play' \| 'play-rate' \| 'play-total' \| 'start' \| 'end' \| 'impression'**| **yes**| 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. | + | **breakdown** | **'media-id' \| 'media-type' \| 'continent' \| 'country' \| 'device-type' \| 'operating-system' \| 'browser'**| **yes**| 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`. | | **from** | **Date**| no| 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` | | **to** | **Date**| no| 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'**| no| 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'**| no| 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`. | - | **unique** | **boolean**| no| Use this query parameter to control how viewer data is counted: - `true` means that a single user watchig 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'**| no| 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`. | - | **filterBy** | [**FilterBy2**](../model/.md)| no| 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). - `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. | + | **filterBy** | [**FilterBy2**](../model/.md)| no| 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). | | **currentPage** | **number**| no| Choose the number of search results to return per page. Minimum value: 1 | | **pageSize** | **number**| no| Results per page. Allowed values 1-100, default is 25. | @@ -79,15 +75,13 @@ Retrieve countable metrics like the number of plays or impressions, grouped by t | Name | Type | Required | Description | | ------------- | ------------- | ------------- | ------------- | - | **metric** | **'play' \| 'play-rate' \| 'start' \| 'end' \| 'impression' \| 'ccv-peak' \| 'ccv-average' \| 'view'**| **yes**| 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. - `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. | + | **metric** | **'play' \| 'play-rate' \| 'start' \| 'end' \| 'impression'**| **yes**| 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. | | **from** | **Date**| no| 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` | | **to** | **Date**| no| 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. | - | **interval** | **'minute' \| 'hour' \| 'day'**| no| 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 should be less than 60 minutes. | + | **interval** | **'hour' \| 'day'**| no| 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`. | | **sortBy** | **'metricValue' \| 'emittedAt'**| no| 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. | | **sortOrder** | **'asc' \| 'desc'**| no| 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`. | - | **unique** | **boolean**| no| Use this query parameter to control how viewer data is counted: - `true` means that a single user watchig 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'**| no| 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`. | - | **filterBy** | [**FilterBy2**](../model/.md)| no| 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). - `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. | + | **filterBy** | [**FilterBy2**](../model/.md)| no| 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). | | **currentPage** | **number**| no| Choose the number of search results to return per page. Minimum value: 1 | | **pageSize** | **number**| no| Results per page. Allowed values 1-100, default is 25. | diff --git a/docs/api/SummariesApi.md b/docs/api/SummariesApi.md index c37e0f4..370ae1b 100644 --- a/docs/api/SummariesApi.md +++ b/docs/api/SummariesApi.md @@ -15,7 +15,7 @@ All URIs are relative to *https://ws.api.video* ## **`create()` - Generate video summary** -Generate a title, abstract, and key takeaways for a video. +Generate an abstract and key takeaways for a video. ### Parameters @@ -37,7 +37,7 @@ Promise<[**Summary**](../model/Summary.md)>. ## **`update()` - Update summary details** -Update details for a summary. Note that this operation is only allowed for summary objects where `sourceStatus` is `missing`. +Update details for a summary. ### Parameters diff --git a/docs/model/AnalyticsAggregatedMetricsResponseContext.md b/docs/model/AnalyticsAggregatedMetricsResponseContext.md index a0969ff..f674467 100644 --- a/docs/model/AnalyticsAggregatedMetricsResponseContext.md +++ b/docs/model/AnalyticsAggregatedMetricsResponseContext.md @@ -5,7 +5,7 @@ Name | Type | Description | Notes ------------ | ------------- | ------------- | ------------- -**metric** | [**AnalyticsAggregatedMetricsResponseContextMetricEnum**](#AnalyticsAggregatedMetricsResponseContextMetricEnum) | Returns the metric and relevant parameters you selected. | [optional] +**metric** | [**AnalyticsAggregatedMetricsResponseContextMetricEnum**](#AnalyticsAggregatedMetricsResponseContextMetricEnum) | Returns the metric you selected. | [optional] **aggregation** | [**AnalyticsAggregatedMetricsResponseContextAggregationEnum**](#AnalyticsAggregatedMetricsResponseContextAggregationEnum) | Returns the aggregation you selected. | [optional] **timeframe** | [**AnalyticsAggregatedMetricsResponseContextTimeframe**](AnalyticsAggregatedMetricsResponseContextTimeframe.md) | | [optional] @@ -21,17 +21,6 @@ End | 'end' Impression | 'impression' ImpressionTime | 'impression-time' WatchTime | 'watch-time' -Ccv | 'ccv' -UniqueCcv | 'unique-ccv' -View3 | 'view-3' -View5 | 'view-5' -View10 | 'view-10' -View30 | 'view-30' -UniqueView | 'unique-view' -UniqueView3 | 'unique-view-3' -UniqueView5 | 'unique-view-5' -UniqueView10 | 'unique-view-10' -UniqueView30 | 'unique-view-30' diff --git a/docs/model/AnalyticsMetricsBreakdownResponseContext.md b/docs/model/AnalyticsMetricsBreakdownResponseContext.md index 52c8653..f3b0e50 100644 --- a/docs/model/AnalyticsMetricsBreakdownResponseContext.md +++ b/docs/model/AnalyticsMetricsBreakdownResponseContext.md @@ -5,7 +5,7 @@ Name | Type | Description | Notes ------------ | ------------- | ------------- | ------------- -**metric** | [**AnalyticsMetricsBreakdownResponseContextMetricEnum**](#AnalyticsMetricsBreakdownResponseContextMetricEnum) | Returns the metric and relevant parameters you selected. | [optional] +**metric** | [**AnalyticsMetricsBreakdownResponseContextMetricEnum**](#AnalyticsMetricsBreakdownResponseContextMetricEnum) | Returns the metric you selected. | [optional] **breakdown** | [**AnalyticsMetricsBreakdownResponseContextBreakdownEnum**](#AnalyticsMetricsBreakdownResponseContextBreakdownEnum) | Returns the dimension you selected. | [optional] **timeframe** | [**AnalyticsAggregatedMetricsResponseContextTimeframe**](AnalyticsAggregatedMetricsResponseContextTimeframe.md) | | [optional] @@ -20,19 +20,6 @@ PlayRate | 'play-rate' Start | 'start' End | 'end' Impression | 'impression' -CcvAverage | 'ccv-average' -CcvPeak | 'ccv-peak' -UniqueCcvAverage | 'unique-ccv-average' -UniqueCcvPeak | 'unique-ccv-peak' -View3 | 'view-3' -View5 | 'view-5' -View10 | 'view-10' -View30 | 'view-30' -UniqueView | 'unique-view' -UniqueView3 | 'unique-view-3' -UniqueView5 | 'unique-view-5' -UniqueView10 | 'unique-view-10' -UniqueView30 | 'unique-view-30' diff --git a/docs/model/AnalyticsMetricsOverTimeResponse.md b/docs/model/AnalyticsMetricsOverTimeResponse.md index 507e165..083b163 100644 --- a/docs/model/AnalyticsMetricsOverTimeResponse.md +++ b/docs/model/AnalyticsMetricsOverTimeResponse.md @@ -6,7 +6,7 @@ Name | Type | Description | Notes ------------ | ------------- | ------------- | ------------- **context** | [**AnalyticsMetricsOverTimeResponseContext**](AnalyticsMetricsOverTimeResponseContext.md) | | -**data** | [**Array<AnalyticsMetricsOverTimeResponseData>**](AnalyticsMetricsOverTimeResponseData.md) | Returns an array of metrics and the timestamps. | +**data** | [**Array<AnalyticsMetricsOverTimeResponseData>**](AnalyticsMetricsOverTimeResponseData.md) | Returns an array of metrics and the timestamps . | **pagination** | [**Pagination**](Pagination.md) | | diff --git a/docs/model/AnalyticsMetricsOverTimeResponseContext.md b/docs/model/AnalyticsMetricsOverTimeResponseContext.md index d09e847..d3775b6 100644 --- a/docs/model/AnalyticsMetricsOverTimeResponseContext.md +++ b/docs/model/AnalyticsMetricsOverTimeResponseContext.md @@ -5,7 +5,7 @@ Name | Type | Description | Notes ------------ | ------------- | ------------- | ------------- -**metric** | [**AnalyticsMetricsOverTimeResponseContextMetricEnum**](#AnalyticsMetricsOverTimeResponseContextMetricEnum) | Returns the metric and relevant parameters you selected. | [optional] +**metric** | [**AnalyticsMetricsOverTimeResponseContextMetricEnum**](#AnalyticsMetricsOverTimeResponseContextMetricEnum) | Returns the metric you selected. | [optional] **interval** | [**AnalyticsMetricsOverTimeResponseContextIntervalEnum**](#AnalyticsMetricsOverTimeResponseContextIntervalEnum) | Returns the interval you selected. | [optional] **timeframe** | [**AnalyticsAggregatedMetricsResponseContextTimeframe**](AnalyticsAggregatedMetricsResponseContextTimeframe.md) | | [optional] @@ -20,19 +20,6 @@ PlayRate | 'play-rate' Start | 'start' End | 'end' Impression | 'impression' -CcvAverage | 'ccv-average' -CcvPeak | 'ccv-peak' -UniqueCcvAverage | 'unique-ccv-average' -UniqueCcvPeak | 'unique-ccv-peak' -View3 | 'view-3' -View5 | 'view-5' -View10 | 'view-10' -View30 | 'view-30' -UniqueView | 'unique-view' -UniqueView3 | 'unique-view-3' -UniqueView5 | 'unique-view-5' -UniqueView10 | 'unique-view-10' -UniqueView30 | 'unique-view-30' @@ -40,7 +27,6 @@ UniqueView30 | 'unique-view-30' Name | Value ---- | ----- -Minute | 'minute' Hour | 'hour' Day | 'day' diff --git a/docs/model/FilterBy.md b/docs/model/FilterBy.md index 55017dd..024a468 100644 --- a/docs/model/FilterBy.md +++ b/docs/model/FilterBy.md @@ -13,7 +13,6 @@ Name | Type | Description | Notes **operatingSystem** | **Array<string>** | Returns analytics based on the operating system used by the viewers. Response values can include `windows`, `mac osx`, `android`, `ios`, `linux`. | [optional] **browser** | **Array<string>** | Returns analytics based on the browser used by the viewers. Response values can include `chrome`, `firefox`, `edge`, `opera`. | [optional] **tag** | **string** | 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). | [optional] -**referrer** | **Array<string>** | 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. | [optional] diff --git a/docs/model/FilterBy1.md b/docs/model/FilterBy1.md index 0688254..c2b7215 100644 --- a/docs/model/FilterBy1.md +++ b/docs/model/FilterBy1.md @@ -13,7 +13,6 @@ Name | Type | Description | Notes **operatingSystem** | **Array<string>** | Returns analytics based on the operating system used by the viewers. Response values can include `windows`, `mac osx`, `android`, `ios`, `linux`. | [optional] **browser** | **Array<string>** | Returns analytics based on the browser used by the viewers. Response values can include `chrome`, `firefox`, `edge`, `opera`. | [optional] **tag** | **string** | 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). | [optional] -**referrer** | **Array<string>** | 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. | [optional] diff --git a/docs/model/FilterBy2.md b/docs/model/FilterBy2.md index ed9e0af..9b7fdcf 100644 --- a/docs/model/FilterBy2.md +++ b/docs/model/FilterBy2.md @@ -13,7 +13,6 @@ Name | Type | Description | Notes **operatingSystem** | **Array<string>** | Returns analytics based on the operating system used by the viewers. Response values can include `windows`, `mac osx`, `android`, `ios`, `linux`. | [optional] **browser** | **Array<string>** | Returns analytics based on the browser used by the viewers. Response values can include `chrome`, `firefox`, `edge`, `opera`. | [optional] **tag** | **string** | 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). | [optional] -**referrer** | **Array<string>** | 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. | [optional] diff --git a/docs/model/SummaryCreationPayload.md b/docs/model/SummaryCreationPayload.md index 852d30b..a893f6d 100644 --- a/docs/model/SummaryCreationPayload.md +++ b/docs/model/SummaryCreationPayload.md @@ -7,6 +7,7 @@ Name | Type | Description | Notes ------------ | ------------- | ------------- | ------------- **videoId** | **string** | Create a summary of a video using the video ID. | **origin** | [**SummaryCreationPayloadOriginEnum**](#SummaryCreationPayloadOriginEnum) | Use this parameter to define how the API generates the summary. The only allowed value is `auto`, which means that the API generates a summary automatically. If you do not set this parameter, **the API will not generate a summary automatically**. In this case, `sourceStatus` will return `missing`, and you have to manually add a summary using the `PATCH /summaries/{summaryId}/source` endpoint operation. | [optional] +**attributes** | [**Array<SummaryCreationPayloadAttributesEnum>**](#Array<SummaryCreationPayloadAttributesEnum>) | Use this parameter to define the elements of a summary that you want to generate. If you do not define this parameter, the API generates a full summary with all attributes. | [optional] @@ -18,3 +19,12 @@ Auto | 'auto' +## Enum: Array<SummaryCreationPayloadAttributesEnum> + +Name | Value +---- | ----- +Abstract | 'abstract' +Takeaways | 'takeaways' + + + diff --git a/docs/model/SummarySource.md b/docs/model/SummarySource.md index c242ddd..4c821ea 100644 --- a/docs/model/SummarySource.md +++ b/docs/model/SummarySource.md @@ -5,7 +5,6 @@ Name | Type | Description | Notes ------------ | ------------- | ------------- | ------------- -**title** | **string** | A video title, based on the contents of the video. | [optional] **_abstract** | **string** | A short outline of the contents of the video. The length of an `abstract` depends on the amount of content in a video that can be transcribed. The API condenses the contents into minimum 20, maximum 300 words. | [optional] **takeaways** | **Array<string>** | A list of 3 key points from the video, in chronological order. | [optional] diff --git a/docs/model/SummaryUpdatePayload.md b/docs/model/SummaryUpdatePayload.md index ca2ff80..f97fba1 100644 --- a/docs/model/SummaryUpdatePayload.md +++ b/docs/model/SummaryUpdatePayload.md @@ -5,7 +5,6 @@ Name | Type | Description | Notes ------------ | ------------- | ------------- | ------------- -**title** | **string** | A video title, based on the contents of the video. | [optional] **_abstract** | **string** | A short outline of the contents of the video. | [optional] **takeaways** | **Array<string>** | A list of 3 key points from the video, in chronological order. | [optional] diff --git a/docs/model/VideoCreationPayload.md b/docs/model/VideoCreationPayload.md index 5659914..35b6e2a 100644 --- a/docs/model/VideoCreationPayload.md +++ b/docs/model/VideoCreationPayload.md @@ -19,6 +19,7 @@ Name | Type | Description | Notes **language** | [**VideoCreationPayloadLanguageEnum**](#VideoCreationPayloadLanguageEnum) | Use this parameter to set the language of the video. When this parameter is set, the API creates a transcript of the video using the language you specify. You must use the [IETF language tag](https://en.wikipedia.org/wiki/IETF_language_tag) format. `language` is a permanent attribute of the video. You can update it to another language using the [`PATCH /videos/{videoId}`](https://docs.api.video/reference/api/Videos#update-a-video-object) operation. This triggers the API to generate a new transcript using a different language. | [optional] **transcript** | **boolean** | Use this parameter to enable transcription. - When `true`, the API generates a transcript for the video. - The default value is `false`. - If you define a video language using the `language` parameter, the API uses that language to transcribe the video. If you do not define a language, the API detects it based on the video. - When the API generates a transcript, it will be available as a caption for the video. | [optional] **transcriptSummary** | **boolean** | Use this parameter to enable summarization. We recommend using this parameter together with `transcript: true`. - When `true`, the API generates a summary for the video, based on the transcription. - The default value is `false`. - If you define a video language using the `language` parameter, the API uses that language to summarize the video. If you do not define a language, the API detects it based on the video. | [optional] +**transcriptSummaryAttributes** | [**Array<VideoCreationPayloadTranscriptSummaryAttributesEnum>**](#Array<VideoCreationPayloadTranscriptSummaryAttributesEnum>) | Use this parameter to define the elements of a summary that you want to generate. If you do not define this parameter, the API generates a full summary with all attributes. | [optional] @@ -62,3 +63,12 @@ Zh | 'zh' +## Enum: Array<VideoCreationPayloadTranscriptSummaryAttributesEnum> + +Name | Value +---- | ----- +Abstract | 'abstract' +Takeaways | 'takeaways' + + + diff --git a/docs/model/VideoUpdatePayload.md b/docs/model/VideoUpdatePayload.md index ea75053..7bbb08b 100644 --- a/docs/model/VideoUpdatePayload.md +++ b/docs/model/VideoUpdatePayload.md @@ -16,6 +16,7 @@ Name | Type | Description | Notes **language** | [**VideoUpdatePayloadLanguageEnum**](#VideoUpdatePayloadLanguageEnum) | Use this parameter to set the language of the video. When this parameter is set, the API creates a transcript of the video using the language you specify. You must use the [IETF language tag](https://en.wikipedia.org/wiki/IETF_language_tag) format. `language` is a permanent attribute of the video. You can update it to another language using the [`PATCH /videos/{videoId}`](https://docs.api.video/reference/api/Videos#update-a-video-object) operation. This triggers the API to generate a new transcript using a different language. | [optional] **transcript** | **boolean** | Use this parameter to enable transcription. - When `true`, the API generates a transcript for the video. - The default value is `false`. - If you define a video language using the `language` parameter, the API uses that language to transcribe the video. If you do not define a language, the API detects it based on the video. - When the API generates a transcript, it will be available as a caption for the video. | [optional] **transcriptSummary** | **boolean** | Use this parameter to enable summarization. - When `true`, the API generates a summary for the video, based on the transcription. - The default value is `false`. - If you define a video language using the `language` parameter, the API uses that language to summarize the video. If you do not define a language, the API detects it based on the video. | [optional] +**transcriptSummaryAttributes** | [**Array<VideoUpdatePayloadTranscriptSummaryAttributesEnum>**](#Array<VideoUpdatePayloadTranscriptSummaryAttributesEnum>) | Use this parameter to define the elements of a summary that you want to generate. If you do not define this parameter, the API generates a full summary with all attributes. | [optional] @@ -59,3 +60,12 @@ Zh | 'zh' +## Enum: Array<VideoUpdatePayloadTranscriptSummaryAttributesEnum> + +Name | Value +---- | ----- +Abstract | 'abstract' +Takeaways | 'takeaways' + + + diff --git a/package.json b/package.json index a10b9df..d7c87a3 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@api.video/nodejs-client", - "version": "2.6.7", + "version": "2.6.6", "description": "api.video nodejs API client", "keywords": [ "api.video", diff --git a/src/HttpClient.ts b/src/HttpClient.ts index b201aa4..d6ef8bc 100644 --- a/src/HttpClient.ts +++ b/src/HttpClient.ts @@ -59,7 +59,7 @@ export default class HttpClient { this.chunkSize = params.chunkSize; this.headers = new AxiosHeaders({ Accept: 'application/json, */*;q=0.8', - 'AV-Origin-Client': 'nodejs:2.6.7', + 'AV-Origin-Client': 'nodejs:2.6.6', Authorization: this.apiKey ? `Basic ${encode(`${this.apiKey}:`)}` : '', ...(params.applicationName && params.applicationVersion ? { diff --git a/src/ObjectSerializer.ts b/src/ObjectSerializer.ts index 55b0313..1091b42 100644 --- a/src/ObjectSerializer.ts +++ b/src/ObjectSerializer.ts @@ -128,10 +128,13 @@ const enumsMap: Set = new Set([ 'SummaryOriginEnum', 'SummarySourceStatusEnum', 'SummaryCreationPayloadOriginEnum', + 'SummaryCreationPayloadAttributesEnum', 'VideoLanguageOriginEnum', 'VideoCreationPayloadLanguageEnum', + 'VideoCreationPayloadTranscriptSummaryAttributesEnum', 'VideoStatusIngestStatusEnum', 'VideoUpdatePayloadLanguageEnum', + 'VideoUpdatePayloadTranscriptSummaryAttributesEnum', ]); const typeMap: { [index: string]: any } = { diff --git a/src/api/AnalyticsApi.ts b/src/api/AnalyticsApi.ts index fad1b69..a212df9 100644 --- a/src/api/AnalyticsApi.ts +++ b/src/api/AnalyticsApi.ts @@ -31,13 +31,11 @@ export default class AnalyticsApi { * Retrieve time-based and countable metrics like average watch time or the number of impressions over a certain period of time. * Retrieve aggregated metrics * @param {Object} searchParams - * @param { 'play' | 'start' | 'end' | 'impression' | 'impression-time' | 'watch-time' | 'ccv' | 'view' } searchParams.metric 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. - `ccv`: is the number of concurrent viewers, or users watching at the same time. - `view`: the total number of viewers until this point in time. - * @param { 'count' | 'rate' | 'total' | 'average' | 'sum' | 'peak' | 'live' } searchParams.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. - `peak` shows the highest value of the `ccv` metric in the timeframe of your request. You can use this aggregation only with the `ccv` metric. - `live` shows the highest value of the `ccv` metric from the last 20 seconds. You can use this aggregation only with the `ccv` metric. + * @param { 'play' | 'start' | 'end' | 'impression' | 'impression-time' | 'watch-time' } searchParams.metric 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. + * @param { 'count' | 'rate' | 'total' | 'average' | 'sum' } searchParams.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. * @param { Date } searchParams.from 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`. * @param { Date } searchParams.to 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. - * @param { boolean } searchParams.unique Use this query parameter to control how viewer data is counted: - `true` means that a single user watchig 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. - * @param { '3s' | '5s' | '10s' | '30s' } searchParams.viewDuration 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`. - * @param { FilterBy2 } searchParams.filterBy 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). - `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. + * @param { FilterBy2 } searchParams.filterBy 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). */ public async getAggregatedMetrics(args: { metric: @@ -46,21 +44,10 @@ export default class AnalyticsApi { | 'end' | 'impression' | 'impression-time' - | 'watch-time' - | 'ccv' - | 'view'; - aggregation: - | 'count' - | 'rate' - | 'total' - | 'average' - | 'sum' - | 'peak' - | 'live'; + | 'watch-time'; + aggregation: 'count' | 'rate' | 'total' | 'average' | 'sum'; from?: Date; to?: Date; - unique?: boolean; - viewDuration?: '3s' | '5s' | '10s' | '30s'; filterBy?: FilterBy2; }): Promise { return this.getAggregatedMetricsWithResponseHeaders(args).then( @@ -72,21 +59,17 @@ export default class AnalyticsApi { * Retrieve time-based and countable metrics like average watch time or the number of impressions over a certain period of time. * Retrieve aggregated metrics * @param {Object} searchParams - * @param { 'play' | 'start' | 'end' | 'impression' | 'impression-time' | 'watch-time' | 'ccv' | 'view' } searchParams.metric 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. - `ccv`: is the number of concurrent viewers, or users watching at the same time. - `view`: the total number of viewers until this point in time. - * @param { 'count' | 'rate' | 'total' | 'average' | 'sum' | 'peak' | 'live' } searchParams.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. - `peak` shows the highest value of the `ccv` metric in the timeframe of your request. You can use this aggregation only with the `ccv` metric. - `live` shows the highest value of the `ccv` metric from the last 20 seconds. You can use this aggregation only with the `ccv` metric. + * @param { 'play' | 'start' | 'end' | 'impression' | 'impression-time' | 'watch-time' } searchParams.metric 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. + * @param { 'count' | 'rate' | 'total' | 'average' | 'sum' } searchParams.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. * @param { Date } searchParams.from 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`. * @param { Date } searchParams.to 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. - * @param { boolean } searchParams.unique Use this query parameter to control how viewer data is counted: - `true` means that a single user watchig 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. - * @param { '3s' | '5s' | '10s' | '30s' } searchParams.viewDuration 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`. - * @param { FilterBy2 } searchParams.filterBy 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). - `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. + * @param { FilterBy2 } searchParams.filterBy 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). */ public async getAggregatedMetricsWithResponseHeaders({ metric, aggregation, from, to, - unique, - viewDuration, filterBy, }: { metric: @@ -95,21 +78,10 @@ export default class AnalyticsApi { | 'end' | 'impression' | 'impression-time' - | 'watch-time' - | 'ccv' - | 'view'; - aggregation: - | 'count' - | 'rate' - | 'total' - | 'average' - | 'sum' - | 'peak' - | 'live'; + | 'watch-time'; + aggregation: 'count' | 'rate' | 'total' | 'average' | 'sum'; from?: Date; to?: Date; - unique?: boolean; - viewDuration?: '3s' | '5s' | '10s' | '30s'; filterBy?: FilterBy2; }): Promise<{ headers: ApiResponseHeaders; @@ -151,22 +123,6 @@ export default class AnalyticsApi { ObjectSerializer.serialize(to, 'Date', 'date-time') ); } - if (unique !== undefined) { - urlSearchParams.append( - 'unique', - ObjectSerializer.serialize(unique, 'boolean', '') - ); - } - if (viewDuration !== undefined) { - urlSearchParams.append( - 'viewDuration', - ObjectSerializer.serialize( - viewDuration, - "'3s' | '5s' | '10s' | '30s'", - '' - ) - ); - } if (filterBy !== undefined) { if (typeof filterBy !== 'object') { throw new Error(`${filterBy} is not an object`); @@ -215,15 +171,13 @@ export default class AnalyticsApi { * Retrieve detailed analytics play-rate and number of impressions segmented by dimensions like country or device type. * Retrieve metrics in a breakdown of dimensions * @param {Object} searchParams - * @param { 'play' | 'play-rate' | 'play-total' | 'start' | 'end' | 'impression' | 'ccv-peak' | 'ccv-average' | 'view' } searchParams.metric 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. - * @param { 'media-id' | 'media-type' | 'continent' | 'country' | 'device-type' | 'operating-system' | 'browser' | 'referrer' } searchParams.breakdown 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`. - `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 referrer. + * @param { 'play' | 'play-rate' | 'play-total' | 'start' | 'end' | 'impression' } searchParams.metric 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. + * @param { 'media-id' | 'media-type' | 'continent' | 'country' | 'device-type' | 'operating-system' | 'browser' } searchParams.breakdown 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`. * @param { Date } searchParams.from 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` * @param { Date } searchParams.to 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. * @param { 'metricValue' | 'dimensionValue' } searchParams.sortBy 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. * @param { 'asc' | 'desc' } searchParams.sortOrder 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`. - * @param { boolean } searchParams.unique Use this query parameter to control how viewer data is counted: - `true` means that a single user watchig 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. - * @param { '3s' | '5s' | '10s' | '30s' } searchParams.viewDuration 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`. - * @param { FilterBy2 } searchParams.filterBy 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). - `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. + * @param { FilterBy2 } searchParams.filterBy 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). * @param { number } searchParams.currentPage Choose the number of search results to return per page. Minimum value: 1 * @param { number } searchParams.pageSize Results per page. Allowed values 1-100, default is 25. */ @@ -234,10 +188,7 @@ export default class AnalyticsApi { | 'play-total' | 'start' | 'end' - | 'impression' - | 'ccv-peak' - | 'ccv-average' - | 'view'; + | 'impression'; breakdown: | 'media-id' | 'media-type' @@ -245,14 +196,11 @@ export default class AnalyticsApi { | 'country' | 'device-type' | 'operating-system' - | 'browser' - | 'referrer'; + | 'browser'; from?: Date; to?: Date; sortBy?: 'metricValue' | 'dimensionValue'; sortOrder?: 'asc' | 'desc'; - unique?: boolean; - viewDuration?: '3s' | '5s' | '10s' | '30s'; filterBy?: FilterBy2; currentPage?: number; pageSize?: number; @@ -266,15 +214,13 @@ export default class AnalyticsApi { * Retrieve detailed analytics play-rate and number of impressions segmented by dimensions like country or device type. * Retrieve metrics in a breakdown of dimensions * @param {Object} searchParams - * @param { 'play' | 'play-rate' | 'play-total' | 'start' | 'end' | 'impression' | 'ccv-peak' | 'ccv-average' | 'view' } searchParams.metric 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. - * @param { 'media-id' | 'media-type' | 'continent' | 'country' | 'device-type' | 'operating-system' | 'browser' | 'referrer' } searchParams.breakdown 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`. - `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 referrer. + * @param { 'play' | 'play-rate' | 'play-total' | 'start' | 'end' | 'impression' } searchParams.metric 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. + * @param { 'media-id' | 'media-type' | 'continent' | 'country' | 'device-type' | 'operating-system' | 'browser' } searchParams.breakdown 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`. * @param { Date } searchParams.from 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` * @param { Date } searchParams.to 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. * @param { 'metricValue' | 'dimensionValue' } searchParams.sortBy 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. * @param { 'asc' | 'desc' } searchParams.sortOrder 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`. - * @param { boolean } searchParams.unique Use this query parameter to control how viewer data is counted: - `true` means that a single user watchig 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. - * @param { '3s' | '5s' | '10s' | '30s' } searchParams.viewDuration 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`. - * @param { FilterBy2 } searchParams.filterBy 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). - `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. + * @param { FilterBy2 } searchParams.filterBy 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). * @param { number } searchParams.currentPage Choose the number of search results to return per page. Minimum value: 1 * @param { number } searchParams.pageSize Results per page. Allowed values 1-100, default is 25. */ @@ -285,8 +231,6 @@ export default class AnalyticsApi { to, sortBy, sortOrder, - unique, - viewDuration, filterBy, currentPage, pageSize, @@ -297,10 +241,7 @@ export default class AnalyticsApi { | 'play-total' | 'start' | 'end' - | 'impression' - | 'ccv-peak' - | 'ccv-average' - | 'view'; + | 'impression'; breakdown: | 'media-id' | 'media-type' @@ -308,14 +249,11 @@ export default class AnalyticsApi { | 'country' | 'device-type' | 'operating-system' - | 'browser' - | 'referrer'; + | 'browser'; from?: Date; to?: Date; sortBy?: 'metricValue' | 'dimensionValue'; sortOrder?: 'asc' | 'desc'; - unique?: boolean; - viewDuration?: '3s' | '5s' | '10s' | '30s'; filterBy?: FilterBy2; currentPage?: number; pageSize?: number; @@ -372,22 +310,6 @@ export default class AnalyticsApi { ObjectSerializer.serialize(sortOrder, "'asc' | 'desc'", '') ); } - if (unique !== undefined) { - urlSearchParams.append( - 'unique', - ObjectSerializer.serialize(unique, 'boolean', '') - ); - } - if (viewDuration !== undefined) { - urlSearchParams.append( - 'viewDuration', - ObjectSerializer.serialize( - viewDuration, - "'3s' | '5s' | '10s' | '30s'", - '' - ) - ); - } if (filterBy !== undefined) { if (typeof filterBy !== 'object') { throw new Error(`${filterBy} is not an object`); @@ -448,35 +370,23 @@ export default class AnalyticsApi { * Retrieve countable metrics like the number of plays or impressions, grouped by the time at which they occurred * Retrieve metrics over time * @param {Object} searchParams - * @param { 'play' | 'play-rate' | 'start' | 'end' | 'impression' | 'ccv-peak' | 'ccv-average' | 'view' } searchParams.metric 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. - `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. + * @param { 'play' | 'play-rate' | 'start' | 'end' | 'impression' } searchParams.metric 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. * @param { Date } searchParams.from 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` * @param { Date } searchParams.to 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. - * @param { 'minute' | 'hour' | 'day' } searchParams.interval 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 should be less than 60 minutes. + * @param { 'hour' | 'day' } searchParams.interval 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`. * @param { 'metricValue' | 'emittedAt' } searchParams.sortBy 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. * @param { 'asc' | 'desc' } searchParams.sortOrder 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`. - * @param { boolean } searchParams.unique Use this query parameter to control how viewer data is counted: - `true` means that a single user watchig 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. - * @param { '3s' | '5s' | '10s' | '30s' } searchParams.viewDuration 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`. - * @param { FilterBy2 } searchParams.filterBy 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). - `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. + * @param { FilterBy2 } searchParams.filterBy 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). * @param { number } searchParams.currentPage Choose the number of search results to return per page. Minimum value: 1 * @param { number } searchParams.pageSize Results per page. Allowed values 1-100, default is 25. */ public async getMetricsOverTime(args: { - metric: - | 'play' - | 'play-rate' - | 'start' - | 'end' - | 'impression' - | 'ccv-peak' - | 'ccv-average' - | 'view'; + metric: 'play' | 'play-rate' | 'start' | 'end' | 'impression'; from?: Date; to?: Date; - interval?: 'minute' | 'hour' | 'day'; + interval?: 'hour' | 'day'; sortBy?: 'metricValue' | 'emittedAt'; sortOrder?: 'asc' | 'desc'; - unique?: boolean; - viewDuration?: '3s' | '5s' | '10s' | '30s'; filterBy?: FilterBy2; currentPage?: number; pageSize?: number; @@ -490,15 +400,13 @@ export default class AnalyticsApi { * Retrieve countable metrics like the number of plays or impressions, grouped by the time at which they occurred * Retrieve metrics over time * @param {Object} searchParams - * @param { 'play' | 'play-rate' | 'start' | 'end' | 'impression' | 'ccv-peak' | 'ccv-average' | 'view' } searchParams.metric 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. - `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. + * @param { 'play' | 'play-rate' | 'start' | 'end' | 'impression' } searchParams.metric 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. * @param { Date } searchParams.from 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` * @param { Date } searchParams.to 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. - * @param { 'minute' | 'hour' | 'day' } searchParams.interval 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 should be less than 60 minutes. + * @param { 'hour' | 'day' } searchParams.interval 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`. * @param { 'metricValue' | 'emittedAt' } searchParams.sortBy 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. * @param { 'asc' | 'desc' } searchParams.sortOrder 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`. - * @param { boolean } searchParams.unique Use this query parameter to control how viewer data is counted: - `true` means that a single user watchig 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. - * @param { '3s' | '5s' | '10s' | '30s' } searchParams.viewDuration 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`. - * @param { FilterBy2 } searchParams.filterBy 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). - `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. + * @param { FilterBy2 } searchParams.filterBy 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). * @param { number } searchParams.currentPage Choose the number of search results to return per page. Minimum value: 1 * @param { number } searchParams.pageSize Results per page. Allowed values 1-100, default is 25. */ @@ -509,28 +417,16 @@ export default class AnalyticsApi { interval, sortBy, sortOrder, - unique, - viewDuration, filterBy, currentPage, pageSize, }: { - metric: - | 'play' - | 'play-rate' - | 'start' - | 'end' - | 'impression' - | 'ccv-peak' - | 'ccv-average' - | 'view'; + metric: 'play' | 'play-rate' | 'start' | 'end' | 'impression'; from?: Date; to?: Date; - interval?: 'minute' | 'hour' | 'day'; + interval?: 'hour' | 'day'; sortBy?: 'metricValue' | 'emittedAt'; sortOrder?: 'asc' | 'desc'; - unique?: boolean; - viewDuration?: '3s' | '5s' | '10s' | '30s'; filterBy?: FilterBy2; currentPage?: number; pageSize?: number; @@ -568,7 +464,7 @@ export default class AnalyticsApi { if (interval !== undefined) { urlSearchParams.append( 'interval', - ObjectSerializer.serialize(interval, "'minute' | 'hour' | 'day'", '') + ObjectSerializer.serialize(interval, "'hour' | 'day'", '') ); } if (sortBy !== undefined) { @@ -583,22 +479,6 @@ export default class AnalyticsApi { ObjectSerializer.serialize(sortOrder, "'asc' | 'desc'", '') ); } - if (unique !== undefined) { - urlSearchParams.append( - 'unique', - ObjectSerializer.serialize(unique, 'boolean', '') - ); - } - if (viewDuration !== undefined) { - urlSearchParams.append( - 'viewDuration', - ObjectSerializer.serialize( - viewDuration, - "'3s' | '5s' | '10s' | '30s'", - '' - ) - ); - } if (filterBy !== undefined) { if (typeof filterBy !== 'object') { throw new Error(`${filterBy} is not an object`); diff --git a/src/api/SummariesApi.ts b/src/api/SummariesApi.ts index fa7a42c..7b8cc15 100644 --- a/src/api/SummariesApi.ts +++ b/src/api/SummariesApi.ts @@ -29,7 +29,7 @@ export default class SummariesApi { } /** - * Generate a title, abstract, and key takeaways for a video. + * Generate an abstract and key takeaways for a video. * Generate video summary * @param summaryCreationPayload */ @@ -42,7 +42,7 @@ export default class SummariesApi { } /** - * Generate a title, abstract, and key takeaways for a video. + * Generate an abstract and key takeaways for a video. * Generate video summary * @param summaryCreationPayload */ @@ -95,7 +95,7 @@ export default class SummariesApi { } /** - * Update details for a summary. Note that this operation is only allowed for summary objects where `sourceStatus` is `missing`. + * Update details for a summary. * Update summary details * @param summaryId The unique identifier of the summary source you want to update. * @param summaryUpdatePayload @@ -110,7 +110,7 @@ export default class SummariesApi { } /** - * Update details for a summary. Note that this operation is only allowed for summary objects where `sourceStatus` is `missing`. + * Update details for a summary. * Update summary details * @param summaryId The unique identifier of the summary source you want to update. * @param summaryUpdatePayload diff --git a/src/model/AnalyticsAggregatedMetricsResponseContext.ts b/src/model/AnalyticsAggregatedMetricsResponseContext.ts index 348773c..b02c32d 100644 --- a/src/model/AnalyticsAggregatedMetricsResponseContext.ts +++ b/src/model/AnalyticsAggregatedMetricsResponseContext.ts @@ -14,7 +14,7 @@ import AnalyticsAggregatedMetricsResponseContextTimeframe from './AnalyticsAggre export default class AnalyticsAggregatedMetricsResponseContext { /** - * Returns the metric and relevant parameters you selected. + * Returns the metric you selected. */ 'metric'?: AnalyticsAggregatedMetricsResponseContextMetricEnum; /** @@ -57,18 +57,7 @@ export type AnalyticsAggregatedMetricsResponseContextMetricEnum = | 'end' | 'impression' | 'impression-time' - | 'watch-time' - | 'ccv' - | 'unique-ccv' - | 'view-3' - | 'view-5' - | 'view-10' - | 'view-30' - | 'unique-view' - | 'unique-view-3' - | 'unique-view-5' - | 'unique-view-10' - | 'unique-view-30'; + | 'watch-time'; export type AnalyticsAggregatedMetricsResponseContextAggregationEnum = | 'count' | 'rate' diff --git a/src/model/AnalyticsMetricsBreakdownResponseContext.ts b/src/model/AnalyticsMetricsBreakdownResponseContext.ts index 9a21f66..be016a6 100644 --- a/src/model/AnalyticsMetricsBreakdownResponseContext.ts +++ b/src/model/AnalyticsMetricsBreakdownResponseContext.ts @@ -14,7 +14,7 @@ import AnalyticsAggregatedMetricsResponseContextTimeframe from './AnalyticsAggre export default class AnalyticsMetricsBreakdownResponseContext { /** - * Returns the metric and relevant parameters you selected. + * Returns the metric you selected. */ 'metric'?: AnalyticsMetricsBreakdownResponseContextMetricEnum; /** @@ -56,20 +56,7 @@ export type AnalyticsMetricsBreakdownResponseContextMetricEnum = | 'play-rate' | 'start' | 'end' - | 'impression' - | 'ccv-average' - | 'ccv-peak' - | 'unique-ccv-average' - | 'unique-ccv-peak' - | 'view-3' - | 'view-5' - | 'view-10' - | 'view-30' - | 'unique-view' - | 'unique-view-3' - | 'unique-view-5' - | 'unique-view-10' - | 'unique-view-30'; + | 'impression'; export type AnalyticsMetricsBreakdownResponseContextBreakdownEnum = | 'media-id' | 'media-type' diff --git a/src/model/AnalyticsMetricsOverTimeResponse.ts b/src/model/AnalyticsMetricsOverTimeResponse.ts index 154806d..7c11238 100644 --- a/src/model/AnalyticsMetricsOverTimeResponse.ts +++ b/src/model/AnalyticsMetricsOverTimeResponse.ts @@ -17,7 +17,7 @@ import Pagination from './Pagination.js'; export default class AnalyticsMetricsOverTimeResponse { 'context': AnalyticsMetricsOverTimeResponseContext; /** - * Returns an array of metrics and the timestamps. + * Returns an array of metrics and the timestamps . */ 'data': Array; 'pagination': Pagination; diff --git a/src/model/AnalyticsMetricsOverTimeResponseContext.ts b/src/model/AnalyticsMetricsOverTimeResponseContext.ts index ba54746..0f6af99 100644 --- a/src/model/AnalyticsMetricsOverTimeResponseContext.ts +++ b/src/model/AnalyticsMetricsOverTimeResponseContext.ts @@ -14,7 +14,7 @@ import AnalyticsAggregatedMetricsResponseContextTimeframe from './AnalyticsAggre export default class AnalyticsMetricsOverTimeResponseContext { /** - * Returns the metric and relevant parameters you selected. + * Returns the metric you selected. */ 'metric'?: AnalyticsMetricsOverTimeResponseContextMetricEnum; /** @@ -56,21 +56,7 @@ export type AnalyticsMetricsOverTimeResponseContextMetricEnum = | 'play-rate' | 'start' | 'end' - | 'impression' - | 'ccv-average' - | 'ccv-peak' - | 'unique-ccv-average' - | 'unique-ccv-peak' - | 'view-3' - | 'view-5' - | 'view-10' - | 'view-30' - | 'unique-view' - | 'unique-view-3' - | 'unique-view-5' - | 'unique-view-10' - | 'unique-view-30'; + | 'impression'; export type AnalyticsMetricsOverTimeResponseContextIntervalEnum = - | 'minute' | 'hour' | 'day'; diff --git a/src/model/FilterBy.ts b/src/model/FilterBy.ts index a15cc44..a9d9e99 100644 --- a/src/model/FilterBy.ts +++ b/src/model/FilterBy.ts @@ -41,10 +41,6 @@ export default class FilterBy { * 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). */ 'tag'?: string; - /** - * 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. - */ - 'referrer'?: Array; static readonly discriminator?: string = undefined; @@ -97,12 +93,6 @@ export default class FilterBy { type: 'string', format: '', }, - { - name: 'referrer', - baseName: 'referrer', - type: 'Array', - format: 'uri', - }, ]; static getAttributeTypeMap(): Array { diff --git a/src/model/FilterBy1.ts b/src/model/FilterBy1.ts index 128b3de..6c4aaa6 100644 --- a/src/model/FilterBy1.ts +++ b/src/model/FilterBy1.ts @@ -41,10 +41,6 @@ export default class FilterBy1 { * 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). */ 'tag'?: string; - /** - * 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. - */ - 'referrer'?: Array; static readonly discriminator?: string = undefined; @@ -97,12 +93,6 @@ export default class FilterBy1 { type: 'string', format: '', }, - { - name: 'referrer', - baseName: 'referrer', - type: 'Array', - format: 'uri', - }, ]; static getAttributeTypeMap(): Array { diff --git a/src/model/FilterBy2.ts b/src/model/FilterBy2.ts index ace0a3a..ca25a91 100644 --- a/src/model/FilterBy2.ts +++ b/src/model/FilterBy2.ts @@ -41,10 +41,6 @@ export default class FilterBy2 { * 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). */ 'tag'?: string; - /** - * 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. - */ - 'referrer'?: Array; static readonly discriminator?: string = undefined; @@ -97,12 +93,6 @@ export default class FilterBy2 { type: 'string', format: '', }, - { - name: 'referrer', - baseName: 'referrer', - type: 'Array', - format: 'uri', - }, ]; static getAttributeTypeMap(): Array { diff --git a/src/model/SummaryCreationPayload.ts b/src/model/SummaryCreationPayload.ts index 0a733f3..0cb9479 100644 --- a/src/model/SummaryCreationPayload.ts +++ b/src/model/SummaryCreationPayload.ts @@ -20,6 +20,10 @@ export default class SummaryCreationPayload { * Use this parameter to define how the API generates the summary. The only allowed value is `auto`, which means that the API generates a summary automatically. If you do not set this parameter, **the API will not generate a summary automatically**. In this case, `sourceStatus` will return `missing`, and you have to manually add a summary using the `PATCH /summaries/{summaryId}/source` endpoint operation. */ 'origin'?: SummaryCreationPayloadOriginEnum; + /** + * Use this parameter to define the elements of a summary that you want to generate. If you do not define this parameter, the API generates a full summary with all attributes. + */ + 'attributes'?: Array; static readonly discriminator?: string = undefined; @@ -36,6 +40,12 @@ export default class SummaryCreationPayload { type: 'SummaryCreationPayloadOriginEnum', format: '', }, + { + name: 'attributes', + baseName: 'attributes', + type: 'Array', + format: '', + }, ]; static getAttributeTypeMap(): Array { @@ -44,3 +54,4 @@ export default class SummaryCreationPayload { } export type SummaryCreationPayloadOriginEnum = 'auto'; +export type SummaryCreationPayloadAttributesEnum = 'abstract' | 'takeaways'; diff --git a/src/model/SummarySource.ts b/src/model/SummarySource.ts index b2582cd..fdfe6a2 100644 --- a/src/model/SummarySource.ts +++ b/src/model/SummarySource.ts @@ -12,10 +12,6 @@ import AttributeType from './AttributeType.js'; export default class SummarySource { - /** - * A video title, based on the contents of the video. - */ - 'title'?: string; /** * A short outline of the contents of the video. The length of an `abstract` depends on the amount of content in a video that can be transcribed. The API condenses the contents into minimum 20, maximum 300 words. */ @@ -28,12 +24,6 @@ export default class SummarySource { static readonly discriminator?: string = undefined; static readonly attributeTypeMap: Array = [ - { - name: 'title', - baseName: 'title', - type: 'string', - format: '', - }, { name: '_abstract', baseName: 'abstract', diff --git a/src/model/SummaryUpdatePayload.ts b/src/model/SummaryUpdatePayload.ts index 6417787..a467317 100644 --- a/src/model/SummaryUpdatePayload.ts +++ b/src/model/SummaryUpdatePayload.ts @@ -12,10 +12,6 @@ import AttributeType from './AttributeType.js'; export default class SummaryUpdatePayload { - /** - * A video title, based on the contents of the video. - */ - 'title'?: string; /** * A short outline of the contents of the video. */ @@ -28,12 +24,6 @@ export default class SummaryUpdatePayload { static readonly discriminator?: string = undefined; static readonly attributeTypeMap: Array = [ - { - name: 'title', - baseName: 'title', - type: 'string', - format: '', - }, { name: '_abstract', baseName: 'abstract', diff --git a/src/model/VideoCreationPayload.ts b/src/model/VideoCreationPayload.ts index 67795bb..15fb608 100644 --- a/src/model/VideoCreationPayload.ts +++ b/src/model/VideoCreationPayload.ts @@ -65,6 +65,10 @@ export default class VideoCreationPayload { * Use this parameter to enable summarization. We recommend using this parameter together with `transcript: true`. - When `true`, the API generates a summary for the video, based on the transcription. - The default value is `false`. - If you define a video language using the `language` parameter, the API uses that language to summarize the video. If you do not define a language, the API detects it based on the video. */ 'transcriptSummary'?: boolean; + /** + * Use this parameter to define the elements of a summary that you want to generate. If you do not define this parameter, the API generates a full summary with all attributes. + */ + 'transcriptSummaryAttributes'?: Array; static readonly discriminator?: string = undefined; @@ -153,6 +157,12 @@ export default class VideoCreationPayload { type: 'boolean', format: '', }, + { + name: 'transcriptSummaryAttributes', + baseName: 'transcriptSummaryAttributes', + type: 'Array', + format: '', + }, ]; static getAttributeTypeMap(): Array { @@ -194,3 +204,6 @@ export type VideoCreationPayloadLanguageEnum = | 'ur' | 'vi' | 'zh'; +export type VideoCreationPayloadTranscriptSummaryAttributesEnum = + | 'abstract' + | 'takeaways'; diff --git a/src/model/VideoUpdatePayload.ts b/src/model/VideoUpdatePayload.ts index cebef93..22127cc 100644 --- a/src/model/VideoUpdatePayload.ts +++ b/src/model/VideoUpdatePayload.ts @@ -57,6 +57,10 @@ export default class VideoUpdatePayload { * Use this parameter to enable summarization. - When `true`, the API generates a summary for the video, based on the transcription. - The default value is `false`. - If you define a video language using the `language` parameter, the API uses that language to summarize the video. If you do not define a language, the API detects it based on the video. */ 'transcriptSummary'?: boolean; + /** + * Use this parameter to define the elements of a summary that you want to generate. If you do not define this parameter, the API generates a full summary with all attributes. + */ + 'transcriptSummaryAttributes'?: Array; static readonly discriminator?: string = undefined; @@ -127,6 +131,12 @@ export default class VideoUpdatePayload { type: 'boolean', format: '', }, + { + name: 'transcriptSummaryAttributes', + baseName: 'transcriptSummaryAttributes', + type: 'Array', + format: '', + }, ]; static getAttributeTypeMap(): Array { @@ -168,3 +178,6 @@ export type VideoUpdatePayloadLanguageEnum = | 'ur' | 'vi' | 'zh'; +export type VideoUpdatePayloadTranscriptSummaryAttributesEnum = + | 'abstract' + | 'takeaways'; diff --git a/test/payloads/analytics/getAggregatedMetrics/responses400-2.json b/test/payloads/analytics/getAggregatedMetrics/responses400-2.json deleted file mode 100644 index d7d510f..0000000 --- a/test/payloads/analytics/getAggregatedMetrics/responses400-2.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "type" : "https://docs.api.video/reference/request-invalid-query-parameter", - "title" : "A query parameter is invalid.", - "status" : 400, - "detail" : "This value should not contain more than 2048 characters.", - "name" : "filterBy[referrer]" -} \ No newline at end of file diff --git a/test/payloads/analytics/getAggregatedMetrics/responses400-3.json b/test/payloads/analytics/getAggregatedMetrics/responses400-3.json deleted file mode 100644 index 8199ab8..0000000 --- a/test/payloads/analytics/getAggregatedMetrics/responses400-3.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "type" : "https://docs.api.video/reference/request-invalid-query-parameter", - "title" : "A query parameter is invalid.", - "status" : 400, - "detail" : "This view duration is invalid. Use one of \"3s\", \"5s\", \"10s\", \"30s\".", - "name" : "viewDuration" -} \ No newline at end of file diff --git a/test/payloads/analytics/getMetricsBreakdown/responses400-2.json b/test/payloads/analytics/getMetricsBreakdown/responses400-2.json deleted file mode 100644 index d7d510f..0000000 --- a/test/payloads/analytics/getMetricsBreakdown/responses400-2.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "type" : "https://docs.api.video/reference/request-invalid-query-parameter", - "title" : "A query parameter is invalid.", - "status" : 400, - "detail" : "This value should not contain more than 2048 characters.", - "name" : "filterBy[referrer]" -} \ No newline at end of file diff --git a/test/payloads/analytics/getMetricsBreakdown/responses400-3.json b/test/payloads/analytics/getMetricsBreakdown/responses400-3.json deleted file mode 100644 index 8199ab8..0000000 --- a/test/payloads/analytics/getMetricsBreakdown/responses400-3.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "type" : "https://docs.api.video/reference/request-invalid-query-parameter", - "title" : "A query parameter is invalid.", - "status" : 400, - "detail" : "This view duration is invalid. Use one of \"3s\", \"5s\", \"10s\", \"30s\".", - "name" : "viewDuration" -} \ No newline at end of file diff --git a/test/payloads/analytics/getMetricsOverTime/responses400-2.json b/test/payloads/analytics/getMetricsOverTime/responses400-2.json deleted file mode 100644 index f7c9d42..0000000 --- a/test/payloads/analytics/getMetricsOverTime/responses400-2.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "type" : "https://docs.api.video/reference/request-invalid-query-parameter", - "title" : "A query parameter is invalid.", - "status" : 400, - "detail" : "This interval is invalid. Use one of \"minute\", \"hour\", \"day\".", - "name" : "interval" -} \ No newline at end of file diff --git a/test/payloads/analytics/getMetricsOverTime/responses400-3.json b/test/payloads/analytics/getMetricsOverTime/responses400-3.json deleted file mode 100644 index 333be94..0000000 --- a/test/payloads/analytics/getMetricsOverTime/responses400-3.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "type" : "https://docs.api.video/reference/request-invalid-query-parameter", - "title" : "A query parameter is invalid.", - "status" : 400, - "detail" : "This interval cannot be used with a timeframe over 60 minutes.", - "name" : "interval" -} \ No newline at end of file diff --git a/test/payloads/analytics/getMetricsOverTime/responses400-4.json b/test/payloads/analytics/getMetricsOverTime/responses400-4.json deleted file mode 100644 index d7d510f..0000000 --- a/test/payloads/analytics/getMetricsOverTime/responses400-4.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "type" : "https://docs.api.video/reference/request-invalid-query-parameter", - "title" : "A query parameter is invalid.", - "status" : 400, - "detail" : "This value should not contain more than 2048 characters.", - "name" : "filterBy[referrer]" -} \ No newline at end of file diff --git a/test/payloads/analytics/getMetricsOverTime/responses400-5.json b/test/payloads/analytics/getMetricsOverTime/responses400-5.json deleted file mode 100644 index 8199ab8..0000000 --- a/test/payloads/analytics/getMetricsOverTime/responses400-5.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "type" : "https://docs.api.video/reference/request-invalid-query-parameter", - "title" : "A query parameter is invalid.", - "status" : 400, - "detail" : "This view duration is invalid. Use one of \"3s\", \"5s\", \"10s\", \"30s\".", - "name" : "viewDuration" -} \ No newline at end of file