docs(specs): Review OpenAPI Analytics (search analytics) (#1689)

Co-authored-by: Kai Welke <kai.welke@algolia.com>

specs/analytics/common/parameters.yml

@@ -2,10 +2,11 @@
 Attribute:
   in: path
   name: attribute
-  description: The exact name of the attribute.
+  description: Attribute name.
   required: true
   schema:
     type: string
+    example: 'brand'
 
 # query
 OrderBy:
@@ -18,13 +19,18 @@ OrderBy:
 # private
 orderBy:
   type: string
+  description: >
+    Method for ordering results.
+
+    `clickThroughRate`, `conversionRate` and `averageClickPosition` are only available if the `clickAnalytics` parameter is `true`.
   enum: [searchCount, clickThroughRate, conversionRate, averageClickPosition]
   default: searchCount
 
 Direction:
   in: query
   name: direction
-  description: The sorting of the result.
+  description: >
+    Sorting direction of the results: ascending or descending.
   schema:
     $ref: '#/direction'
 
@@ -37,73 +43,100 @@ direction:
 ClickAnalytics:
   in: query
   name: clickAnalytics
-  description: Whether to include the click-through and conversion rates for a search.
+  description: Whether to include [click and conversion](https://www.algolia.com/doc/guides/sending-events/getting-started/) rates for a search.
   schema:
     type: boolean
     default: false
 
+count:
+  description: Number of tracked _and_ untracked searches (where the `clickAnalytics` parameter isn't `true`).
+  type: integer
+  example: 504
+
+noResultCount:
+  description: Number of occurences.
+  type: integer
+  example: 54
+
 Search:
   in: query
   name: search
-  description: The query term to search for. Must match the exact user input.
+  description: User query.
+  example: 'enable ab test'
   schema:
     type: string
 
 Tags:
   name: tags
   in: query
-  description: Filter metrics on the provided tags. Each tag must correspond to an analyticsTags set at search time. Multiple tags can be combined with the operators OR and AND. If a tag contains characters like spaces or parentheses, it should be URL encoded.
+  description: Filter analytics on the [`analyticsTags`](https://www.algolia.com/doc/api-reference/api-parameters/analyticsTags/) set at search time. Multiple tags can be combined with the operators OR and AND. If a tag contains characters like spaces or parentheses, it must be URL-encoded.
+  example: 'device:mobile%20phone'
   schema:
     type: string
 
 # misc
 average:
   type: number
   format: double
-  description: The average of all the click count event.
+  description: Average count of all click events.
 
 averageClickPosition:
   type: integer
-  description: The average position of all the click count event.
+  description: Average [position](https://www.algolia.com/doc/guides/search-analytics/concepts/metrics/#click-position) of clicked search result.
+  example: 1
 
 clickCount:
   type: integer
-  description: The number of click event.
+  description: Number of click events.
+  example: 162
 
 date:
   type: string
-  description: Date of the event.
+  description: Date of the event in the format YYYY-MM-DD.
+  example: '2023-06-14'
 
 rate:
   type: number
   format: double
-  description: The click-through rate.
+  description: >
+    [Click-through rate (CTR)](https://www.algolia.com/doc/guides/search-analytics/concepts/metrics/#click-through-rate).
+  minimum: 0
+  maximum: 1
+  example: 0.14634193523426317
 
 conversionRate:
   type: number
   format: double
-  description: The conversion rate.
+  description: >
+    [Conversion rate (CR)](https://www.algolia.com/doc/guides/search-analytics/concepts/metrics/#conversion-rate).
+  example: 0
 
 conversionCount:
   type: integer
-  description: The number of converted clicks.
+  description: Number of converted clicks.
+  example: 0
 
 attribute:
-  description: The attribute.
+  description: Attribute name.
   type: string
+  example: 'url'
 
 operator:
-  description: The operator.
+  description: Operator.
   type: string
+  example: ':'
 
 value:
-  description: The value of the attribute.
+  description: Attribute value.
   type: string
+  example: 'integration'
 
 search:
-  description: The search query.
+  description: User query.
+  example: 'separator'
   type: string
 
 hit:
-  description: The hit.
+  description: Hit.
   type: string
+  example: 'method-export-rules-php'

specs/analytics/common/schemas/getTopFilterAttributes.yml

@@ -6,7 +6,7 @@ getTopFilterAttributesResponse:
   properties:
     attributes:
       type: array
-      description: A list of attributes with their count.
+      description: Filterable attributes.
       items:
         $ref: '#/getTopFilterAttribute'
 

specs/analytics/common/schemas/getTopFilterForAttribute.yml

@@ -6,7 +6,7 @@ getTopFilterForAttributeResponse:
   properties:
     values:
       type: array
-      description: A list of filters for the given attributes.
+      description: Filter values for an attribute.
       items:
         $ref: '#/getTopFilterForAttribute'
 

specs/analytics/common/schemas/getTopFiltersNoResults.yml

@@ -6,7 +6,7 @@ getTopFiltersNoResultsResponse:
   properties:
     values:
       type: array
-      description: A list of filters without results.
+      description: Filters with no results.
       items:
         $ref: '#/getTopFiltersNoResultsValues'
 
@@ -21,7 +21,7 @@ getTopFiltersNoResultsValues:
       $ref: '../../../common/parameters.yml#/count'
     values:
       type: array
-      description: A list of filters without results.
+      description: Filters with no results.
       items:
         $ref: '#/getTopFiltersNoResultsValue'
 

specs/analytics/common/schemas/getTopHits.yml

@@ -6,7 +6,7 @@ topHitsResponse:
   properties:
     hits:
       type: array
-      description: A list of top hits with their count.
+      description: Top hits.
       items:
         type: object
         title: topHit
@@ -28,7 +28,7 @@ topHitsResponseWithAnalytics:
   properties:
     hits:
       type: array
-      description: A list of top hits with their count and analytics.
+      description: Top hits.
       items:
         type: object
         title: topHitWithAnalytics

specs/analytics/common/schemas/getTopSearches.yml

@@ -6,7 +6,7 @@ topSearchesResponse:
   properties:
     searches:
       type: array
-      description: A list of top searches with their count.
+      description: Top searches with their hits count.
       items:
         type: object
         title: topSearch
@@ -19,7 +19,7 @@ topSearchesResponse:
           search:
             $ref: '../parameters.yml#/search'
           count:
-            $ref: '../../../common/parameters.yml#/count'
+            $ref: '../parameters.yml#/count'
           nbHits:
             $ref: '../../../search/common/schemas/SearchResponse.yml#/nbHits'
 
@@ -31,7 +31,7 @@ topSearchesResponseWithAnalytics:
   properties:
     searches:
       type: array
-      description: A list of top searches with their count and analytics.
+      description: Top searches with their hits count and analytics.
       items:
         type: object
         title: topSearchWithAnalytics
@@ -50,7 +50,7 @@ topSearchesResponseWithAnalytics:
           search:
             $ref: '../parameters.yml#/search'
           count:
-            $ref: '../../../common/parameters.yml#/count'
+            $ref: '../parameters.yml#/count'
           clickThroughRate:
             $ref: '../parameters.yml#/rate'
           averageClickPosition:

specs/analytics/paths/search/getNoClickRate.yml

@@ -3,7 +3,7 @@ get:
     - search
   operationId: getNoClickRate
   summary: Get no click rate.
-  description: Returns the rate at which searches didn't lead to any clicks. The endpoint returns a value for the complete given time range, as well as a value per day. It also returns the count of searches and searches without clicks.
+  description: Returns the rate at which searches don't lead to any clicks. The endpoint returns a value for the complete given time range, as well as a value per day. It also returns the count of searches and searches without clicks.
   parameters:
     - $ref: '../../../common/parameters.yml#/Index'
     - $ref: '../../../common/parameters.yml#/StartDate'
@@ -32,7 +32,7 @@ get:
                 $ref: '../../common/parameters.yml#/clickCount'
               dates:
                 type: array
-                description: A list of searches without clicks with their date, rate and counts.
+                description: Overall count of searches without clicks plus a daily breakdown.
                 items:
                   type: object
                   title: noClickRateEvent
@@ -46,7 +46,7 @@ get:
                     rate:
                       $ref: '../../common/parameters.yml#/rate'
                     count:
-                      $ref: '../../common/parameters.yml#/clickCount'
+                      $ref: '../../common/parameters.yml#/count'
                     noClickCount:
                       $ref: '../../common/parameters.yml#/clickCount'
                     date:

specs/analytics/paths/search/getNoResultsRate.yml

@@ -3,7 +3,7 @@ get:
     - search
   operationId: getNoResultsRate
   summary: Get no results rate.
-  description: Returns the rate at which searches didn't return any results. The endpoint returns a value for the complete given time range, as well as a value per day. It also returns the count of searches and searches without results used to compute the rates.
+  description: Returns the rate at which searches didn't return any results. 
   parameters:
     - $ref: '../../../common/parameters.yml#/Index'
     - $ref: '../../../common/parameters.yml#/StartDate'
@@ -32,7 +32,7 @@ get:
                 $ref: '../../../common/parameters.yml#/count'
               dates:
                 type: array
-                description: A list of searches without results with their date, rate and counts.
+                description: Overall count of searches without results plus a daily breakdown.
                 items:
                   type: object
                   title: noResultsRateEvent
@@ -46,9 +46,9 @@ get:
                     date:
                       $ref: '../../common/parameters.yml#/date'
                     noResultCount:
-                      $ref: '../../../common/parameters.yml#/count'
+                      $ref: '../../common/parameters.yml#/noResultCount'
                     count:
-                      $ref: '../../../common/parameters.yml#/count'
+                      $ref: '../../common/parameters.yml#/count'
                     rate:
                       $ref: '../../common/parameters.yml#/rate'
     '400':

specs/analytics/paths/search/getSearchesCount.yml

@@ -2,8 +2,8 @@ get:
   tags:
     - search
   operationId: getSearchesCount
-  summary: Get searches count.
-  description: Returns the number of searches across the given time range. The endpoint returns a value for the complete given time range, as well as a value per day.
+  summary: Get number of searches.
+  description: Returns the number of searches within a time range.
   parameters:
     - $ref: '../../../common/parameters.yml#/Index'
     - $ref: '../../../common/parameters.yml#/StartDate'
@@ -26,7 +26,7 @@ get:
                 $ref: '../../../common/parameters.yml#/count'
               dates:
                 type: array
-                description: A list of search events with their date and count.
+                description: Search events with their associated dates and hit counts.
                 items:
                   type: object
                   title: searchEvent

specs/analytics/paths/search/getSearchesNoClicks.yml

@@ -3,7 +3,7 @@ get:
     - search
   operationId: getSearchesNoClicks
   summary: Get top searches with no clicks.
-  description: Returns top searches that didn't lead to any clicks. Limited to the 1000 most frequent ones. For each search, also returns the average number of found hits.
+  description: Return the most popular of the last 1,000 searches that didn't lead to any clicks.
   parameters:
     - $ref: '../../../common/parameters.yml#/Index'
     - $ref: '../../../common/parameters.yml#/StartDate'
@@ -25,7 +25,7 @@ get:
             properties:
               searches:
                 type: array
-                description: A list of searches with no clicks and their count.
+                description: Searches with no clicks.
                 items:
                   type: object
                   title: searchNoClickEvent

specs/analytics/paths/search/getSearchesNoResults.yml

@@ -3,7 +3,7 @@ get:
     - search
   operationId: getSearchesNoResults
   summary: Get top searches with no results.
-  description: Returns top searches that didn't return any results. Limited to the 1000 most frequent ones.
+  description: Returns the most popular of the latest 1,000 searches that didn't return any results.
   parameters:
     - $ref: '../../../common/parameters.yml#/Index'
     - $ref: '../../../common/parameters.yml#/StartDate'
@@ -25,7 +25,7 @@ get:
             properties:
               searches:
                 type: array
-                description: A list of searches with no results and their count.
+                description: Searches with no results.
                 items:
                   type: object
                   title: searchNoResultEvent

specs/analytics/paths/search/getTopCountries.yml

@@ -3,7 +3,7 @@ get:
     - search
   operationId: getTopCountries
   summary: Get top countries.
-  description: Returns top countries. Limited to the 1000 most frequent ones.
+  description: Returns top countries. Limited to the 1,000 most frequent ones.
   parameters:
     - $ref: '../../../common/parameters.yml#/Index'
     - $ref: '../../../common/parameters.yml#/StartDate'
@@ -25,7 +25,7 @@ get:
             properties:
               countries:
                 type: array
-                description: A list of countries with their count.
+                description: Countries
                 items:
                   type: object
                   title: topCountry
@@ -35,8 +35,9 @@ get:
                     - count
                   properties:
                     country:
-                      description: The country.
+                      description: Country.
                       type: string
+                      example: 'UK'
                     count:
                       $ref: '../../../common/parameters.yml#/count'
     '400':

specs/analytics/paths/search/getTopFilterAttributes.yml

@@ -2,8 +2,8 @@ get:
   tags:
     - search
   operationId: getTopFilterAttributes
-  summary: Get top filter attributes.
-  description: Returns top filter attributes. Limited to the 1000 most used filters.
+  summary: Get top filterable attributes.
+  description: Return the most popular [filterable attributes](https://www.algolia.com/doc/guides/managing-results/refine-results/filtering/) in the 1,000 most recently used filters.
   parameters:
     - $ref: '../../../common/parameters.yml#/Index'
     - $ref: '../../common/parameters.yml#/Search'