--- title: "Retrieve by query" method: GET path: "/v1/search/{search_query}" tags: ["Search results"] --- # Retrieve by query `GET /v1/search/{search_query}` Retrieve AI optimized search results for products (or optionally other sections) by search query. ## Path parameters - `search_query` string, path, required ## Query parameters - `key` string, required — The key of the index to use. - `section` string — The section of the index to use. Defaults to `Products`. - `filters` Filters - `filter_match_types` object — An object specifying whether results must match `all`, `any` or `none` of a given filter when multiple options of the same facet (e.g: color: yellow & blue) are selected. - `pre_filter_expression` union - object - string, json - `num_results_per_page` integer — The number of results per page to return. - `page` integer — The page of results to return. - `offset` integer — The number of results to skip from the beginning. Cannot be used together with `page`. - `sort_by` string — The method to sort results by. The default value `relevance` sorts by Constructor's attractiveness & personalization algorithms and is reserved. Alternative sort criteria can be configured using the [Sort options API](/reference/v1-sort-options-create-or-replace-sort-options). - `sort_order` 'ascending' | 'descending' - `now` string, date-time — A date time representing the current moment in time when applying filtering by product age. Used to emulate "past/future" requests. Requires authentication. - `variations_map` VariationsMap - `filter_by` union - VariationsMapRange - `field` string, required — Path to a metadata field (dot-separated) - `range` union[], required — This filter matches items where the specified field is within the specified range (min and max). The values are inclusive. Use "inf" for an unbounded upper limit or "-inf" for an unbounded lower limit. - union - 'inf' | '-inf' - integer - number - VariationsMapSingleFilter - `field` string, required — Path to a metadata field (dot-separated) - `value` union, required — The value of this field to filter by - boolean - integer - number - string - VariationsMapOr - `or_` array[], required - unknown[] - unknown - VariationsMapAnd - `and_` array[], required - unknown[] - unknown - VariationsMapNot - `not_` object, required - `group_by` VariationsMapGrouping[] — An array of fields that should be used to group variations. Variations which share the value of all fields specified here will all fall under one group - `name` string, required - `field` string, required - `values` object, required — A set of aggregations that should be applied to each variation group. The object keys specify the name of the field under which each aggregated value will be returned in the response - `dtype` 'array' | 'object', required — The expected data type of the variations_map objects in the response - `fmt_options` FmtOptions — Options to format different aspects of the response. - `fields` string[] — A list of specific item fields to return in the response. Allows the request to control which fields are returned. - `show_hidden_fields` boolean — A flag to return all `hidden` fields in the response. - `hidden_fields` string[] — A list of specific hidden fields to return in the response. Unlike `show_hidden_fields` this parameter allows the request to control which `hidden` fields are returned. Used to return item fields for a particular store or user segment. - `variations_return_type` 'default' | 'all' | 'matched' - `groups_max_depth` integer — The maximum depth of the group hierarchy in the response. - `groups_start` string — A flag to specify the start of the group hierarchy returned in the response. `current` returns groups starting from the currently selected one. `top` returns groups starting from the root category in the hierarchy. `group_id:{id}`, returns the whole tree starting from group with the provided id. - `groups_path` string[] — Specifies the path from the root group to the current group you are browsing. It is used to construct the parents path in the `response.groups` for the current browsed group. Max depth allowed for the path is 10. This option is only accepted when `groups_start` is 'current'. - `groups_sort_by` 'relevance' | 'value' | 'num_matches' - `groups_sort_order` 'ascending' | 'descending' - `show_hidden_facets` boolean — A flag to return all facets configured as `hidden` in `response.facets`. - `hidden_facets` string[] — A list of specific hidden facets to return in the response. Unlike `show_hidden_facets` this parameter allows the request to control which hidden facets are returned. Used to return facets for a particular store or user segment. - `show_hidden_facet_options` boolean — A flag to return all `hidden` facets options in the response. - `show_protected_facets` boolean — A flag to return all `protected` facets in the response. Requires authentication. - `facet_options` object — A list of specific facet options per facet to return in the response. This parameter accepts up to 5 facets and works only with facets of type `multiple`. Invalid facet options will be ignored. Used to return facet options for a particular facet like store or user segment. - `facet_groups_limit` integer — The maximum limit of the facet groups returned in the response. - `show_hidden_sort_options` boolean — A flag to return all sort options configured as `hidden` in `response.sort_options`. - `hidden_sort_options` string[] — A list of `sort_by` fields whose hidden sort options should be included in the response. Unlike `show_hidden_sort_options` this parameter allows you to specify exactly which hidden sort options are returned. - `qs` string, json — A JSON-encoded query string. Any query parameters listed for this endpoint can be serialized into a JSON string and parsed thru the `qs` param. - `origin_referrer` string — The url or app location where the request originated. - `c` string — The ID of the client and version that the request is coming from, such as `cio-js-2.90`. - `us` string[] — A customer defined context (such as `vip-club-member`) used to evaluate redirect or refined tag rules. Pass multiple segments by passing multiple `us` arguments. - `ui` string — A customer generated anonymized identifier for a user on a customer website. It should only be sent for logged in customers and helps Constructor to tie multiple client and session IDs together to form a behavioral data profile across devices. - `s` integer — An integer representing the users session number (starting with `1`), incremented after a 30 minute period of inactivity. - `i` string — A globally unique identifier for the user browser (or mobile application instance) making the request. - `lang` 'ar' | 'ca' | 'cs' | 'da' | 'de' | 'el' | 'en' | 'es' | 'et' | 'eu' | 'fi' | 'fr' | 'ga' | 'he' | 'hi' | 'hu' | 'hy' | 'id' | 'it' | 'lt' | 'lv' | 'ne' | 'nl' | 'no' | 'pl' | 'pt' | 'ro' | 'ru' | 'sk' | 'sr' | 'sv' | 'ta' | 'tr' | 'yi' — A specification of the user query language. When provided, this parameter enables language-specific processing such as stemming to improve relevance and recall. ## Response `200` OK - SearchGetResponse - `request` object, required — The request arguments how they were interpreted by the API. This field is of arbitrary type, ie it doesn't have a guaranteed schema, and data from it shouldn't be used programmatically, it is for debugging purposes only. - `result_id` string - `response` union, required - SearchResponse - `result_sources` ResultSources, required - `token_match` ResultSourceValue, required - `count` integer, required — Number of results returned from their respective sources - `embeddings_match` ResultSourceValue, required - `count` integer, required — Number of results returned from their respective sources - `facets` union[], required — An array of facets associated with the items returned by the search query. - union - union - BoundariesRangeFacet - … - OptionsRangeFacet - … - SingleOrMultipleFacet - `type` 'single' | 'multiple', required — If a facet is of type `single`, then only one of the options may be selected (e.g: display as radio button). If the type is `multiple`, then multiple options may be selected (e.g: display as checkboxes). - `name` string, required — The name of the facet. This should be passed in the filters parameter when a facet of this type is selected. `filters[name]=value` - `display_name` string, required — The name of the facet as it is displayed to end users. Note that in `filters` parameter you need to use not `display_name` but `name`. - `hidden` boolean, required — The boolean value saying whether facet is available for interaction. - `data` object, required — Object containing custom data associated with this facet. An empty object (`{}`) if no data is currently associated with this facet. - `options` FacetOption[] — An array of possible facet values matching this search. By default, facet options are sorted by relevance. Number of options is limited, by default, to 500. But the limit can be configured per [facet](/reference/v1-facets-create-facet) key. - … - HierarchicalFacet - `options` FacetOption[] — A list of facet option configurations to create and associate with this facet configuration. Default value is `[]` (empty list). - … - `name` string, required — The facet name used to refer to the facet in your catalog. Must be unique inside the section and key. - `type` 'hierarchical', required - `display_name` string — The name of the facet to present to end users. Default value is `null`, in which case the `name` will be presented. - `sort_order` 'relevance' | 'value' | 'num_matches' - `sort_descending` boolean — `true` if this facet group's options should be sorted in descending order, `false` to sort ascending. Default value is `true` if `sort_order` is `relevance` or `num_matches` and `false` for `value`. Setting `sort_order: relevance` will set `sort_descending: true` for `POST`, `PUT`, `PATCH` endpoints if `sort_descending` is not explicitly set in the request. - `range_type` 'static' - `range_format` 'boundaries' | 'options' - `range_inclusive` 'above' | 'below' - `range_limits` union[] — Defines the cut-off points for generating static range buckets. Expects list of sorted numbers (like `[10, 25, 40]`). Default value is `null` - … - `match_type` 'any' | 'all' | 'none' - `position` integer — Used to slot facet groups to fixed positions. Default value is `null`. - `hidden` boolean — Specifies whether the facet is hidden from users. Use this for facet data that you don't want shown to end users, but that isn't sensitive. - `protected` boolean — Specifies whether the facet is protected from users. Setting this to `true` will require authentication to view the facet. - `countable` boolean — Specifies whether counts for each facet option should be calculated and shown in the response. Setting this to `false` will skip counting these options, improving performance for facets with high cardinality. - `options_limit` integer — Maximum number of options of facet type `multiple` to return in search responses. If absent, the default limit is applied. - `data` object — Dictionary with any extra facet data. Default value is `{}` (empty dictionary). - `groups` Group[], required — An array of item groups and the number of results belonging to each group. - `group_id` string, required — The ID of the group. - `display_name` string — The name of the group as it is displayed to end users. - `count` integer, required — The number of results within this group. - `data` object — Object containing custom data associated with this group. - `children` object[], required — An array of groups that are 'children' of the group in question. - `parents` GroupBase[], required — An array of groups that are 'parents' of the group in question. - `group_id` string, required — The ID of the group. - `display_name` string — The name of the group as it is displayed to end users. - `results` SearchandizedResult[], required - `value` string, required — Name of the matched item or variation (if variations are defined). - `matched_terms` string[], required — All terms within the item matching the user's query (regardless of whether misspelled). - `data` ResultData, required - `id` string — The ID of this item as specified in the catalog. - `url` string — The URL where the item can be viewed or purchased. - `image_url` string — The item's image URL for display in results. - `variation_id` string — ID of the selected (best matching) variation. All metadata of the best matching variation will also be merged into the item's `data` object.Returned when [item variation](#) data is defined. - `facets` ResultFacet[] — The item's associated facets. - `name` string, required - `values` union[], required - … - `groups` ResultGroup[] — The item's associated categories. - `group_id` string, required — The ID of the group. - `display_name` string — The name of the group as it is displayed to end users. - `path` string, required — The path of `group_id`s above this group. `/great-grandparent/grandparent/parent/` - `path_list` Path[], required — An array of groups constituting the path. - … - `variations` ResultVariation[] — An array of this item's variations matching user's query. - `data` ResultData, required - `id` string — The ID of this item as specified in the catalog. - `url` string — The URL where the item can be viewed or purchased. - `image_url` string — The item's image URL for display in results. - `variation_id` string — ID of the selected (best matching) variation. All metadata of the best matching variation will also be merged into the item's `data` object.Returned when [item variation](#) data is defined. - `facets` ResultFacet[] — The item's associated facets. - … - `groups` ResultGroup[] — The item's associated categories. - … - `value` string, required - `variations_map` union — Variations data in the format requested by `variations_map` query parameter. - unknown[] - unknown - object - `is_slotted` boolean, required — `true` if the current product is slotted as a result of searchandizing. - `labels` object, required — A set of miscellaneous properties of this result. For example, it can indicate whether a slotted result is advertised or promoted. - `sort_options` SortOption[], required — Sort options configured for this index through the [Sort options API](https://docs.constructor.com/reference/v1-sort-options-create-or-replace-sort-options). It does not restrict the values accepted by `sort_by` or `sort_order`. Any sortable field can be used in ascending or descending order. Returns an empty array when no sort options are configured, in which case results default to sorting by relevance in descending order. - `display_name` string — The name of the sort option as it is displayed to end users. - `path_in_metadata` string, required — The path in the item's metadata to the field that results will be sorted according to. - `position` integer — The position of the sort option, used to provide sort options in a specific order. - `hidden` boolean — Indicates if a sort option is hidden. This can be marked at `sort_by` level. A hidden sort option will be ignored in response by default. - `sort_by` string, required — The name of the sort option. - `sort_order` 'ascending' | 'descending', required - `refined_content` object[], required — Arbitrary content attached to the search query via [content rule](#). Constructor doesn't enforce any restrictions on the attached data except for a size limit of 200kB, and just returns it as-is when there is a query match. There can be several rules attached to the same query, so the `refined_content` itself is an array of objects. - `total_num_results` integer, required — Total count of results within the section - `features` Feature[], required — State of features for Affinity Engine, Searchandizing, Personalization and Learn To Rank - `display_name` string, required — The name of the features as it is displayed to end users. - `enabled` boolean, required — Displays the enabled status of the feature. - `feature_name` string, required — The name of the feature. - `variant` FeatureVariant - `name` string, required — The name of the feature variant. - `display_name` string — The name of the feature variant as it is displayed to end users. - `related_searches` RelatedSearch[], required — An array of related queries. - `query` string, required — The related search query. - `related_browse_pages` RelatedBrowseEntity[], required — An array of related browse pages. - `filter_name` string, required — The name of the related browse filter. - `filter_value` string, required — The value of the related browse filter. - `display_name` string, required — The display name of the related browse filter. - `image_url` string, required — The thumbnail for the browse filter. - RedirectResponse - `redirect` Redirect, required - `matched_terms` string[] — An array of all the terms in the redirect match definition that matched the search query. - `matched_user_segments` string[] — An array of all the user segments in the redirect match definition that matched the search query. - `data` RedirectData, required - `url` string, required — Target URL of the redirect. ## Other responses - `400` — Validation Error --- [API](https://skmtc.dev/constructor/apis/autocomplete.md) · [All operations](https://skmtc.dev/constructor/apis/autocomplete/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/constructor/autocomplete/revisions/2d33330633b6/schema)