openapi: 3.0.2
externalDocs:
  url: https://www.algolia.com/doc/guides/search-analytics/overview
  description: Search analytics.
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

    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.

    A semantic patterns framework is also available under `/3/patterns/*` for building custom
    analytics queries.

    ## 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
components:
  securitySchemes:
    appId:
      $ref: '../common/securitySchemes.yml#/appId'
    apiKey:
      $ref: '../common/securitySchemes.yml#/apiKey'
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: pattern
    x-displayName: Patterns
    description: |
      The semantic patterns query framework (`/3/patterns/*`).
      Build custom analytics queries from metrics, groupBy, filters, and parameters.
  - 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.
x-tagGroups:
  - name: Metrics
    tags:
      - search
      - click
      - revenue
      - filter
      - pattern
      - user
  - name: Other
    tags:
      - status
paths:
  # ######################
  # ### Custom request ###
  # ######################
  /{path}:
    $ref: '../common/paths/customRequest.yml'

  # ##################################
  # ### Search Analytics Endpoints ###
  # ##################################
  /2/searches:
    $ref: 'paths/search/getTopSearches.yml'
  /2/searches/count:
    $ref: 'paths/search/getSearchesCount.yml'
  /2/searches/noResults:
    $ref: 'paths/search/getSearchesNoResults.yml'
  /2/searches/noClicks:
    $ref: 'paths/search/getSearchesNoClicks.yml'
  /2/searches/noResultRate:
    $ref: 'paths/search/getNoResultsRate.yml'
  /2/searches/noClickRate:
    $ref: 'paths/search/getNoClickRate.yml'
  /2/hits:
    $ref: 'paths/search/getTopHits.yml'
  /2/users/count:
    $ref: 'paths/search/getUsersCount.yml'
  /2/filters:
    $ref: 'paths/search/getTopFilterAttributes.yml'
  /2/filters/{attribute}:
    $ref: 'paths/search/getTopFilterForAttribute.yml'
  /2/filters/noResults:
    $ref: 'paths/search/getTopFiltersNoResults.yml'
  /2/countries:
    $ref: 'paths/search/getTopCountries.yml'

  # #################################
  # ### Click Analytics Endpoints ###
  # #################################
  /2/clicks/averageClickPosition:
    $ref: 'paths/click/getAverageClickPosition.yml'
  /2/clicks/positions:
    $ref: 'paths/click/getClickPositions.yml'
  /2/clicks/clickThroughRate:
    $ref: 'paths/click/getClickThroughRate.yml'
  /2/conversions/conversionRate:
    $ref: 'paths/click/getConversionRate.yml'
  /2/conversions/addToCartRate:
    $ref: 'paths/click/getAddToCartRate.yml'
  /2/conversions/purchaseRate:
    $ref: 'paths/click/getPurchaseRate.yml'
  /2/conversions/revenue:
    $ref: 'paths/revenue/getRevenue.yml'

  # ########################
  # ### Status Endpoints ###
  # ########################
  /2/status:
    $ref: 'paths/status/getStatus.yml'

  # ######################
  # ### Patterns — /3/ ###
  # ######################
  /3/patterns/fields:
    $ref: 'paths/patterns/getPatternsFields.yml'
  /3/patterns/timeseries:
    $ref: 'paths/patterns/queryPatternsTimeseries.yml'
  /3/patterns/scalar:
    $ref: 'paths/patterns/queryPatternsScalar.yml'
  /3/patterns/table:
    $ref: 'paths/patterns/queryPatternsTable.yml'
  /3/patterns/distribution:
    $ref: 'paths/patterns/queryPatternsDistribution.yml'

  # ###############
  # ### Helpers ###
  # ###############
  /setClientApiKey:
    $ref: '../common/helpers/setClientApiKey.yml#/method'