From f3e03af2a90f2f2b87a1e23853a2405c6ab7ae34 Mon Sep 17 00:00:00 2001 From: szekelyzol Date: Mon, 4 Nov 2024 14:42:41 +0000 Subject: [PATCH] Analytics updates --- openapi.yaml | 258 +++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 250 insertions(+), 8 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index 3530901..6d45fd1 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -13006,6 +13006,8 @@ paths: - `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. required: true style: simple explode: false @@ -13018,6 +13020,8 @@ paths: - impression - impression-time - watch-time + - ccv + - view - name: aggregation in: path description: | @@ -13028,6 +13032,8 @@ paths: - `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. style: simple explode: false required: true @@ -13039,6 +13045,8 @@ paths: - total - average - sum + - peak + - live - name: from in: query description: | @@ -13068,6 +13076,42 @@ paths: type: string format: date-time example: 2024-02-06T00:00:00+01:00 + - name: unique + in: query + description: | + Use this query parameter to control how viewer data is counted: + + - `true` means that a single user watching multiple times counts as 1 unique viewer + - `false` means that all views count, even if from the same user. + + The API accepts this parameter only when you use the `ccv` or `view` metric. + + Viewers are unique for 1 day. + + The API determines uniqueness based on a viewer's `user-agent` and IP address. This means that the API can filter viewers using multiple tabs to watch the same video multiple times, but cannot filter for viewers who use multiple browsers to watch the same content multiple times. + style: form + explode: false + schema: + type: boolean + example: true + - name: viewDuration + in: query + description: | + Use this query parameter to define how many seconds a view has to last to be counted in analytics data. + + - You can only use this parameter with the `view` metric. + - The accepted values are `3s`, `5s`, `10s`, and `30s`. + - If you do not set this parameter, the API defaults to `5s`. + style: form + explode: false + schema: + type: string + enum: + - 3s + - 5s + - 10s + - 30s + example: 5s - $ref: '#/components/parameters/filterBy' responses: '200': @@ -13136,6 +13180,22 @@ paths: status: 400 detail: This field was not expected. name: from:2024-05-20T09:15:05+02:00 + Referrer too long: + description: Occurs when the value of `referrer` in your query is too long. + value: + 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] + Invalid view duration: + description: Occurs when the value of `viewDuration` is incorrect. + value: + 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 '404': headers: X-RateLimit-Limit: @@ -13273,6 +13333,9 @@ paths: - `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. required: true style: simple explode: false @@ -13285,6 +13348,9 @@ paths: - start - end - impression + - ccv-peak + - ccv-average + - view - name: breakdown in: path description: | @@ -13299,6 +13365,7 @@ paths: - `device-type`: Returns analytics based on the type of device used by the viewers. Response values can include: `computer`, `phone`, `tablet`, `tv`, `console`, `wearable`, `unknown`. - `operating-system`: Returns analytics based on the operating system used by the viewers. Response values can include `windows`, `mac osx`, `android`, `ios`, `linux`. - `browser`: Returns analytics based on the browser used by the viewers. Response values can include `chrome`, `firefox`, `edge`, `opera`. + - `referrer`: Returns the URL where the view originates from, for example a website where the video is embedded. View events from Android and iOS return empty strings as the value for `referrer`. style: simple explode: false required: true @@ -13312,6 +13379,7 @@ paths: - device-type - operating-system - browser + - referrer - name: from in: query description: | @@ -13374,6 +13442,41 @@ paths: - asc - desc example: asc + - name: unique + in: query + description: | + Use this query parameter to control how viewer data is counted: + + - `true` means that a single user watching multiple times counts as 1 unique viewer + - `false` means that all views count, even if from the same user. + + The API accepts this parameter only when you use the `ccv-peak`, `ccv-average`, or `view` metric. + + Viewers are unique for 1 day. + + The API determines uniqueness based on a viewer's `user-agent` and IP address. This means that the API can filter viewers using multiple tabs to watch the same video multiple times, but cannot filter for viewers who use multiple browsers to watch the same content multiple times. + style: form + explode: false + schema: + type: boolean + example: true + - name: viewDuration + in: query + description: | + 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`. + style: form + explode: false + schema: + type: string + enum: + - 3s + - 5s + - 10s + - 30s - $ref: '#/components/parameters/filterBy' - $ref: '#/components/parameters/current-page' - $ref: '#/components/parameters/page-size' @@ -13459,6 +13562,22 @@ paths: status: 400 detail: This field was not expected. name: from:2024-05-20T09:15:05+02:00 + Referrer too long: + description: Occurs when the value of `referrer` in your query is too long. + value: + 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] + Invalid view duration: + description: Occurs when the value of `viewDuration` is incorrect. + value: + 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 '404': headers: X-RateLimit-Limit: @@ -13597,6 +13716,9 @@ paths: - `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. required: true style: simple explode: false @@ -13608,6 +13730,9 @@ paths: - start - end - impression + - ccv-peak + - ccv-average + - view - name: from in: query description: | @@ -13638,16 +13763,15 @@ paths: - name: interval in: query description: | - 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. + Use this query parameter to define the granularity of the data. Possible values: `minute`, `hour`, `day`. - If you do not set a value for `interval`, and the period you set using the `from` and `to` parameters is less than or equals to 2 days, then the default assigned value is `hour`. Otherwise the API sets it to `day`. + - When you set `minute` as interval, the timeframe you define with the `from` and `to` parameters must be less than 60 minutes. style: form explode: false schema: type: string - enum: [hour, day] + enum: [minute, hour, day] example: hour - name: sortBy in: query @@ -13684,6 +13808,41 @@ paths: - asc - desc example: asc + - name: unique + in: query + description: | + Use this query parameter to control how viewer data is counted: + + - `true` means that a single user watching multiple times counts as 1 unique viewer + - `false` means that all views count, even if from the same user. + + The API accepts this parameter only when you use the `ccv-peak`, `ccv-average`, or `view` metric. + + Viewers are unique for 1 day. + + The API determines uniqueness based on a viewer's `user-agent` and IP address. This means that the API can filter viewers using multiple tabs to watch the same video multiple times, but cannot filter for viewers who use multiple browsers to watch the same content multiple times. + style: form + explode: false + schema: + type: boolean + example: true + - name: viewDuration + in: query + description: | + 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`. + style: form + explode: false + schema: + type: string + enum: + - 3s + - 5s + - 10s + - 30s - $ref: '#/components/parameters/filterBy' - $ref: '#/components/parameters/current-page' - $ref: '#/components/parameters/page-size' @@ -13773,6 +13932,38 @@ paths: status: 400 detail: This field was not expected. name: from:2024-05-20T09:15:05+02:00 + Invalid interval: + description: Occurs when the value you set for `interval` is not `minute`, `hour`, or `day`. + value: + 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 + Timeframe does not match interval: + description: Occurs when you set `minute` as interval, and a timeframe that is longer than 60 minutes. + value: + 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 + Referrer too long: + description: Occurs when the value of `referrer` in your query is too long. + value: + 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] + Invalid view duration: + description: Occurs when the value of `viewDuration` is incorrect. + value: + 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 '404': headers: X-RateLimit-Limit: @@ -16443,7 +16634,7 @@ components: type: object properties: metric: - description: Returns the metric you selected. + description: Returns the metric and relevant parameters you selected. type: string enum: - play @@ -16452,6 +16643,17 @@ components: - 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 example: impression aggregation: description: Returns the aggregation you selected. @@ -16492,7 +16694,7 @@ components: type: object properties: metric: - description: Returns the metric you selected. + description: Returns the metric and relevant parameters you selected. type: string enum: - play @@ -16500,6 +16702,19 @@ components: - 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 example: impression breakdown: description: Returns the dimension you selected. @@ -16554,7 +16769,7 @@ components: type: object properties: metric: - description: Returns the metric you selected. + description: Returns the metric and relevant parameters you selected. type: string enum: - play @@ -16562,11 +16777,25 @@ components: - 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 example: impression interval: description: Returns the interval you selected. type: string enum: + - minute - hour - day example: day @@ -16585,7 +16814,7 @@ components: format: date-time example: '2024-05-29T11:15:07+00:00' data: - description: Returns an array of metrics and the timestamps . + description: Returns an array of metrics and the timestamps. type: array items: type: object @@ -16919,6 +17148,7 @@ components: - `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. in: query required: false example: filterBy[country]=FR&filterBy[operatingSystem]=windows&filterBy[browser][]=firefox&filterBy[browser][]=chrome&filterBy[tag]=Cool videos @@ -16974,6 +17204,18 @@ components: type: string description: 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). example: Cool videos + referrer: + type: array + items: + type: string + format: uri + maxLength: 2048 + description: |- + Filters data based on the URL where the view is originating from. This filter parameter accepts an empty string to filter view events where no referrer is available. + + - The API filters for exact matches. Include the trailing `/` characters if needed. + - The URLs you add must be URL encoded. + example: ['https%3A%2F%2Fmy-awesome-videos.com'] current-page: name: currentPage in: query