Apply review suggestions

Author: Gary Conroy

specs/analytics/paths/click/getAddToCartRate.yml

@@ -11,7 +11,7 @@ get:
     By default, the analyzed period includes the last eight days including the current day.
 
     The rate is the number of add-to-cart conversion events divided by the number of tracked searches.
-    A search is tracked if it returns a queryID and `clickAnalytics` is `true`.
+    A search is tracked if it returns a queryID (`clickAnalytics` is `true`).
     This differs from the response's `count`, which shows the overall number of searches, including those where `clickAnalytics` is `false`.
 
     **There's a difference between a 0 and null add-to-cart rate when `clickAnalytics` is enabled:**

specs/analytics/paths/click/getAverageClickPosition.yml

@@ -23,7 +23,7 @@ get:
     '200':
       description: OK
       headers:
-        x-ratelimit-limit:a
+        x-ratelimit-limit:
           $ref: '../../../common/responses/rateLimit.yml#/x-ratelimit-limit'
         x-ratelimit-remaining:
           $ref: '../../../common/responses/rateLimit.yml#/x-ratelimit-remaining'

specs/analytics/paths/click/getClickPositions.yml

@@ -11,7 +11,6 @@ get:
     This lets you check how many clicks the first, second, or tenth search results receive.
 
     An average of `0` when `clickAnalytics` is enabled means Algolia didn't receive any [click events](https://www.algolia.com/doc/guides/sending-events/getting-started/) for the queries.
-    The average is `0` until Algolia receives at least one click event.
   parameters:
     - $ref: '../../../common/parameters.yml#/Index'
     - $ref: '../../../common/parameters.yml#/StartDate'

specs/analytics/paths/click/getClickThroughRate.yml

@@ -6,7 +6,7 @@ get:
     - analytics
   summary: Retrieve click-through rate
   description: |
-    Retrieves the click-through rate (CTR) for all your searches with at least one click event, including a daily breakdown
+    Retrieves the click-through rate (CTR) for all your searches with at least one click event, including a daily breakdown.
 
     By default, the analyzed period includes the last eight days including the current day.
 

specs/analytics/paths/click/getPurchaseRate.yml

@@ -11,7 +11,7 @@ get:
     By default, the analyzed period includes the last eight days including the current day.
 
     The rate is the number of purchase conversion events divided by the number of tracked searches.
-    A search is tracked if it returns a queryID and `clickAnalytics` is `true`.
+    A search is tracked if it returns a query ID (`clickAnalytics` is `true`).
     This differs from the response's `count`, which shows the overall number of searches, including those where `clickAnalytics` is `false`.
 
     **There's a difference between a 0 and null purchase rate when `clickAnalytics` is enabled:**

specs/analytics/paths/revenue/getRevenue.yml

@@ -8,11 +8,11 @@ get:
   description: |
     Retrieves revenue-related metrics, such as the total revenue or the average order value.
 
-    To retrieve revenue-related metrics, sent purchase events.
+    To retrieve revenue-related metrics, send purchase events.
     By default, the analyzed period includes the last eight days including the current day.
 
-    Revenue is based on purchase conversion events (an `eventSubtype` of `purchase`).
-    The revenue is `price` multiplied by `quantity` for each object in the event's `objectData` array.
+    Revenue is based on purchase conversion events (a conversion event with an `eventSubtype` attribute of `purchase`).
+    The revenue is the `price` attribute multiplied by the `quantity` attribute for each object in the event's `objectData` array.
   parameters:
     - $ref: '../../../common/parameters.yml#/Index'
     - $ref: '../../../common/parameters.yml#/StartDate'

specs/analytics/paths/search/getNoClickRate.yml

@@ -7,7 +7,7 @@ get:
   summary: Retrieve no click rate
   description: |
     Retrieves the fraction of searches that didn't lead to any click within a time range, including a daily breakdown.
-    It also returns the count of tracked searches and tracked searches without clicks.
+    It also returns the number of tracked searches and tracked searches without clicks.
 
     By default, the analyzed period includes the last eight days including the current day.
   parameters:

specs/analytics/paths/search/getSearchesNoResults.yml

@@ -4,7 +4,7 @@ get:
   operationId: getSearchesNoResults
   x-acl:
     - analytics
-  summary: Retrieve the 1,000 most frequent searches that produced zero results.
+  summary: Retrieves the most popular searches that didn't return any results.
   description: 
 
   parameters:

specs/analytics/paths/search/getTopHits.yml

@@ -8,24 +8,24 @@ get:
   description: |
     Retrieves the object IDs of the 1,000 most frequent search results.
 
-    If you enable `clickAnalytics` (set it to `true`), you'll also see:
+    If you set the `clickAnalytics` query parameter to true, the response also includes:
 
-    - Tracked searches count. A search is tracked if it returns a queryID and `clickAnalytics` is `true`. This differs from the response's `count`, which shows the overall number of searches, including those where `clickAnalytics` is `false`.
+    - Tracked searches count. Tracked searches are Search API requests with the `clickAnalytics` parameter set to `true`. This differs from the response's `count`, which shows the overall number of searches, including those where `clickAnalytics` is `false`.
     - Click count
     - Click-through rate (CTR)
     - Conversion count
     - Conversion rate (CR)
-    - Average click position.
+    - Average click position
 
-    If you enable `revenueAnalytics` (set it to `true`), you'll also see:
+    If you set the `revenueAnalytics` parameter to `true`, the response also includes:
 
     - Add-to-cart count
     - Add-to-cart rate (ATCR)
     - Purchase count
     - Purchase rate
-    - Revenue details for each currency.
+    - Revenue details for each currency
 
-    **There's a difference between 0% rates and null rates when `clickAnalytics` is enabled:**
+    **There's a difference between 0% rates and null rates:**
 
     - **Null** means there were no queries: since Algolia didn't receive any events, the rates (CTR, CR, ATCR, purchase rate) are null.
     - **0% rates** mean there _were_ queries but no [click or conversion events](https://www.algolia.com/doc/guides/sending-events/getting-started/) were received.

specs/analytics/paths/search/getTopSearches.yml

@@ -8,24 +8,24 @@ get:
   description: |
     Returns the most popular searches. For each search, it also includes the average number of hits.
 
-    If you enable `clickAnalytics` (set it to `true`), you'll also see:
+    If you set the `clickAnalytics` query parameter to `true`, the response also includes
 
-    - Tracked searches count. A search is tracked if it returns a queryID and `clickAnalytics` is `true`. This differs from the response's `count`, which shows the overall number of searches, including those where `clickAnalytics` is `false`.
+    - Tracked searches count. Tracked searches are Search API requests with the `clickAnalytics` parameter set to `true`. This differs from the response's `count`, which shows the overall number of searches, including those where `clickAnalytics` is `false`.
     - Click count
     - Click-through rate (CTR)
     - Conversion count
     - Conversion rate (CR)
-    - Average click position.
+    - Average click position
 
-    If you enable `revenueAnalytics` (set it to `true`), you'll also see:
+    If you set the `revenueAnalytics` query parameter to `true`, the response also includes:
 
     - Add-to-cart count
     - Add-to-cart rate (ATCR)
     - Purchase count
     - Purchase rate
-    - Revenue details for each currency.
+    - Revenue details for each currency
 
-    **There's a difference between 0% rates and null rates when `clickAnalytics` is enabled:**
+    **There's a difference between 0% rates and null rates:**
 
     - **Null** means there were no queries: since Algolia didn't receive any events, the rates (CTR, CR, ATCR, purchase rate) are null.
     - **0% rates** mean there _were_ queries but no [click or conversion events](https://www.algolia.com/doc/guides/sending-events/getting-started/) were received.