Merge pull request #351 from apivideo/Add-tag-filter-to-analytics-specs

Add tag filter to analytics specs
apivideo · Jul 31, 2024 · adf6dbe · adf6dbe
2 parents 1511f5f + dcac1e0
commit adf6dbe
Showing 1 changed file with 103 additions and 92 deletions.
diff --git a/openapi.yaml b/openapi.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:
@@ -11920,9 +11899,9 @@ paths:
           - `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. Possible response values are: `computer`, `phone`, `tablet`, `tv`, `console`, `wearable`, `unknown`.
-          - `operating-system`: 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`.
+          - `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`.
         style: simple
         explode: false
         required: true
@@ -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:
@@ -12379,6 +12300,25 @@ paths:
       x-client-paginated: true
       x-doctave:
         code-samples:
+              - language: node
+                code: |
+                  const metrics = await client.analytics.getMetricsOverTime({
+                    metric: 'play',
+                    filterBy: {
+                      browser: ['chrome', 'firefox'],
+                      continent: ['EU', 'AF'],
+                    },
+                  });
+              - language: csharp
+                code: |
+                  FilterBy2 filterBy = new FilterBy2
+                  {
+                      continent = new List<string> { "EU", "US" },
+                      devicetype = new List<string> { "phone" },
+                      tag = "test"
+                  };
+                  Page<AnalyticsMetricsBreakdownResponseData> page = apiClient.Analytics()
+                      .getMetricsBreakdown("play", "continent").From(new DateTime(2024, 7, 1)).FilterBy(filterBy).execute();
   /webhooks:
     get:
       tags:
@@ -14708,7 +14648,6 @@ components:
       required:
         - context
         - data
-        - pagination
     analytics-metrics-breakdown-response:
       title: Analytics response for metrics breakdown by dimension
       type: object
@@ -15126,6 +15065,78 @@ 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` 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).
+      in: query
+      required: false
+      example: filterBy[country]=FR&filterBy[operatingSystem]=windows&filterBy[browser][]=firefox&filterBy[browser][]=chrome&filterBy[tag]=Cool videos
+      style: deepObject
+      x-is-deep-object: true
+      explode: true
+      schema:
+        type: object
+        properties:
+          mediaId:
+            type: array
+            items:
+              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: array
+            items:
+              type: string
+              enum: [AS, AF, NA, SA, AN, EU, AZ]
+            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`.
+            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: array
+            items:
+              type: string
+            example: ['FR']
+          deviceType:
+            type: array
+            items:
+              type: string
+            description: 'Returns analytics based on the type of device used by the viewers. Response values can include: `computer`, `phone`, `tablet`, `tv`, `console`, `wearable`, `unknown`.'
+            example: ['computer']
+          operatingSystem:
+            type: array
+            items:
+              type: string
+            description: Returns analytics based on the operating system used by the viewers. Response values can include `windows`, `mac osx`, `android`, `ios`, `linux`.
+            example: ['windows']
+          browser:
+            description: Returns analytics based on the browser used by the viewers. Response values can include `chrome`, `firefox`, `edge`, `opera`.
+            type: array
+            items:
+              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