Add tag filter to analytics specs

apivideo · Jul 26, 2024 · fc01675 · fc01675
1 parent 239f10c
commit fc01675
Showing 1 changed file with 68 additions and 88 deletions.
diff --git a/oas_apivideo.yaml b/oas_apivideo.yaml
@@ -11733,28 +11733,7 @@ paths:
           type: string
           format: date-time
         example: 2024-02-06T00:00:00+01:00
-      - name: filterBy
-        in: query
-        description: |
-          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`.
-
-          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/). 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/).
-          - `deviceType`: Returns analytics based on the type of device used by the viewers. Possible response values are: `computer`, `phone`, `tablet`, `tv`, `console`, `wearable`, `unknown`.
-          - `operatingSystem`: Returns analytics based on the operating system used by the viewers. Response values include `windows`, `mac osx`, `android`, `ios`, `linux`.
-          - `browser`: Returns analytics based on the browser used by the viewers. Response values include `chrome`, `firefox`, `edge`, `opera`.
-        style: form
-        explode: true
-        schema:
-          type: string
-        example: filterBy[continent]=EU&filterBy[country]=FR&filterBy[browser]=Safari&filterBy[browser]=Firefox
+      - $ref: '#/components/parameters/filterBy'
       responses:
         '200':
           headers:
@@ -11963,27 +11942,7 @@ paths:
           type: string
           format: date-time
         example: 2024-02-06T00:00:00+01:00
-      - name: filterBy
-        in: query
-        description: |
-          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. You must use `camelCase` for query parameters.
-
-          - If you do not set a value for `filterBy`, the API returns the full dataset for your project.
-
-          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/). 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/).
-          - `deviceType`: Returns analytics based on the type of device used by the viewers. Possible response values are: `computer`, `phone`, `tablet`, `tv`, `console`, `wearable`, `unknown`.
-          - `operatingSystem`: Returns analytics based on the operating system used by the viewers. Response values include `windows`, `mac osx`, `android`, `ios`, `linux`.
-          - `browser`: Returns analytics based on the browser used by the viewers. Response values include `chrome`, `firefox`, `edge`, `opera`.
-        style: form
-        explode: true
-        schema:
-          type: string
-        example: filterBy[continent]=EU&filterBy[country]=FR&filterBy[browser]=Safari&filterBy[browser]=Firefox
+      - $ref: '#/components/parameters/filterBy'
       - $ref: '#/components/parameters/current-page'
       - $ref: '#/components/parameters/page-size'
       responses:
@@ -12167,7 +12126,7 @@ paths:
         schema:
           type: string
           format: date-time
-        example: from=2024-02-05T00:00:00+01:00
+        example: 2024-02-05T00:00:00+01:00
       - name: to
         in: query
         description: |
@@ -12180,7 +12139,7 @@ paths:
         schema:
           type: string
           format: date-time
-        example: to=2024-02-06T00:00:00+01:00
+        example: 2024-02-06T00:00:00+01:00
       - name: interval
         in: query
         description: |
@@ -12193,49 +12152,11 @@ paths:
         explode: false
         schema:
           type: string
-          format: date-time
-        example: to=2024-02-06T00:00:00+01:00
-      - name: filterBy
-        in: query
-        description: |
-          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. You must use `camelCase` for query parameters.
-
-          - If you do not set a value for `filterBy`, the API returns the full dataset for your project.
-
-          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/). 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/).
-          - `deviceType`: Returns analytics based on the type of device used by the viewers. Possible response values are: `computer`, `phone`, `tablet`, `tv`, `console`, `wearable`, `unknown`.
-          - `operatingSystem`: Returns analytics based on the operating system used by the viewers. Response values include `windows`, `mac osx`, `android`, `ios`, `linux`.
-          - `browser`: Returns analytics based on the browser used by the viewers. Response values include `chrome`, `firefox`, `edge`, `opera`.
-        style: form
-        explode: true
-        schema:
-          type: string
-        example: filterBy[continent]=EU&filterBy[country]=FR&filterBy[browser]=Safari&filterBy[browser]=Firefox
-      - name: currentPage
-        in: query
-        description: 'Choose the number of search results to return per page. Minimum value: 1'
-        required: false
-        style: form
-        explode: true
-        schema:
-          type: integer
-          default: 1
-        example: 2
-      - name: pageSize
-        in: query
-        description: 'Results per page. Allowed values 1-100, default is 25.'
-        required: false
-        style: form
-        explode: true
-        schema:
-          type: integer
-          default: 25
-        example: 30
+          enum: [hour, day]
+        example: hour
+      - $ref: '#/components/parameters/filterBy'
+      - $ref: '#/components/parameters/current-page'
+      - $ref: '#/components/parameters/page-size'
       responses:
         '200':
           headers:
@@ -15126,6 +15047,65 @@ components:
         metadata:
           $ref: '#/components/schemas/video-status-encoding-metadata'
   parameters:
+    filterBy:
+      name: filterBy
+      description: |
+          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`.
+
+          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. Possible response values are: `computer`, `phone`, `tablet`, `tv`, `console`, `wearable`, `unknown`.
+          - `operatingSystem`: Returns analytics based on the operating system used by the viewers. Response values include `windows`, `mac osx`, `android`, `ios`, `linux`.
+          - `browser`: Returns analytics based on the browser used by the viewers. Response values 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).
+      in: query
+      required: false
+      example: {"mediaType":"video","continent":"EU","country":"FR"}
+      style: deepObject
+      explode: true
+      schema:
+        type: object
+        properties:
+          mediaId:
+            type: string
+            description: Returns analytics based on the unique identifiers of a video or a live stream.
+            example: vi4blUQJFrYWbaG44NChkH27
+          mediaType:
+            type: string
+            enum: [video, live-stream]
+            example: video
+          continent:
+            type: string
+            description: 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`.
+            enum: [AS, AF, NA, SA, AN, EU, AZ]
+            example: EU
+          country:
+            description: 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`.
+            type: string
+            example: FR
+          deviceType:
+            type: string
+            description: 'Returns analytics based on the type of device used by the viewers. Possible response values are: `computer`, `phone`, `tablet`, `tv`, `console`, `wearable`, `unknown`.'
+            example: computer
+          operatingSystem:
+            type: string
+            description: Returns analytics based on the operating system used by the viewers. Response values include `windows`, `mac osx`, `android`, `ios`, `linux`.
+            example: windows
+          browser:
+            description: Returns analytics based on the browser used by the viewers. Response values include `chrome`, `firefox`, `edge`, `opera`.
+            type: string
+            example: firefox
+          tag:
+            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
     current-page:
       name: currentPage
       in: query