> ## 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. # Search query > Search through indexed items of a search engine. ## OpenAPI ````yaml /openapi/search-v6.yaml get /6/{hashid}/_search openapi: 3.0.0 info: title: Search API contact: name: Doofinder Support url: https://docs.doofinder.com/ version: '6.0' description: > # Introduction Search API allows you to perform the search requests you can do on your search engines using the doofinder layer, directly from your code. # Basics ## Endpoint All requests should be done with `https` protocol in our api location. `https://{search_zone}-search.doofinder.com` where `{search_zone}` depends on your location, is the geographic zone your search engine is located at. i.e.: eu1. Also, indicates which host to use in your API calls. ## Authentication The authentication method for search API requires an api key that could be obtained in our [management control panel](https://admin.doofinder.com). You can generate it in your user account -> Api Keys. Example of the generated API Key: `eu1-ab46030xza33960aac71a10248489b6c26172f07` ### API Token You could authenticate with the previous API key in header as a Token. The correct way to authenticate is to send a HTTP Header with the name `Authorization` and the value `Token ` For example, for the key shown above: `Authorization: Token eu1-ab46030xza33960aac71a10248489b6c26172f07` ## 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. i.e.: d8fdeab7fce96a19d3fc7b0ca7a1e98b - `{token}`: Your personal authentication token obtained in the control panel. - `{index}`: The index of the data you're searching at. i.e.: product - `{id}`: Unique identification of a resource. i.e.: 1234 or HVIUYC termsOfService: https://www.doofinder.com/es/terms-and-conditions x-logo: url: https://admin.doofinder.com/images/logo.svg backgroundColor: '#33268C' altText: Doofinder Search Engine servers: - url: https://{search_zone}-search.doofinder.com variables: search_zone: enum: - eu1 - us1 - ap1 default: eu1 - url: / security: - api_token: [] tags: - name: Search description: Search operations. - name: Session & Events description: Stats operations. paths: /6/{hashid}/_search: get: tags: - Search summary: Search query description: Search through indexed items of a search engine. operationId: search_query parameters: - $ref: '#/components/parameters/hashid' - $ref: '#/components/parameters/auto_filters' - $ref: '#/components/parameters/custom_results' - $ref: '#/components/parameters/excluded_results' - $ref: '#/components/parameters/exclude' - $ref: '#/components/parameters/facets' - $ref: '#/components/parameters/filter' - $ref: '#/components/parameters/filter_execution' - $ref: '#/components/parameters/grouping' - $ref: '#/components/parameters/with_variants' - $ref: '#/components/parameters/indices' - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/query' - $ref: '#/components/parameters/query_name' - $ref: '#/components/parameters/rpp' - $ref: '#/components/parameters/session_id_query' - $ref: '#/components/parameters/user_id_query' - $ref: '#/components/parameters/stats' - $ref: '#/components/parameters/skip_auto_filters' - $ref: '#/components/parameters/skip_top_facet' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/title_facet' - $ref: '#/components/parameters/top_facet' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/SearchResponse' '400': description: >- Bad Request — invalid query parameters (invalid rpp, page, query_name, sort, filter_execution, session_id, or user_id). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_query: summary: Bad query value value: error: Bad request, bad query invalid_session_id: summary: session_id too long value: error: session_id should have 32 characters or less invalid_rpp: summary: Invalid rpp value: error: Invalid rpp '403': description: >- Forbidden — missing or invalid API token, client IP is blocked, or CORS `Origin` not allowed. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Missing or invalid API token value: error: forbidden banned_ip: summary: Client IP is blocked value: error: banned ip '404': description: Not Found — search engine mapping does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: summary: Mapping not found value: error: Mapping not found components: parameters: hashid: name: hashid in: path description: Unique id of a search engine. required: true schema: type: string auto_filters: name: auto_filters in: query description: 'Enable/Disable auto filters feature in search. Default: false' schema: type: boolean custom_results: name: custom_results in: query description: 'Enable/Disable custom_results feature in search. Default: true' schema: type: boolean excluded_results: name: excluded_results in: query description: 'Enable/Disable excluded items feature in the search. Default: true' schema: type: boolean exclude: name: exclude in: query description: > Exclusive parameters are negative filters. Doofinder expects the exclude parameters grouped like this: `exclude: { color: ['blue', 'red'], size: ['M', 'S'], price: { gte: 4.36, lt: 99 } }` For the range filters it can be used the following: - gte: Greater than or equal - lte: Less than or equal - gt: Greater than - lt: Less than Writing that down in request parameters language is: `exclude[color][]=blue&exclude[color][]=red&exclude[size]=M&exclude[size]=S&exclude[price][gte]=4.36&exclude[price][lt]=99` Note that [ and ] characters should be escaped (%5B and %5D) in all exclude cases. schema: type: string facets: name: facets in: query schema: type: object description: > Aggregates fields values in a facet, you could use a term facet or range facet. Read [facets configuration](https://support.doofinder.com/search/layer-settings/filters-configuration) for more deep info about facets. The type of the facet (term or range) will be determined automatically. Parameters: * __field__*: That is the field name that you want to aggregate results. * size: The number of results to return in each field. Only applicable to facet terms. Maximum: 50 by default to help maintain the speed of the search function. If you need more, please contact Doofinder support. * type: The facet type. Indicates the type of the facet, one of `term` or `range`. will return an error if the facet type is not correct. *required parameter Example request returning the `brand` term facet and the `best_facet` range facet: `facets[0][field]=brand&facets[0][size]=10&facets[1][field]=best_price`. filter: name: filter in: query description: > Filter parameters for items. Doofinder expects the filter parameters grouped like this: `filter: { color: ['blue', 'red'], size: ['M', 'S'], price: { gte: 4.36, lt: 99 } }` Range filters can be used as follow: - gte: Greater than or equal - lte: Less than or equal - gt: Greater than - lt: Less than Writing that down in request parameters language: `filter[color][]=blue&filter[color][]=red&filter[size][]=M&filter[size][]=S&filter[price][gte]=4.36&filter[price][lt]=99` Note that [ and ] characters should be escaped (%5B and %5D) in all filter cases. schema: type: string filter_execution: name: filter_execution in: query description: > Filters are applied with "and" boolean logic than means that all filters conditions should be met. If you want to apply any of the filters conditions, you can change it to "or". schema: type: string enum: - and - or grouping: name: grouping in: query description: > Enable/Disable the grouping of variants as single items. If not given, it's taken from the configuration set in the admin. schema: type: boolean with_variants: name: with_variants in: query description: > When provided and grouping is active, each hit includes a `df_variants` array containing all documents that share the same `df_grouping_id`, including the root (collapsed) document itself. The value is a list of document field names to include in each variant hit (e.g. `with_variants[]=visual_variant`). If the list is empty or grouping is off, this parameter has no effect. schema: type: array items: type: string indices: name: indices in: query description: > Your search engine is composed by one or many Indices. With the `indices` parameter you can specify to search within one specific Index. If this parameter is not provided, the search will work with all Indices. For instance, if you want to search within the "product" Index you should use the following query: `indices[]=product` In case you want to search within multiple Indices, the query will be: `indices[]=product&indices[]=page` The order of the values do not affect the results order. Note that `[` and `]` characters should be escaped (`%5B` and `%5D`) in all cases. schema: type: array items: type: string example: indices[]: product page: name: page in: query description: page number of the results to return. schema: type: integer query: name: query in: query description: >- The search term. It must be escaped and it cannot be longer than 200 characters or 10 words. schema: type: string query_name: name: query_name in: query description: > This parameter is used to run a specific query type; normally search service uses the best query for the search being made. The possible values for the `query_name` parameter are: * `match_and`: Doofinder will return results that contain all the search terms. * `match_or`: Doofinder will return results that contain any of the search terms. Of course, results that contain all the terms are scored better. * `fuzzy`: Doofinder will try to apply some «fuzzy logic» to determine whether a result, even if it’s not an exact match, is «close enough» to the search terms. schema: type: string enum: - match_and - match_or - fuzzy rpp: name: rpp in: query description: | Results per page. how many results per page to return. Limits are rpp <= 100 and rpp * page < 1000. schema: type: integer session_id_query: name: session_id in: query description: The current session ID, must be unique for each user. schema: $ref: '#/components/schemas/session_id' user_id_query: name: user_id in: query description: Identifies the user, must be unique for each user. schema: $ref: '#/components/schemas/user_id' stats: name: stats in: query description: 'Enable/Disable this search in stats reports. Default: true' schema: type: boolean skip_auto_filters: name: skip_auto_filters in: query description: A list of fields to be skipped from auto_filters feature. schema: type: array items: type: string skip_top_facet: name: skip_top_facet in: query description: A list of fields to be skipped from top_facet feature. schema: type: array items: type: string sort: name: sort in: query description: > Sorted results by certain fields. Doofinder expects sort parameters like this: `sort: [{"price": "asc"}, {"brand": "desc"}]` Writing that down in request parameters language is: `sort[0][price]=asc&sort[1][brand]=desc` Note that [ and ] characters should be escaped (%5B and %5D) in all filter cases. schema: type: string title_facet: name: title_facet in: query description: 'Enable/Disable title_facet feature. Default: false' schema: type: boolean top_facet: name: top_facet in: query description: 'Enable/Disable top_facet feature. Default: false' schema: type: boolean schemas: SearchResponse: title: Search Response description: | Search response. Some fields can not be included in the request if they have not data. type: object properties: banner: $ref: '#/components/schemas/BannerResponse' count: description: | Total number of items found in the search engine for the searched term. type: integer custom_results_id: type: integer description: | Id of applied custom results. This field will not be included if none of the custom results apply. dynamic_boosting_rule_id: type: integer description: | Id of applied dynamic boosting rule. This field will not be included if none of the dynamic boosting rules apply. facets: description: >- Information about different groupings that can be made for certain fields in the search results. items: oneOf: - $ref: '#/components/schemas/TermFacetResponse' - $ref: '#/components/schemas/RangeFacetResponse' type: array query_name: type: string description: >- In order to get the best possible results, Doofinder tries several types of querying. This is the type of the query Doofinder made to obtain these results. results: items: $ref: '#/components/schemas/Item' type: array total: type: integer description: Total number of items that can be fetched. example: custom_results_id: 5 facets: - brand: terms: items: - name: Adidas count: 5 - name: Nike count: 3 selected: [] query_name: fuzzy results: - description: The best product description ever dfid: 1234567890abcdef1234567890abcdef@product@1234567890abcdef id: my_id image_url: http://www.example.com/images/alt_product_image.jpg title: My item url: http://www.example.com/alt_product_description.htm total: 1 ErrorResponse: type: object description: Standard error response returned on all non-200 outcomes. properties: error: type: string description: Human-readable error message. required: - error session_id: type: string description: Identifier of search session maxLength: 32 user_id: type: string description: Identifier of user maxLength: 36 BannerResponse: title: Banner Response description: Banner response for a query search. type: object properties: blank: description: Display the banner link in a new window. type: boolean html_code: description: Html code to be used as banner instead of an image. type: string id: description: Banner identification. type: integer image: description: Image URL used as banner. type: string link: description: URL to be redirected when click over banner. type: string mobile_image: description: Image URL used as banner for mobile devices. type: string TermFacetResponse: title: Term Facet Response description: Facet terms search response. Used to aggregate a field by their values. type: object properties: key: description: Name of the aggregated field. type: string terms: type: object description: Facet terms list properties: items: type: array items: type: object properties: count: description: Number of elements type: integer name: description: Name of the term type: string selected: description: Items that are selected as part of a filter. type: array items: type: object properties: count: description: Number of elements type: integer name: description: Name of the term type: string RangeFacetResponse: title: Range Facet Response description: | Facet range search response. Used to return the min and max values for the aggregated field. type: object properties: key: description: Name of the aggregated field. type: string range: type: object properties: from: description: Selected start point of the range. type: number max: description: Maximum value of the field. type: number min: description: Minimum value of the field. type: number to: description: Selected end point of the range. type: number Item: title: Item description: A searchable object. Items are the objects that form the search results. type: object properties: description: type: string description: Item description. dfid: type: string description: >- Doofinder result doofinder id. It comes in every Doofinder results for every item. id: type: string description: Unique identification of an indexed item. image_url: type: string description: Item image url. title: type: string description: Item title. url: type: string description: Item url. required: - dfid - id - title example: description: The best product description ever dfid: 1234567890abcdef1234567890abcdef@product@1234567890abcdef id: my_id image_url: http://www.example.com/images/alt_product_image.jpg title: My item url: http://www.example.com/alt_product_description.htm securitySchemes: api_token: type: apiKey description: | Doofinder API key. Pass it as: Authorization: Token name: Authorization in: header ````