components:
  parameters:
    account_code:
      description: The account code to filter by.
      in: query
      name: account_code
      schema:
        type: string
    aggregate:
      description: Flag to indicate when to aggregate all Search Engines stats data.
      in: query
      name: aggregate
      required: false
      schema:
        default: true
        type: boolean
    device:
      description: Filter by kind of device.
      in: query
      name: device
      schema:
        enum:
          - desktop
          - mobile
        type: string
    dfid:
      description: >-
        Filter by a doofinder item id. You can get this value from the
        playground.
      in: query
      name: dfid
      schema:
        type: string
    exclude:
      description: Exclude filters
      in: query
      name: exclude
      schema:
        properties:
          total_hits:
            description: Exclude by the number of search results.
            type: integer
        type: object
    facet:
      description: Filter by a facet.
      in: query
      name: facet
      schema:
        items:
          type: string
        type: array
    format:
      description: Indicates which response format should be used
      in: query
      name: format
      schema:
        default: json
        enum:
          - json
          - csv
        type: string
    from:
      description: Start date of the period in the format of UNIX timestamp or YYYYMMDD.
      in: query
      name: from
      required: true
      schema:
        pattern: ^20\d{2}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$|^\d{10}|^\d{13}$
        type: string
    indices:
      description: |
        Filter by index name.

        Parameters:
          * name *: The name of the index to filter
          * hashid *: The hashid where `name` belongs

        Format:
          indices[i][name]=value&indices[i][hashid]=hashid.
      example: >-
        indices[1][name]=product1&indices[1][hashid]=hashid1&indices[2][name]=product2&indices[2][hashid]=hashid2
      in: query
      name: indices
      schema:
        type: object
    metric_name:
      description: Filter by the name of sector.
      in: path
      name: name
      required: true
      schema:
        enum:
          - click_through_rate
          - clicks_per_session
          - conversion_rate
          - searches_per_session
          - used_search
          - abandonment
        type: string
    no_results:
      description: Show only searches that exclusively yielded 0 results.
      in: query
      name: no_results
      schema:
        type: boolean
    opportunities:
      description: >-
        Show only searches that exclusively had "fuzzy" or "phonetic_text" as
        query name.
      in: query
      name: opportunities
      schema:
        type: boolean
    product_type:
      description: Filter by the type of product.
      in: query
      name: product_type
      schema:
        items:
          enum:
            - search
            - banner
            - custom_result
            - recommendation
            - quizz
            - aichat
          type: string
        type: array
    query:
      description: An string used to filter stats by input query.
      in: query
      name: query
      schema:
        type: string
    query_name:
      description: >-
        Type of query to filter by. Arrays parameters must be in the format
        `param[]=value`.
      in: query
      name: query_name
      schema:
        items:
          type: string
        type: array
    sector:
      description: Sector name to compute the benchmark for (e.g. "fashion", "technology").
      in: query
      name: sector
      required: true
      schema:
        type: string
    stats_hashid:
      deprecated: true
      in: query
      name: hashid
      schema:
        items:
          pattern: ^[a-f0-9]{32}$
          type: string
        type: array
    stats_hashids:
      description: >-
        Unique id of the search engine. It accepts an array of values. If you
        want to work with all user search engines just don't send this
        parameter. Arrays parameters must be in the format `param[]=value`.
      in: query
      name: hashids
      schema:
        items:
          pattern: ^[a-f0-9]{32}$
          type: string
        type: array
    to:
      description: End date of the period in the format of UNIX timestamp or YYYYMMDD.
      in: query
      name: to
      required: true
      schema:
        pattern: ^20\d{2}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$|^\d{10}$|^\d{13}
        type: string
    total_hits:
      description: Filter by the number of search results.
      in: query
      name: total_hits
      schema:
        type: integer
    tz:
      description: >
        The timezone for the given dates, by default, assumes ETC/UTC.

        In naming your time zones, you must stick to those indicated in the TZ
        database name column
        [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)
      example: Europe/Madrid
      in: query
      name: tz
      schema:
        default: Etc/UTC
        type: string
  responses:
    RegisterResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RegisterResult'
      description: Response returned over register stat operation.
    StatsBadRequest:
      content:
        application/json:
          example:
            error:
              code: bad_params
              message: Bad parameters error
          schema:
            $ref: '#/components/schemas/StatsError'
      description: Bad Request — invalid or missing query parameters.
    StatsForbidden:
      content:
        application/json:
          example:
            error:
              code: access_denied
              message: Access denied
          schema:
            $ref: '#/components/schemas/StatsError'
      description: >-
        Forbidden — token is valid but does not have access to this search
        engine.
    StatsNotFound:
      content:
        application/json:
          example:
            error:
              code: not_found
              message: Not found
          schema:
            $ref: '#/components/schemas/StatsError'
      description: Not Found — the requested search engine or resource does not exist.
    StatsTimeResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StatsTimeResult'
      description: Stats retrieved.
    StatsTimeout:
      content:
        application/json:
          example:
            error:
              code: timeout
              message: Request timed out
          schema:
            $ref: '#/components/schemas/StatsError'
      description: >-
        Request Timeout — the stats backend took too long; retry after a short
        delay.
    StatsTooManyRequests:
      content:
        application/json:
          example:
            error:
              code: too_many_requests
              message: Too many requests
          schema:
            $ref: '#/components/schemas/StatsError'
      description: Too Many Requests — rate limit exceeded; back off and retry.
    StatsUnauthorized:
      content:
        application/json:
          example:
            error:
              code: not_authenticated
              message: Authentication required
          schema:
            $ref: '#/components/schemas/StatsError'
      description: Unauthorized — no valid API token provided.
  schemas:
    has_init:
      default: true
      description: Indicates if the sale was made after using a doofinder product or not
      type: boolean
    StatsResultSerchesResult:
      allOf:
        - $ref: '#/components/schemas/StatsResult'
        - description: Stats searches from results.
          properties:
            results:
              items:
                properties:
                  brand:
                    example: Garnier
                    type: string
                  categories:
                    example:
                      - Perfumes
                      - OtroCategoria
                    items:
                      type: string
                    type: array
                  count:
                    example: 12
                    type: integer
                type: object
              type: array
          title: Top results searches
          type: object
      example:
        results:
          - brand: Garnier
            categories: Perfumes
            count: 200
        total: 1
        total_count: 200
    StatsTimeResult:
      allOf:
        - $ref: '#/components/schemas/StatsResult'
        - description: Stats counter with timestamp.
          properties:
            results:
              items:
                properties:
                  count:
                    example: 12
                    type: integer
                  timestamp:
                    example: 1581120000000
                    type: integer
                type: object
              type: array
          title: Counters Stats by Time
          type: object
      example:
        results:
          - count: 12
            timestamp: 1581120000000
        total: 1
        total_count: 12
    CartJSONRegisterRequest:
      properties:
        checkout_json:
          $ref: '#/components/schemas/checkout_json'
        currency:
          $ref: '#/components/schemas/currency'
        hashid:
          $ref: '#/components/schemas/hashid'
        ip:
          $ref: '#/components/schemas/ip'
        referer:
          $ref: '#/components/schemas/referer'
        session_id:
          $ref: '#/components/schemas/session_id'
        user_agent:
          $ref: '#/components/schemas/user_agent'
        user_id:
          $ref: '#/components/schemas/user_id'
      required:
        - hashid
        - checkout_json
      type: object
    StatsError:
      description: Standard error wrapper for all Stats API error responses.
      properties:
        error:
          properties:
            code:
              description: Machine-readable error code.
              example: not_authenticated
              type: string
            message:
              description: Human-readable error description.
              example: Authentication required
              type: string
          required:
            - code
          type: object
      required:
        - error
      type: object
    hashid:
      description: >-
        Unique id of the search engine. In the search engine selector, you will
        find the hashid information
      pattern: ^[a-f0-9]{32}$
      type: string
    user_id:
      description: Identifier of user
      maxLength: 36
      type: string
    StatsTopSearchesResult:
      allOf:
        - $ref: '#/components/schemas/StatsResult'
        - description: Stats results for top searches.
          properties:
            results:
              items:
                properties:
                  count:
                    example: 12
                    type: integer
                  query:
                    example: some term
                    type: string
                type: object
              type: array
          title: Top Searches Stats
          type: object
      example:
        results:
          - count: 12
            query: some term
        total: 1
        total_count: 12
    RegisterResult:
      description: Response returned over register stat operation.
      example:
        status: registered
      properties:
        status:
          description: Result of the stats request. i.e. 'registered'
          type: string
      title: Stats Response
      type: object
    TopSalesResult:
      description: Top Stats results for Sales.
      example:
        results:
          - avg_price: 500
            dfid: >-
              070cdedbb32a134ad74db5ac9cd93b36@product@74446c03dd1ae404c61723db51a6766b
            sum_amount: 30
            title: coffee capsules
          - avg_price: 200.25
            dfid: >-
              070cdedab32a134ad74db5ac9cd93b36@product@744d6c03dd1ae404c61723db51a6766b
            sum_amount: 20
            title: pencils
        total: 2
        total_count: 2
      properties:
        results:
          items:
            properties:
              avg_price:
                example: 3000
                type: number
              dfid:
                example: >-
                  070cdedbb32a134ad74db5ac9cd93b36@product@74446c03dd1ae404c61723db51a6766b
                type: string
              sum_amount:
                example: 21
                type: integer
              title:
                example: Item Title
                type: string
            type: object
          type: array
        total:
          description: Count of all top sales retrieved.
          example: 1
          type: integer
        total_count:
          description: Count of all top sales retrieved.
          example: 12
          type: integer
      title: Top Sales Results Stats
      type: object
    StatsBannersResult:
      allOf:
        - $ref: '#/components/schemas/StatsResult'
        - description: Stats results for banners.
          properties:
            results:
              items:
                properties:
                  clicks:
                    example: 2
                    type: integer
                  displays:
                    example: 12
                    type: integer
                  id:
                    example: 3561
                    type: integer
                type: object
              type: array
          title: Banner Stats
          type: object
      example:
        results:
          - clicks: 2
            displays: 12
            id: 3561
        total: 1
        total_count: 1
    StatsFacetsResult:
      allOf:
        - $ref: '#/components/schemas/StatsResult'
        - description: Stats results for facets.
          properties:
            results:
              items:
                properties:
                  count:
                    description: Number of times facet has been used in provided time range
                    type: integer
                  facet:
                    description: Used facet
                    type: string
                  timestamp:
                    description: >-
                      Date timestamp in the format of UNIX timestamp or
                      YYYYMMDD.
                    type: integer
                type: object
              type: array
          title: Facets Stats
          type: object
      example:
        results:
          - count: 12
            facet: brand
            timestamp: 1581120000000
        total: 1
        total_count: 12
    StatsRedirectsResult:
      allOf:
        - $ref: '#/components/schemas/StatsResult'
        - description: Stats results for redirections.
          properties:
            results:
              items:
                properties:
                  count:
                    example: 12
                    type: integer
                  id:
                    example: 9771
                    type: integer
                  link:
                    example: https://example.com/redirection
                    type: string
                type: object
              type: array
          title: Redirects Stats
          type: object
      example:
        results:
          - count: 12
            id: 9771
            link: https://example.com/redirection
        total: 1
        total_count: 12
    checkout_html:
      description: >-
        Base 64-encoded html for the checkout page. It should only contain the
        cart's products.
      type: string
    StatsCustomresultsResult:
      allOf:
        - $ref: '#/components/schemas/StatsResult'
        - description: Stats results for Custom results.
          properties:
            results:
              items:
                properties:
                  clicks:
                    example: 2
                    type: integer
                  displays:
                    example: 12
                    type: integer
                  id:
                    example: 3561
                    type: integer
                type: object
              type: array
          title: Custom Results Stats
          type: object
      example:
        results:
          - clicks: 2
            displays: 10
            id: 3561
          - clicks: 0
            displays: 5
            id: 3220
        total: 2
        total_count: 2
    SaleRequest:
      properties:
        has_init:
          $ref: '#/components/schemas/has_init'
        hashid:
          $ref: '#/components/schemas/hashid'
        ip:
          $ref: '#/components/schemas/ip'
        referer:
          $ref: '#/components/schemas/referer'
        session_id:
          $ref: '#/components/schemas/session_id'
        user_agent:
          $ref: '#/components/schemas/user_agent'
        user_id:
          $ref: '#/components/schemas/user_id'
      required:
        - hashid
      type: object
    StatsTopFacetsResult:
      allOf:
        - $ref: '#/components/schemas/StatsResult'
        - description: Top Stats results for facets.
          properties:
            results:
              items:
                properties:
                  count:
                    description: Number of times facet has been used in provided time range
                    type: integer
                  facet:
                    description: Used facet
                    type: string
                  searches:
                    description: List of searches and it's count when facet is applied.
                    items:
                      properties:
                        count:
                          description: Number of times a search is associated to facet.
                          type: integer
                        query:
                          description: search
                          type: string
                      type: object
                    type: array
                  value:
                    anyOf:
                      - description: Facet value used for filtering
                        type: string
                      - description: Range used for filtering
                        properties:
                          gte:
                            description: Start value of range
                            type: string
                          lte:
                            description: End value of range
                            type: string
                        type: object
                type: object
              type: array
          title: Top Facets Stats
          type: object
      example:
        results:
          - count: 10
            facet: categories
            searches:
              - count: 2
                query: example
              - count: 1
                query: example2
            value: Electronics
          - count: 7
            facet: price
            searches:
              - count: 2
                query: example
              - count: 1
                query: ''
            value:
              gte: '100'
              lt: '200'
        total: 2
        total_count: 17
    user_agent:
      deprecated: true
      description: Identifier of device. Detected automatically by the server.
      type: string
    currency:
      description: Currency of the checkout.
      example: EUR
      type: string
    url:
      description: Page URI visited by the user
      type: string
    SearchEngineUsageResult:
      description: Stats for user behaviour for a search engine.
      example:
        results:
          - inits: 2000
            searches: 8000
            visits: 3000
        total: 0
        total_count: 0
      properties:
        results:
          items:
            properties:
              inits:
                description: >-
                  How many times the layer has been loaded (unique clicks on
                  search bar)
                example: 2000
                type: integer
              searches:
                description: Total of searches done
                example: 8000
                type: integer
              visits:
                description: How many visits a store has received
                example: 3000
                type: number
            type: object
          type: array
        total:
          description: Always 0.
          example: 0
          type: integer
        total_count:
          description: Always 0.
          example: 0
          type: integer
      title: Search engine user stats
      type: object
    StatsInitsUsersResult:
      allOf:
        - $ref: '#/components/schemas/StatsResult'
        - description: Inits users result.
          example:
            results:
              - sessions: 12170
                unique_sessions: 159080
                users: 5876
            total: 1
            total_count: 1
          properties:
            results:
              items:
                properties:
                  sessions:
                    example: 12170
                    type: integer
                  unique_sessions:
                    example: 159080
                    type: integer
                  users:
                    example: 5876
                    type: integer
                type: object
              type: array
          title: Inits Users
          type: object
    referer:
      deprecated: true
      description: >-
        The referer header value, provides information about the URL from which
        the current request originated. Detected automatically by the server.
      type: string
    store:
      description: >-
        Identifier of store. In the store setup section, you will find the store
        ID information.
      maxLength: 36
      minLength: 1
      type: string
    StatsClickedItemsResult:
      allOf:
        - $ref: '#/components/schemas/StatsResult'
        - description: Stats results for clicked items.
          properties:
            results:
              items:
                properties:
                  count:
                    example: 12
                    type: integer
                  dfid:
                    example: >-
                      abff7f4819f8e532ef11ce6638963b4e@product@567b8f5f423af15818a068235807edc0
                    type: string
                  link:
                    example: https://example.com/item1
                    type: string
                  title:
                    example: Item Name
                    type: string
                type: object
              type: array
          title: Clicks Stats
          type: object
      example:
        results:
          - count: 12
            dfid: >-
              abff7f4819f8e532ef11ce6638963b4e@product@567b8f5f423af15818a068235807edc0
            link: https://example.com/item1
            source:
              link: https://example.com/item1
              title: Item Name
            title: Item Name
        total: 1
        total_count: 12
    StatsClicksItemsPositionResult:
      allOf:
        - $ref: '#/components/schemas/StatsResult'
        - description: Clicks items position result.
          properties:
            results:
              items:
                properties:
                  clicks:
                    description: How many clicks that product had in that position
                    example: 12170
                    type: integer
                  position:
                    description: The product's position when clicked
                    example: 10
                    type: integer
                  product:
                    description: The Id of the product
                    example: 5876
                    type: string
                type: object
              type: array
          title: Clicks Items Position
          type: object
      example:
        results:
          - clicks: 12170
            product_clicks: 159080
            sum_product_position: 5876
        total: 1
        total_count: 1
    checkout_json:
      description: Checkout json array with the cart items basic data.
      example:
        - id: prod_12345
          price: 29.99
          quantity: 2
        - id: prod_67890
          price: $12.50
          quantity: 1
      items:
        properties:
          id:
            description: The id field for the indexed item.
            example: prod_12345
            type: string
          price:
            description: >-
              The price of the product. If passed as a string, it is expected to
              have a currency. If passed as a number, it will use the search
              engine's currency.
            example: 29.99
            oneOf:
              - type: string
              - type: number
          quantity:
            description: How many items of this product are being bought.
            example: 2
            type: integer
          title:
            deprecated: true
            type: string
        required:
          - id
          - quantity
          - price
        type: object
      type: array
    StatsResult:
      properties:
        total:
          description: Sum of all elements retrieved.
          example: 1
          type: integer
        total_count:
          description: >-
            Total sum of all elements count. If element does not have a "count",
            this has the same value as `total`.
          example: 12
          type: integer
      title: Stats Result
      type: object
    StatsSalesResult:
      description: Stats results for Sales.
      example:
        results:
          - amount: 2.2
            session: 24cb1eccd1cf4a67d071f2deeac75e33
          - amount: 1
            session: a4eaf92a223c024b7c6680dc807c3f84
        total: 2
        total_amount: 3.2
      properties:
        results:
          items:
            properties:
              amount:
                example: 2
                format: float
                type: number
              session:
                example: ed8fb684573cdbb3d511e465c04e2d21
                type: string
            type: object
          type: array
        total:
          description: Count of all sales retrieved.
          example: 1
          type: integer
        total_amount:
          description: Total sum of all sales amount.
          example: 12
          type: integer
      title: Sales Results Stats
      type: object
    ip:
      deprecated: true
      description: >-
        Unique address that identifies a device. Detected automatically by the
        server.
      type: string
    StatsLocationResult:
      allOf:
        - $ref: '#/components/schemas/StatsResult'
        - description: Sessions geolocations result.
          properties:
            results:
              items:
                properties:
                  latitude:
                    example: 38.0952
                    format: float
                    type: number
                  longitude:
                    example: -3.636
                    format: float
                    type: number
                type: object
              type: array
          title: Sessions Geoocation
          type: object
      example:
        results:
          - latitude: 38.0952
            longitude: -3.636
        total: 1
        total_count: 1
    VisitRegisterRequest:
      properties:
        dfid:
          type: string
        hashid:
          $ref: '#/components/schemas/hashid'
        ip:
          $ref: '#/components/schemas/ip'
        page_type:
          type: string
        session_id:
          $ref: '#/components/schemas/session_id'
        store:
          $ref: '#/components/schemas/store'
        url:
          $ref: '#/components/schemas/url'
        user_agent:
          $ref: '#/components/schemas/user_agent'
        user_id:
          $ref: '#/components/schemas/user_id'
      required:
        - store
      type: object
    StatsSearchesLocationResult:
      allOf:
        - $ref: '#/components/schemas/StatsResult'
        - description: Searches locations result.
          properties:
            results:
              items:
                properties:
                  city:
                    example: Madrid
                    type: string
                  continent:
                    example: Europe
                    type: string
                  country:
                    example: Spain
                    type: string
                  latitude:
                    example: 38.0952
                    format: float
                    type: number
                  longitude:
                    example: -3.636
                    format: float
                    type: number
                  query:
                    example: perfume y hombre
                    type: string
                type: object
              type: array
          title: Searches Locations
          type: object
      example:
        results:
          - city: Madrid
            continent: Europe
            country: Spain
            latitude: 38.0952
            longitude: -3.636
            query: perfume y hombre
        total: 1
        total_count: 1
    session_id:
      description: Identifier of search session
      maxLength: 32
      nullable: true
      type: string
    StatsClicksUsersResult:
      allOf:
        - $ref: '#/components/schemas/StatsResult'
        - description: Clicks users result.
          properties:
            results:
              items:
                properties:
                  clicks:
                    example: 12170
                    type: integer
                  product_clicks:
                    example: 159080
                    type: integer
                  users:
                    example: 5876
                    type: integer
                type: object
              type: array
          title: Clicks Users
          type: object
      example:
        results:
          - clicks: 12170
            product_clicks: 159080
            users: 5876
        total: 1
        total_count: 1
  securitySchemes:
    api_token:
      description: |
        Doofinder API key. Pass it as:
        Authorization: Token <api_key>
      in: header
      name: Authorization
      type: apiKey
    jwt_token:
      description: |
        JWT Bearer token. Sign a JWT with your API key (HS256) and pass it as:
        Authorization: Bearer <jwt_token>
      in: header
      name: Authorization
      type: apiKey
info:
  contact:
    name: Doofinder Support
    url: https://docs.doofinder.com/
  description: >
    # Introduction


    Doofinder Stats API provides statistical information about your search
    engines.


    # Basics


    ## Endpoint


    All requests should be done via `https` to the right endpoint:


    ```

    https://{search-zone}-api.doofinder.com

    ```


    Where `{search-zone}` is the code of the datacenter where your search
    engines are located.


    For instance:


    ```

    https://eu1-api.doofinder.com

    https://us1-api.doofinder.com

    ```


    ## Authentication


    To authenticate you need a Doofinder API key. If you don't have one you can
    generate it in the Doofinder Admin by going to your Account and then to API
    Keys, [here](https://admin.doofinder.com/admin/account/api).


    A valid API key looks like this:


    ```

    ab46030xza33960aac71a10248489b6c26172f07

    ```


    ### API Token


    You can authenticate with the previous API key. The correct way to
    authenticate is to send a HTTP Header with the name `Authorization` and the
    value `Token {api-key}`.


    I.e.:


    ```

    Authorization: Token ab46030xza33960aac71a10248489b6c26172f07

    ```


    ### JWT Token


    If you prefer you can authenticate with a [JSON Web Token](https://jwt.io).
    The token must be signed with an API management key and there are some
    claims required in the JWT payload. These claims are:

      * `iat` (issued at): Creation datetime timestamp, i.e. the moment when the JWT was created.

      * `exp` (expiration time): Expiration datetime timestamp, i.e. the moment when the JWT is going to expire and will no longer be valid. The time span between issued and expiration dates must be shorter than a week.

      * `name`: Your user code. It is your unique identifier as doofinder user. You can find this code in your profile page in the Doofinder's administration panel.

    To authenticate using JWT you must send a HTTP header with the name
    `Authorization` and the value `Bearer {JWT-token}`.


    I.e.:


    ```

    Authorization: Bearer
    eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoidGVzdCIsImlhdCI6MTUxNjIzOTAyMn0.QX_3HF-T2-vlvzGDbAzZyc1Cd-J9qROSes3bxlgB4uk

    ```


    ## Conventions


    Along most of the code samples you will find placeholders for some common
    variable values. They are:

      * `{hashid}`: The search engine's unique id. e.g.: d8fdeab7fce96a19d3fc7b0ca7a1e98b.

      * `{index}`: When storing items, they're always stored under a certain _index_. e.g.: product.

      * `{token}`: Your personal authentication token obtained in the control panel.

    ## Api limits


    ### Requests rate


    The API has a limit of 20 requests per second. If you do more than that, the
    next requests will get a `429 Too Many Requests` error. There is no penalty
    associated to that error, but you must wait one second before attempting
    more requests.


    ### Body size


    The body size for requests with data sending (eg: POST or PUT requests) has
    a limit of 8MB. If you do a request with a request body bigger than 8 MB,
    the response will be `413 Payload Too Large`. This is important mostly for
    batch calls like batch create items.


    # Objects


    ## Search Engines


    A search engine is a collection of indices where data is stored. It has some
    properties like name, language, and some other configuration options that
    are shared among all of its indices.


    Each search engine is uniquely identified by its `hashid` which is an
    auto-generated string.


    Search engines have a _"process"_ operation which takes items from all its
    data sources and insert them into their indices. This operation has a zero
    downtime, you can still search into indices while processing.
  termsOfService: https://www.doofinder.com/en/terms-and-conditions
  title: Doofinder Stats API
  version: '2.0'
  x-logo:
    altText: Doofinder Search Engine
    backgroundColor: '#33268C'
    url: https://admin.doofinder.com/images/logo.svg
openapi: 3.0.0
paths:
  /api/v2/stats/banners:
    get:
      description: >-
        Gets how many times banners have been displayed and clicked in a time
        period, grouped by banner id.
      operationId: bannersStats
      parameters:
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/to'
        - $ref: '#/components/parameters/stats_hashids'
        - $ref: '#/components/parameters/stats_hashid'
        - description: Unique id of the banner.
          in: query
          name: id
          schema:
            type: string
        - $ref: '#/components/parameters/tz'
        - $ref: '#/components/parameters/format'
        - $ref: '#/components/parameters/aggregate'
        - $ref: '#/components/parameters/indices'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatsBannersResult'
          description: Stats retrieved.
        '400':
          $ref: '#/components/responses/StatsBadRequest'
        '401':
          $ref: '#/components/responses/StatsUnauthorized'
        '403':
          $ref: '#/components/responses/StatsForbidden'
        '404':
          $ref: '#/components/responses/StatsNotFound'
        '408':
          $ref: '#/components/responses/StatsTimeout'
        '429':
          $ref: '#/components/responses/StatsTooManyRequests'
      summary: Banners
      tags:
        - Features
  /api/v2/stats/carts:
    post:
      description: Process checkout cart information on Doofinder statistics.
      operationId: registerCart
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CartJSONRegisterRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/responses/RegisterResponse'
          description: OK
        '400':
          $ref: '#/components/responses/StatsBadRequest'
      summary: Checkout cart process
      tags:
        - Conversions & Sales
  /api/v2/stats/checkouts:
    get:
      description: Counts numbers of checkouts in a time period grouped by day.
      operationId: checkoutsByDate
      parameters:
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/to'
        - $ref: '#/components/parameters/stats_hashids'
        - $ref: '#/components/parameters/stats_hashid'
        - $ref: '#/components/parameters/tz'
        - $ref: '#/components/parameters/device'
        - $ref: '#/components/parameters/format'
        - $ref: '#/components/parameters/aggregate'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatsTimeResult'
          description: Stats retrieved.
        '400':
          $ref: '#/components/responses/StatsBadRequest'
        '401':
          $ref: '#/components/responses/StatsUnauthorized'
        '403':
          $ref: '#/components/responses/StatsForbidden'
        '404':
          $ref: '#/components/responses/StatsNotFound'
        '408':
          $ref: '#/components/responses/StatsTimeout'
        '429':
          $ref: '#/components/responses/StatsTooManyRequests'
      summary: Checkouts
      tags:
        - Conversions & Sales
  /api/v2/stats/clicked_items:
    get:
      description: Gets the most commonly clicked items in a time period.
      operationId: clickedItems
      parameters:
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/to'
        - $ref: '#/components/parameters/stats_hashids'
        - $ref: '#/components/parameters/stats_hashid'
        - $ref: '#/components/parameters/tz'
        - $ref: '#/components/parameters/device'
        - $ref: '#/components/parameters/format'
        - $ref: '#/components/parameters/aggregate'
        - $ref: '#/components/parameters/indices'
        - $ref: '#/components/parameters/query'
        - $ref: '#/components/parameters/dfid'
        - description: >-
            Maximum number of items to return with a minimum of 1 item and a
            maximum of 1000.
          in: query
          name: limit
          schema:
            default: 100
            maximum: 1000
            minimum: 1
            type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatsClickedItemsResult'
          description: Stats retrieved.
        '400':
          $ref: '#/components/responses/StatsBadRequest'
        '401':
          $ref: '#/components/responses/StatsUnauthorized'
        '403':
          $ref: '#/components/responses/StatsForbidden'
        '404':
          $ref: '#/components/responses/StatsNotFound'
        '408':
          $ref: '#/components/responses/StatsTimeout'
        '429':
          $ref: '#/components/responses/StatsTooManyRequests'
      summary: Clicked items
      tags:
        - Clicks & Interactions
  /api/v2/stats/clicked_items/position:
    get:
      description: >-
        Gets the number of clicks each clicked product had in a period of time
        grouped by position.
      operationId: clicksItemsPosition
      parameters:
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/to'
        - $ref: '#/components/parameters/stats_hashids'
        - $ref: '#/components/parameters/indices'
        - $ref: '#/components/parameters/query'
        - $ref: '#/components/parameters/dfid'
        - $ref: '#/components/parameters/device'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatsClicksItemsPositionResult'
          description: Stats retrieved.
        '400':
          $ref: '#/components/responses/StatsBadRequest'
        '401':
          $ref: '#/components/responses/StatsUnauthorized'
        '403':
          $ref: '#/components/responses/StatsForbidden'
        '404':
          $ref: '#/components/responses/StatsNotFound'
        '408':
          $ref: '#/components/responses/StatsTimeout'
        '429':
          $ref: '#/components/responses/StatsTooManyRequests'
      summary: Clicks items and position
      tags:
        - Clicks & Interactions
  /api/v2/stats/clicked_items/searches:
    get:
      description: >-
        Gets the most common searched for a clicked item, and how many times it
        has been clicked from those searches.
      operationId: clickedItemSearches
      parameters:
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/to'
        - $ref: '#/components/parameters/stats_hashids'
        - $ref: '#/components/parameters/stats_hashid'
        - $ref: '#/components/parameters/tz'
        - $ref: '#/components/parameters/device'
        - $ref: '#/components/parameters/format'
        - $ref: '#/components/parameters/aggregate'
        - $ref: '#/components/parameters/indices'
        - $ref: '#/components/parameters/query'
        - $ref: '#/components/parameters/dfid'
          required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatsTopSearchesResult'
          description: Stats retrieved.
        '400':
          $ref: '#/components/responses/StatsBadRequest'
        '401':
          $ref: '#/components/responses/StatsUnauthorized'
        '403':
          $ref: '#/components/responses/StatsForbidden'
        '404':
          $ref: '#/components/responses/StatsNotFound'
        '408':
          $ref: '#/components/responses/StatsTimeout'
        '429':
          $ref: '#/components/responses/StatsTooManyRequests'
      summary: Clicked item searches
      tags:
        - Clicks & Interactions
  /api/v2/stats/clicks:
    get:
      description: Counts number of clicks in a time period grouped by day.
      operationId: clicksByDate
      parameters:
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/to'
        - $ref: '#/components/parameters/stats_hashids'
        - $ref: '#/components/parameters/stats_hashid'
        - $ref: '#/components/parameters/tz'
        - $ref: '#/components/parameters/device'
        - $ref: '#/components/parameters/format'
        - $ref: '#/components/parameters/aggregate'
        - $ref: '#/components/parameters/indices'
        - $ref: '#/components/parameters/query'
        - $ref: '#/components/parameters/dfid'
        - $ref: '#/components/parameters/product_type'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatsTimeResult'
          description: Stats retrieved.
        '400':
          $ref: '#/components/responses/StatsBadRequest'
        '401':
          $ref: '#/components/responses/StatsUnauthorized'
        '403':
          $ref: '#/components/responses/StatsForbidden'
        '404':
          $ref: '#/components/responses/StatsNotFound'
        '408':
          $ref: '#/components/responses/StatsTimeout'
        '429':
          $ref: '#/components/responses/StatsTooManyRequests'
      summary: Clicks
      tags:
        - Clicks & Interactions
  /api/v2/stats/clicks/users:
    get:
      description: >-
        Counts numbers of different users and products in clicks for a time
        period.
      operationId: clicksByUsers
      parameters:
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/to'
        - $ref: '#/components/parameters/stats_hashids'
        - $ref: '#/components/parameters/indices'
        - $ref: '#/components/parameters/query'
        - $ref: '#/components/parameters/dfid'
        - $ref: '#/components/parameters/device'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatsClicksUsersResult'
          description: Stats retrieved.
        '400':
          $ref: '#/components/responses/StatsBadRequest'
        '401':
          $ref: '#/components/responses/StatsUnauthorized'
        '403':
          $ref: '#/components/responses/StatsForbidden'
        '404':
          $ref: '#/components/responses/StatsNotFound'
        '408':
          $ref: '#/components/responses/StatsTimeout'
        '429':
          $ref: '#/components/responses/StatsTooManyRequests'
      summary: Clicks with users
      tags:
        - Clicks & Interactions
  /api/v2/stats/custom-results:
    get:
      description: >-
        Gets how many times custom results have been displayed and clicked in a
        time period, grouped by custom result id.
      operationId: customResultsStats
      parameters:
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/to'
        - $ref: '#/components/parameters/stats_hashids'
        - $ref: '#/components/parameters/stats_hashid'
        - description: Unique id of the custom result.
          in: query
          name: id
          schema:
            type: string
        - $ref: '#/components/parameters/tz'
        - $ref: '#/components/parameters/format'
        - $ref: '#/components/parameters/aggregate'
        - $ref: '#/components/parameters/indices'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatsCustomresultsResult'
          description: Stats retrieved.
        '400':
          $ref: '#/components/responses/StatsBadRequest'
        '401':
          $ref: '#/components/responses/StatsUnauthorized'
        '403':
          $ref: '#/components/responses/StatsForbidden'
        '404':
          $ref: '#/components/responses/StatsNotFound'
        '408':
          $ref: '#/components/responses/StatsTimeout'
        '429':
          $ref: '#/components/responses/StatsTooManyRequests'
      summary: Custom results
      tags:
        - Features
  /api/v2/stats/facets:
    get:
      description: >-
        Gets how many times facets filters have been used in a time period,
        grouped by facet field.
      operationId: facetsStats
      parameters:
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/to'
        - $ref: '#/components/parameters/stats_hashids'
        - $ref: '#/components/parameters/stats_hashid'
        - $ref: '#/components/parameters/tz'
        - $ref: '#/components/parameters/device'
        - $ref: '#/components/parameters/facet'
        - $ref: '#/components/parameters/aggregate'
        - $ref: '#/components/parameters/query'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatsFacetsResult'
          description: Stats retrieved.
        '400':
          $ref: '#/components/responses/StatsBadRequest'
        '401':
          $ref: '#/components/responses/StatsUnauthorized'
        '403':
          $ref: '#/components/responses/StatsForbidden'
        '404':
          $ref: '#/components/responses/StatsNotFound'
        '408':
          $ref: '#/components/responses/StatsTimeout'
        '429':
          $ref: '#/components/responses/StatsTooManyRequests'
      summary: Facets
      tags:
        - Features
  /api/v2/stats/facets/top:
    get:
      description: >-
        Gets most common facets filters used, how many times they have been used
        and which filter has been applied in a time period.
      operationId: facetsTopStats
      parameters:
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/to'
        - $ref: '#/components/parameters/stats_hashids'
        - $ref: '#/components/parameters/stats_hashid'
        - $ref: '#/components/parameters/tz'
        - $ref: '#/components/parameters/device'
        - $ref: '#/components/parameters/facet'
        - $ref: '#/components/parameters/format'
        - $ref: '#/components/parameters/aggregate'
        - $ref: '#/components/parameters/query'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatsTopFacetsResult'
          description: Stats retrieved.
        '400':
          $ref: '#/components/responses/StatsBadRequest'
        '401':
          $ref: '#/components/responses/StatsUnauthorized'
        '403':
          $ref: '#/components/responses/StatsForbidden'
        '404':
          $ref: '#/components/responses/StatsNotFound'
        '408':
          $ref: '#/components/responses/StatsTimeout'
        '429':
          $ref: '#/components/responses/StatsTooManyRequests'
      summary: Top facets values
      tags:
        - Features
  /api/v2/stats/facets_by_day:
    get:
      description: >-
        Gets how many times facets filters have been used in a time period,
        grouped by day.
      operationId: facetsStatsByDay
      parameters:
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/to'
        - $ref: '#/components/parameters/stats_hashid'
        - $ref: '#/components/parameters/stats_hashids'
        - $ref: '#/components/parameters/tz'
        - $ref: '#/components/parameters/device'
        - $ref: '#/components/parameters/facet'
        - $ref: '#/components/parameters/aggregate'
        - $ref: '#/components/parameters/query'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatsFacetsResult'
          description: Stats retrieved.
        '400':
          $ref: '#/components/responses/StatsBadRequest'
        '401':
          $ref: '#/components/responses/StatsUnauthorized'
        '403':
          $ref: '#/components/responses/StatsForbidden'
        '404':
          $ref: '#/components/responses/StatsNotFound'
        '408':
          $ref: '#/components/responses/StatsTimeout'
        '429':
          $ref: '#/components/responses/StatsTooManyRequests'
      summary: Facets by day
      tags:
        - Features
  /api/v2/stats/inits:
    get:
      description: >-
        Counts number of total unique search sessions in a time period group by
        day.
      operationId: initsByDate
      parameters:
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/to'
        - $ref: '#/components/parameters/stats_hashids'
        - $ref: '#/components/parameters/stats_hashid'
        - $ref: '#/components/parameters/tz'
        - $ref: '#/components/parameters/device'
        - $ref: '#/components/parameters/format'
        - $ref: '#/components/parameters/aggregate'
      responses:
        '200':
          $ref: '#/components/responses/StatsTimeResponse'
        '400':
          $ref: '#/components/responses/StatsBadRequest'
        '401':
          $ref: '#/components/responses/StatsUnauthorized'
        '403':
          $ref: '#/components/responses/StatsForbidden'
        '404':
          $ref: '#/components/responses/StatsNotFound'
        '408':
          $ref: '#/components/responses/StatsTimeout'
        '429':
          $ref: '#/components/responses/StatsTooManyRequests'
      summary: Sessions
      tags:
        - Usage & Sessions
  /api/v2/stats/inits/locations:
    get:
      description: Gets all sessions geolocation for a time period.
      operationId: initsLocations
      parameters:
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/to'
        - $ref: '#/components/parameters/stats_hashids'
        - $ref: '#/components/parameters/stats_hashid'
        - $ref: '#/components/parameters/tz'
        - $ref: '#/components/parameters/device'
        - $ref: '#/components/parameters/aggregate'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatsLocationResult'
          description: Geolocations retrieved.
        '400':
          $ref: '#/components/responses/StatsBadRequest'
        '401':
          $ref: '#/components/responses/StatsUnauthorized'
        '403':
          $ref: '#/components/responses/StatsForbidden'
        '404':
          $ref: '#/components/responses/StatsNotFound'
        '408':
          $ref: '#/components/responses/StatsTimeout'
        '429':
          $ref: '#/components/responses/StatsTooManyRequests'
      summary: Sessions geolocation
      tags:
        - Usage & Sessions
  /api/v2/stats/inits/users:
    get:
      description: Counts numbers of different users in sessions for a time period.
      operationId: initsByUser
      parameters:
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/to'
        - $ref: '#/components/parameters/stats_hashids'
        - $ref: '#/components/parameters/device'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatsInitsUsersResult'
          description: Stats retrieved.
        '400':
          $ref: '#/components/responses/StatsBadRequest'
        '401':
          $ref: '#/components/responses/StatsUnauthorized'
        '403':
          $ref: '#/components/responses/StatsForbidden'
        '404':
          $ref: '#/components/responses/StatsNotFound'
        '408':
          $ref: '#/components/responses/StatsTimeout'
        '429':
          $ref: '#/components/responses/StatsTooManyRequests'
      summary: Inits with users
      tags:
        - Usage & Sessions
  /api/v2/stats/redirects:
    get:
      description: >-
        Gets redirections and how many times users make use of them in a time
        period.
      operationId: redirects
      parameters:
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/to'
        - $ref: '#/components/parameters/stats_hashids'
        - $ref: '#/components/parameters/stats_hashid'
        - description: Filter by the unique id of a redirection.
          in: query
          name: id
          schema:
            type: integer
        - $ref: '#/components/parameters/tz'
        - $ref: '#/components/parameters/format'
        - $ref: '#/components/parameters/aggregate'
        - $ref: '#/components/parameters/query'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatsRedirectsResult'
          description: OK
        '400':
          $ref: '#/components/responses/StatsBadRequest'
        '401':
          $ref: '#/components/responses/StatsUnauthorized'
        '403':
          $ref: '#/components/responses/StatsForbidden'
        '404':
          $ref: '#/components/responses/StatsNotFound'
        '408':
          $ref: '#/components/responses/StatsTimeout'
        '429':
          $ref: '#/components/responses/StatsTooManyRequests'
      summary: Redirections
      tags:
        - Clicks & Interactions
  /api/v2/stats/results/top:
    get:
      description: >-
        Gets the most commonly `metric` obtained in searches during a time
        period. Where `metric` can be brand or categories.
      operationId: resultsSearches
      parameters:
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/to'
        - $ref: '#/components/parameters/stats_hashids'
        - $ref: '#/components/parameters/query'
        - $ref: '#/components/parameters/dfid'
        - $ref: '#/components/parameters/device'
        - description: >-
            Parameter to group and filter the data based on your choice, which
            can be either 'brand' or 'categories'.
          in: query
          name: metric
          schema:
            enum:
              - brand
              - categories
            type: string
        - description: >-
            Maximum number of items to return with a minimum of 1 item and a
            maximum of 1000.
          in: query
          name: limit
          schema:
            default: 100
            maximum: 1000
            minimum: 1
            type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatsResultSerchesResult'
          description: Stats retrieved.
        '400':
          $ref: '#/components/responses/StatsBadRequest'
        '401':
          $ref: '#/components/responses/StatsUnauthorized'
        '403':
          $ref: '#/components/responses/StatsForbidden'
        '404':
          $ref: '#/components/responses/StatsNotFound'
        '408':
          $ref: '#/components/responses/StatsTimeout'
        '429':
          $ref: '#/components/responses/StatsTooManyRequests'
      summary: Results searches
      tags:
        - Searches
  /api/v2/stats/sales:
    get:
      description: >-
        Gets the total price for sales checkouts in a period, where a session id
        identifies every sale.
      operationId: sales
      parameters:
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/to'
        - $ref: '#/components/parameters/stats_hashids'
        - $ref: '#/components/parameters/stats_hashid'
        - $ref: '#/components/parameters/tz'
        - $ref: '#/components/parameters/format'
        - $ref: '#/components/parameters/device'
        - $ref: '#/components/parameters/aggregate'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatsSalesResult'
          description: Sales retrieved.
        '400':
          $ref: '#/components/responses/StatsBadRequest'
        '401':
          $ref: '#/components/responses/StatsUnauthorized'
        '403':
          $ref: '#/components/responses/StatsForbidden'
        '404':
          $ref: '#/components/responses/StatsNotFound'
        '408':
          $ref: '#/components/responses/StatsTimeout'
        '429':
          $ref: '#/components/responses/StatsTooManyRequests'
      summary: Sales
      tags:
        - Conversions & Sales
    post:
      description: Register checkout event.
      operationId: checkoutSale
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SaleRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/responses/RegisterResponse'
          description: OK
        '400':
          $ref: '#/components/responses/StatsBadRequest'
      summary: Sale confirm
      tags:
        - Conversions & Sales
  /api/v2/stats/search_engine_users:
    get:
      description: >-
        Gets how many visits a Search engine receive and from that users how
        many inits & searches in a time period
      operationId: searchEngineUsersStats
      parameters:
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/to'
        - $ref: '#/components/parameters/stats_hashids'
        - $ref: '#/components/parameters/stats_hashid'
        - $ref: '#/components/parameters/tz'
        - $ref: '#/components/parameters/format'
        - $ref: '#/components/parameters/aggregate'
        - $ref: '#/components/parameters/device'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchEngineUsageResult'
          description: Stats retrieved.
        '400':
          $ref: '#/components/responses/StatsBadRequest'
        '401':
          $ref: '#/components/responses/StatsUnauthorized'
        '403':
          $ref: '#/components/responses/StatsForbidden'
        '404':
          $ref: '#/components/responses/StatsNotFound'
        '408':
          $ref: '#/components/responses/StatsTimeout'
        '429':
          $ref: '#/components/responses/StatsTooManyRequests'
      summary: Search engine usage
      tags:
        - Usage & Sessions
  /api/v2/stats/searches:
    get:
      description: Counts number of searches in a time period grouped by day.
      operationId: searchesByDate
      parameters:
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/to'
        - $ref: '#/components/parameters/stats_hashids'
        - $ref: '#/components/parameters/stats_hashid'
        - $ref: '#/components/parameters/tz'
        - $ref: '#/components/parameters/device'
        - $ref: '#/components/parameters/format'
        - $ref: '#/components/parameters/query_name'
        - $ref: '#/components/parameters/indices'
        - $ref: '#/components/parameters/query'
        - $ref: '#/components/parameters/dfid'
        - description: Filter by the search source.
          in: query
          name: source
          schema:
            enum:
              - voice
              - image
              - visually_similar
            type: string
        - $ref: '#/components/parameters/total_hits'
        - $ref: '#/components/parameters/aggregate'
      responses:
        '200':
          $ref: '#/components/responses/StatsTimeResponse'
        '400':
          $ref: '#/components/responses/StatsBadRequest'
        '401':
          $ref: '#/components/responses/StatsUnauthorized'
        '403':
          $ref: '#/components/responses/StatsForbidden'
        '404':
          $ref: '#/components/responses/StatsNotFound'
        '408':
          $ref: '#/components/responses/StatsTimeout'
        '429':
          $ref: '#/components/responses/StatsTooManyRequests'
      summary: Searches
      tags:
        - Searches
  /api/v2/stats/searches/locations:
    get:
      description: Gets all searches locations for a time period.
      operationId: searchesLocations
      parameters:
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/to'
        - $ref: '#/components/parameters/stats_hashids'
        - $ref: '#/components/parameters/tz'
        - $ref: '#/components/parameters/aggregate'
        - $ref: '#/components/parameters/indices'
        - $ref: '#/components/parameters/query'
        - $ref: '#/components/parameters/dfid'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatsSearchesLocationResult'
          description: Locations retrieved.
        '400':
          $ref: '#/components/responses/StatsBadRequest'
        '401':
          $ref: '#/components/responses/StatsUnauthorized'
        '403':
          $ref: '#/components/responses/StatsForbidden'
        '404':
          $ref: '#/components/responses/StatsNotFound'
        '408':
          $ref: '#/components/responses/StatsTimeout'
        '429':
          $ref: '#/components/responses/StatsTooManyRequests'
      summary: Searches locations
      tags:
        - Searches
  /api/v2/stats/searches/popular:
    get:
      description: >-
        Gets the most popular searches (the ones containing most clicked items)
        in a time period.
      operationId: searchesPopular
      parameters:
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/to'
        - $ref: '#/components/parameters/stats_hashids'
        - $ref: '#/components/parameters/stats_hashid'
        - $ref: '#/components/parameters/tz'
        - $ref: '#/components/parameters/device'
        - $ref: '#/components/parameters/format'
        - $ref: '#/components/parameters/exclude'
        - $ref: '#/components/parameters/aggregate'
        - $ref: '#/components/parameters/indices'
        - $ref: '#/components/parameters/query'
        - $ref: '#/components/parameters/dfid'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatsTopSearchesResult'
          description: Stats retrieved.
        '400':
          $ref: '#/components/responses/StatsBadRequest'
        '401':
          $ref: '#/components/responses/StatsUnauthorized'
        '403':
          $ref: '#/components/responses/StatsForbidden'
        '404':
          $ref: '#/components/responses/StatsNotFound'
        '408':
          $ref: '#/components/responses/StatsTimeout'
        '429':
          $ref: '#/components/responses/StatsTooManyRequests'
      summary: Popular searches
      tags:
        - Searches
  /api/v2/stats/searches/top:
    get:
      description: Gets a list of the most common searches in a time period.
      operationId: searchesTop
      parameters:
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/to'
        - $ref: '#/components/parameters/stats_hashids'
        - $ref: '#/components/parameters/stats_hashid'
        - $ref: '#/components/parameters/tz'
        - $ref: '#/components/parameters/device'
        - $ref: '#/components/parameters/format'
        - $ref: '#/components/parameters/query_name'
        - $ref: '#/components/parameters/total_hits'
        - $ref: '#/components/parameters/no_results'
        - $ref: '#/components/parameters/opportunities'
        - $ref: '#/components/parameters/exclude'
        - $ref: '#/components/parameters/aggregate'
        - $ref: '#/components/parameters/indices'
        - $ref: '#/components/parameters/query'
        - $ref: '#/components/parameters/dfid'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatsTopSearchesResult'
          description: Stats retrieved.
        '400':
          $ref: '#/components/responses/StatsBadRequest'
        '401':
          $ref: '#/components/responses/StatsUnauthorized'
        '403':
          $ref: '#/components/responses/StatsForbidden'
        '404':
          $ref: '#/components/responses/StatsNotFound'
        '408':
          $ref: '#/components/responses/StatsTimeout'
        '429':
          $ref: '#/components/responses/StatsTooManyRequests'
      summary: Top searches
      tags:
        - Searches
  /api/v2/stats/sector/{name}:
    get:
      description: >-
        Retrieve the median of the metric you send for the sector and/or the
        hashid.
      operationId: sector
      parameters:
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/to'
        - $ref: '#/components/parameters/stats_hashids'
        - $ref: '#/components/parameters/stats_hashid'
        - $ref: '#/components/parameters/sector'
        - $ref: '#/components/parameters/metric_name'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatsTimeResult'
          description: Stats retrieved.
        '400':
          $ref: '#/components/responses/StatsBadRequest'
        '401':
          $ref: '#/components/responses/StatsUnauthorized'
        '403':
          $ref: '#/components/responses/StatsForbidden'
        '404':
          $ref: '#/components/responses/StatsNotFound'
        '408':
          $ref: '#/components/responses/StatsTimeout'
        '429':
          $ref: '#/components/responses/StatsTooManyRequests'
      summary: Sector
      tags:
        - Features
  /api/v2/stats/top-sales:
    get:
      description: Gets the top sold items in a period.
      operationId: top_sales
      parameters:
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/to'
        - $ref: '#/components/parameters/stats_hashids'
        - $ref: '#/components/parameters/stats_hashid'
        - $ref: '#/components/parameters/tz'
        - $ref: '#/components/parameters/format'
        - $ref: '#/components/parameters/device'
        - $ref: '#/components/parameters/aggregate'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopSalesResult'
          description: Top sales retrieved.
        '400':
          $ref: '#/components/responses/StatsBadRequest'
        '401':
          $ref: '#/components/responses/StatsUnauthorized'
        '403':
          $ref: '#/components/responses/StatsForbidden'
        '404':
          $ref: '#/components/responses/StatsNotFound'
        '408':
          $ref: '#/components/responses/StatsTimeout'
        '429':
          $ref: '#/components/responses/StatsTooManyRequests'
      summary: Get top sales
      tags:
        - Conversions & Sales
  /api/v2/stats/usage:
    get:
      description: |
        Gets the usage of a list of search engines during a period.

        It sums the query and API requests made to the service.
        Since usage is computed in UTC time, there is no need to specify the
        timezone in this endpoint.
      operationId: usage
      parameters:
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/to'
        - $ref: '#/components/parameters/stats_hashids'
        - $ref: '#/components/parameters/stats_hashid'
        - $ref: '#/components/parameters/account_code'
        - $ref: '#/components/parameters/aggregate'
        - description: >-
            Filter usage by the given type, `query_counters` for requests to
            search API, and `api_counters` for requests to management API. You
            can also filter by product or obtain everything with `all`. If no
            type is provided it filters by `search`.
          in: query
          name: type
          schema:
            enum:
              - api_counters
              - query_counters
              - recommendations_counters
              - visual_counters
              - quiz_counters
              - category_page_counters
              - search
              - quizzes
              - recommendations
              - assistant_counters
              - all
            type: string
        - $ref: '#/components/parameters/format'
      responses:
        '200':
          $ref: '#/components/responses/StatsTimeResponse'
        '400':
          $ref: '#/components/responses/StatsBadRequest'
        '401':
          $ref: '#/components/responses/StatsUnauthorized'
        '403':
          $ref: '#/components/responses/StatsForbidden'
        '404':
          $ref: '#/components/responses/StatsNotFound'
        '408':
          $ref: '#/components/responses/StatsTimeout'
        '429':
          $ref: '#/components/responses/StatsTooManyRequests'
      summary: Usage
      tags:
        - Usage & Sessions
  /api/v2/stats/visit:
    post:
      description: Save visit event on Doofinder statistics
      operationId: registerVisit
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VisitRegisterRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/responses/RegisterResponse'
          description: OK
        '400':
          $ref: '#/components/responses/StatsBadRequest'
      summary: Visit stats
      tags:
        - Features
security:
  - api_token: []
  - jwt_token: []
servers:
  - url: https://{search_zone}-api.doofinder.com
    variables:
      search_zone:
        default: eu1
        enum:
          - eu1
          - us1
          - ap1
  - url: /
tags:
  - description: Session and usage statistics for your search engines.
    name: Usage & Sessions
  - description: Search activity and top search statistics.
    name: Searches
  - description: Click events and user interaction statistics.
    name: Clicks & Interactions
  - description: Sales, checkout, and conversion statistics.
    name: Conversions & Sales
  - description: Feature-specific statistics including banners, facets, quizzes, and more.
    name: Features
  - description: Visit event registration.
    name: Visits
  - description: Internal usage metrics.
    name: Internal