> ## Documentation Index > Fetch the complete documentation index at: https://algolia.com/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve top searches > Returns the most popular searches. For each search, it also includes the average number of hits. If you set the `clickAnalytics` query parameter to `true`, the response also includes: * Tracked searches count Tracked searches are Search API requests with `clickAnalytics` set to `true`. This differs from the response's `count`, which includes searches where `clickAnalytics` is `false`. * Click count * Click-through rate (CTR) * Conversion count * Conversion rate (CR) * Average click position 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 **There's a difference between 0% rates and null rates:** * **Null** means there were no queries. Algolia didn't receive any events, so rates 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. **Required ACL:** `analytics` ## OpenAPI ````yaml specs/searchstats.yml get /2/searches openapi: 3.1.0 info: title: Analytics API summary: >- The Analytics API gives you access to metrics related to your Algolia search experience description: > ## Base URLs Base URLs for the Analytics API: - `https://analytics.us.algolia.com` - `https://analytics.de.algolia.com` - `https://analytics.algolia.com` (alias of `analytics.us.algolia.com`) Use the URL that matches your [analytics region](https://dashboard.algolia.com/account/infrastructure/analytics). **All requests must use HTTPS.** ## Availability and authentication Access to the Analytics API is available as part of the [Premium or Elevate plans](https://www.algolia.com/pricing). Add these headers to authenticate requests: - `x-algolia-application-id`. Your Algolia application ID. - `x-algolia-api-key`. An API key with the necessary permissions to make the request. The required access control list (ACL) to make a request is listed in each endpoint's reference. You can find your application ID and API key in the [Algolia dashboard](https://dashboard.algolia.com/account/api-keys). ## Rate limits You can make up to **100 requests per minute per app** to the Analytics API. The response includes headers with information about the limits. ## Parameters Query parameters must be [URL-encoded](https://developer.mozilla.org/en-US/docs/Glossary/Percent-encoding). Non-ASCII characters must be UTF-8 encoded. Plus characters (`+`) are interpreted as spaces. ## Response status and errors The Analytics API returns JSON responses. Since JSON doesn't guarantee any specific ordering, don't rely on the order of attributes in the API response. - Successful responses return a `2xx` status - Client errors return a `4xx` status - Server errors are indicated by a `5xx` status. Error responses have a `message` property with more information. ## Version The current version of the Analytics API is version 2, indicated by the `/2/` in each endpoint's URL. ## Query aggregation Algolia accepts queries on each keystroke. To ensure you have relevant analytics data, however, the series of keystrokes is aggregated to keep only the latest (final) user query. This is called "prefix" aggregation. For more information, see [Query agggregation and processing](https://www.algolia.com/doc/guides/search-analytics/concepts/query-aggregation). See the analytics implementation overview for more information about query aggregation. version: 2.0.0 servers: - url: https://analytics.{region}.algolia.com variables: region: description: The region where your Algolia application is hosted. enum: - us - de default: us - url: https://analytics.algolia.com security: - appId: [] apiKey: [] tags: - name: click x-displayName: Clicks description: | Metrics related to click and conversion events, such as click and conversion rates for your search results. - name: filter x-displayName: Filters description: | Metrics related to filters. - name: revenue x-displayName: Revenue description: | Metrics related to revenue. - name: search x-displayName: Searches description: | Metrics related to searches and search results, such as the no-results rate or the most frequent search queries. - name: status x-displayName: Status description: Check the status of the Analytics API. - name: user x-displayName: Users description: Metrics related to the users of your search. externalDocs: url: https://www.algolia.com/doc/guides/search-analytics/overview description: Search analytics. paths: /2/searches: get: tags: - search summary: Retrieve top searches description: > Returns the most popular searches. For each search, it also includes the average number of hits. If you set the `clickAnalytics` query parameter to `true`, the response also includes: - Tracked searches count Tracked searches are Search API requests with `clickAnalytics` set to `true`. This differs from the response's `count`, which includes searches where `clickAnalytics` is `false`. - Click count - Click-through rate (CTR) - Conversion count - Conversion rate (CR) - Average click position 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 **There's a difference between 0% rates and null rates:** - **Null** means there were no queries. Algolia didn't receive any events, so rates 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. operationId: getTopSearches parameters: - $ref: '#/components/parameters/Index' - $ref: '#/components/parameters/ClickAnalytics' - $ref: '#/components/parameters/Direction' - $ref: '#/components/parameters/EndDate' - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Offset' - $ref: '#/components/parameters/OrderBy' - $ref: '#/components/parameters/RevenueAnalytics' - $ref: '#/components/parameters/StartDate' - $ref: '#/components/parameters/Tags' responses: '200': description: OK headers: x-ratelimit-limit: $ref: '#/components/headers/x-ratelimit-limit' x-ratelimit-remaining: $ref: '#/components/headers/x-ratelimit-remaining' x-ratelimit-reset: $ref: '#/components/headers/x-ratelimit-reset' content: application/json: schema: $ref: '#/components/schemas/getTopSearchesResponse' '400': $ref: '#/components/responses/BadRequest' '402': $ref: '#/components/responses/FeatureNotEnabled' '403': $ref: '#/components/responses/MethodNotAllowed' '404': $ref: '#/components/responses/IndexNotFound' x-codeSamples: - lang: csharp label: C# source: |- // Initialize the client var client = new AnalyticsClient( new AnalyticsConfig("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY", "ALGOLIA_APPLICATION_REGION") ); // Call the API var response = await client.GetTopSearchesAsync("index"); // print the response Console.WriteLine(response); - lang: go label: Go source: >- // Initialize the client with your application region, eg. analytics.ALGOLIA_APPLICATION_REGION client, err := analytics.NewClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY", analytics.US) if err != nil { // The client can fail to initialize if you pass an invalid parameter. panic(err) } // Call the API response, err := client.GetTopSearches(client.NewApiGetTopSearchesRequest( "index")) if err != nil { // handle the eventual error panic(err) } // print the response print(response) - lang: java label: Java source: >- // Initialize the client AnalyticsClient client = new AnalyticsClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY", "ALGOLIA_APPLICATION_REGION"); // Call the API GetTopSearchesResponse response = client.getTopSearches("index"); // print the response System.out.println(response); - lang: javascript label: JavaScript source: >- // Initialize the client // Replace 'us' with your Algolia Application Region const client = algoliasearch('ALGOLIA_APPLICATION_ID', 'ALGOLIA_API_KEY').initAnalytics({ region: 'us' }); // Call the API const response = await client.getTopSearches({ index: 'index' }); // print the response console.log(response); - lang: kotlin label: Kotlin source: |- // Initialize the client val client = AnalyticsClient( appId = "ALGOLIA_APPLICATION_ID", apiKey = "ALGOLIA_API_KEY", region = "ALGOLIA_APPLICATION_REGION", ) // Call the API var response = client.getTopSearches(index = "index") // print the response println(response) - lang: php label: PHP source: >- // Initialize the client $client = AnalyticsClient::create('ALGOLIA_APPLICATION_ID', 'ALGOLIA_API_KEY', 'ALGOLIA_APPLICATION_REGION'); // Call the API $response = $client->getTopSearches( 'index', ); // print the response var_dump($response); - lang: python label: Python source: >- # Initialize the client # In an asynchronous context, you can use AnalyticsClient instead, which exposes the exact same methods. client = AnalyticsClientSync( "ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY", "ALGOLIA_APPLICATION_REGION" ) # Call the API response = client.get_top_searches( index="index", ) # print the response print(response) - lang: ruby label: Ruby source: >- # Initialize the client client = Algolia::AnalyticsClient.create("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY", "ALGOLIA_APPLICATION_REGION") # Call the API response = client.get_top_searches("index") # print the response puts(response) - lang: scala label: Scala source: |- // Initialize the client val client = AnalyticsClient( appId = "ALGOLIA_APPLICATION_ID", apiKey = "ALGOLIA_API_KEY", region = Option("ALGOLIA_APPLICATION_REGION") ) // Call the API val response = Await.result( client.getTopSearches( index = "index" ), Duration(100, "sec") ) // print the response println(response) - lang: swift label: Swift source: >- // Initialize the client let client = try AnalyticsClient(appID: "ALGOLIA_APPLICATION_ID", apiKey: "ALGOLIA_API_KEY", region: .us) // Call the API let response = try await client.getTopSearches(index: "index") // print the response print(response) - lang: cURL label: curl source: |- curl --request GET \ --url 'https://analytics.us.algolia.com/2/searches?index=ALGOLIA_INDEX_NAME&clickAnalytics=false&revenueAnalytics=false&startDate=2022-09-19&endDate=2023-01-21&orderBy=searchCount&direction=asc&limit=10&offset=0&tags=device%3Amobile%2520phone' \ --header 'accept: application/json' \ --header 'x-algolia-api-key: ALGOLIA_API_KEY' \ --header 'x-algolia-application-id: ALGOLIA_APPLICATION_ID' components: parameters: Index: in: query name: index description: Index name. required: true schema: type: string example: ALGOLIA_INDEX_NAME ClickAnalytics: in: query name: clickAnalytics description: >- Whether to include metrics related to click and conversion events in the response. schema: type: boolean default: false Direction: in: query name: direction description: | Sorting direction of the results: ascending or descending. schema: $ref: '#/components/schemas/direction' EndDate: in: query name: endDate description: End date of the period to analyze, in `YYYY-MM-DD` format. schema: type: string example: '2023-01-21' Limit: in: query name: limit description: | Number of items to return. required: false schema: type: integer default: 10 maximum: 1000 Offset: in: query name: offset description: | Position of the first item to return. required: false schema: type: integer default: 0 minimum: 0 OrderBy: in: query name: orderBy description: > Attribute by which to order the response items. If the `clickAnalytics` parameter is false, only `searchCount` is available. schema: $ref: '#/components/schemas/orderBy' RevenueAnalytics: in: query name: revenueAnalytics description: Whether to include metrics related to revenue events in the response. schema: type: boolean default: false StartDate: in: query name: startDate description: Start date of the period to analyze, in `YYYY-MM-DD` format. schema: type: string example: '2022-09-19' Tags: name: tags in: query description: > Tags by which to segment the analytics. You can combine multiple tags with `OR` and `AND`. Tags must be URL-encoded. For more information, see [Segment your analytics data](https://www.algolia.com/doc/guides/search-analytics/guides/segments). example: device:mobile%20phone schema: type: string headers: x-ratelimit-limit: description: Number of allowed requests per one minute. example: 100 schema: type: integer x-ratelimit-remaining: description: Number of remaining requests in the current period. example: 99 schema: type: integer x-ratelimit-reset: description: >- Timestamp when the rate limit will reset, measured in seconds since the Unix epoch. example: 1710682486 schema: type: integer schemas: getTopSearchesResponse: oneOf: - $ref: '#/components/schemas/topSearchesResponse' - $ref: '#/components/schemas/topSearchesResponseWithAnalytics' - $ref: '#/components/schemas/topSearchesResponseWithRevenueAnalytics' direction: type: string enum: - asc - desc default: asc orderBy: type: string description: > Attribute by which to order the response items. If the `clickAnalytics` parameter is false, only `searchCount` is available. enum: - searchCount - clickThroughRate - conversionRate - averageClickPosition default: searchCount topSearchesResponse: type: object title: Top searches additionalProperties: false required: - searches properties: searches: type: array description: Most popular searches and their number of search results (hits). items: title: topSearch type: object additionalProperties: false required: - search - count - nbHits properties: count: $ref: '#/components/schemas/count' nbHits: $ref: '#/components/schemas/nbHits' search: $ref: '#/components/schemas/search' topSearchesResponseWithAnalytics: type: object title: Top searches with click analytics additionalProperties: false required: - searches properties: searches: type: array description: >- Most popular searches and their associated click and conversion metrics. items: title: topSearchWithAnalytics type: object additionalProperties: false required: - search - count - nbHits - clickThroughRate - averageClickPosition - clickPositions - conversionRate - trackedSearchCount - clickCount - conversionCount properties: averageClickPosition: $ref: '#/components/schemas/averageClickPosition' clickCount: $ref: '#/components/schemas/clickCount' clickPositions: $ref: '#/components/schemas/clickPositions' clickThroughRate: $ref: '#/components/schemas/clickThroughRate' conversionCount: $ref: '#/components/schemas/conversionCount' conversionRate: $ref: '#/components/schemas/conversionRate' count: $ref: '#/components/schemas/count' nbHits: $ref: '#/components/schemas/nbHits' search: $ref: '#/components/schemas/search' trackedSearchCount: $ref: '#/components/schemas/trackedSearchCount' topSearchesResponseWithRevenueAnalytics: type: object title: Top searches with revenue analytics additionalProperties: false required: - searches properties: searches: type: array description: Most popular searches, including their click and revenue metrics. items: title: topSearchWithRevenueAnalytics type: object additionalProperties: false required: - search - count - nbHits - clickThroughRate - averageClickPosition - clickPositions - conversionRate - trackedSearchCount - clickCount - conversionCount - currencies - addToCartRate - addToCartCount - purchaseRate - purchaseCount properties: addToCartCount: $ref: '#/components/schemas/addToCartCount' addToCartRate: $ref: '#/components/schemas/addToCartRate' averageClickPosition: $ref: '#/components/schemas/averageClickPosition' clickCount: $ref: '#/components/schemas/clickCount' clickPositions: $ref: '#/components/schemas/clickPositions' clickThroughRate: $ref: '#/components/schemas/clickThroughRate' conversionCount: $ref: '#/components/schemas/conversionCount' conversionRate: $ref: '#/components/schemas/conversionRate' count: $ref: '#/components/schemas/count' currencies: $ref: '#/components/schemas/currencies' nbHits: $ref: '#/components/schemas/nbHits' purchaseCount: $ref: '#/components/schemas/purchaseCount' purchaseRate: $ref: '#/components/schemas/purchaseRate' search: $ref: '#/components/schemas/search' trackedSearchCount: $ref: '#/components/schemas/trackedSearchCount' ErrorBase: description: Error. type: object x-keep-model: true additionalProperties: true properties: message: type: string example: Invalid Application-Id or API-Key count: description: Number of searches. type: integer example: 504 nbHits: type: integer description: Number of results (hits). example: 20 search: description: Search query. example: separator type: string averageClickPosition: oneOf: - type: number format: double description: > Average position of a clicked search result in the list of search results. If null, Algolia didn't receive any search requests with `clickAnalytics` set to true. minimum: 1 example: 2.035 default: null - type: 'null' clickCount: type: integer description: Number of clicks associated with this search. example: 162 minimum: 0 default: 0 clickPositions: type: array description: >- List of positions in the search results and clicks associated with this search. minItems: 12 maxItems: 12 items: title: clickPosition type: object description: Click position. properties: clickCount: type: integer description: Number of times this search has been clicked at that position. example: 24 minimum: 0 default: 0 position: type: array description: > Range of positions in the search results, using the pattern `[start,end]`. For positions 11 and up, click events are summed over the specified range. `-1` indicates the end of the list of search results. minItems: 2 maxItems: 2 example: - 21 - -1 items: type: integer clickThroughRate: oneOf: - type: number format: double description: > Click-through rate: calculated as the number of tracked searches with at least one click event divided by the number of tracked searches. If null, Algolia didn't receive any search requests with `clickAnalytics` set to true. minimum: 0 maximum: 1 default: null example: 0.49 - type: 'null' conversionCount: type: integer description: Number of conversions from this search. example: 10 minimum: 0 default: 0 conversionRate: oneOf: - type: number format: double description: > Conversion rate: calculated as the number of tracked searches with at least one conversion event divided by the number of tracked searches. If null, Algolia didn't receive any search requests with `clickAnalytics` set to true. minimum: 0 maximum: 1 default: null example: 0.05 - type: 'null' trackedSearchCount: type: integer example: 2 default: 0 description: >- Number of tracked searches. Tracked searches are search requests where the `clickAnalytics` parameter is true. addToCartCount: type: integer description: Number of add-to-cart events from this search. minimum: 0 default: 0 example: 10 addToCartRate: oneOf: - type: number format: double description: > Add-to-cart rate: calculated as the number of tracked searches with at least one add-to-cart event divided by the number of tracked searches. If null, Algolia didn't receive any search requests with `clickAnalytics` set to true. minimum: 0 maximum: 1 default: null example: 0.1 - type: 'null' currencies: type: object description: | Revenue associated with this search: broken down by currency. default: {} additionalProperties: title: currencyCode x-additionalPropertiesName: currency type: object description: Currency code. properties: currency: type: string description: Currency code. example: USD revenue: type: number format: float description: Revenue associated with this search in this currency. example: 999.98 purchaseCount: type: integer description: Number of purchase events from this search. default: 0 example: 10 purchaseRate: oneOf: - type: number format: double description: > Purchase rate: calculated as the number of tracked searches with at least one purchase event divided by the number of tracked searches. If null, Algolia didn't receive any search requests with `clickAnalytics` set to true. minimum: 0 maximum: 1 default: null example: 0.05 - type: 'null' responses: BadRequest: description: Bad request or request arguments. content: application/json: schema: $ref: '#/components/schemas/ErrorBase' FeatureNotEnabled: description: This feature is not enabled on your Algolia account. content: application/json: schema: $ref: '#/components/schemas/ErrorBase' MethodNotAllowed: description: Method not allowed with this API key. content: application/json: schema: $ref: '#/components/schemas/ErrorBase' IndexNotFound: description: Index not found. content: application/json: schema: $ref: '#/components/schemas/ErrorBase' securitySchemes: appId: type: apiKey in: header name: x-algolia-application-id description: Your Algolia application ID. apiKey: type: apiKey in: header name: x-algolia-api-key description: > Your Algolia API key with the necessary permissions to make the request. Permissions are controlled through access control lists (ACL) and access restrictions. The required ACL to make a request is listed in each endpoint's reference. ````