> ## Documentation Index > Fetch the complete documentation index at: https://docs.doofinder.com/llms.txt > Use this file to discover all available pages before exploring further. # Searches locations > Gets all searches locations for a time period. ## OpenAPI ````yaml /openapi/stats-v2.yaml get /api/v2/stats/searches/locations openapi: 3.0.0 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 servers: - url: https://{search_zone}-api.doofinder.com variables: search_zone: default: eu1 enum: - eu1 - us1 - ap1 - url: / security: - api_token: [] - jwt_token: [] 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 paths: /api/v2/stats/searches/locations: get: tags: - Searches summary: Searches locations 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' components: parameters: 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 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 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 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 aggregate: description: Flag to indicate when to aggregate all Search Engines stats data. in: query name: aggregate required: false schema: default: true type: boolean 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 query: description: An string used to filter stats by input query. in: query name: query schema: 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 schemas: 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 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 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 responses: 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. StatsUnauthorized: content: application/json: example: error: code: not_authenticated message: Authentication required schema: $ref: '#/components/schemas/StatsError' description: Unauthorized — no valid API token provided. 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. 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. securitySchemes: api_token: description: | Doofinder API key. Pass it as: Authorization: Token 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 in: header name: Authorization type: apiKey ````