--- title: "Retrieve by image" method: POST path: "/v2/image_search" tags: ["Image Search results"] --- # Retrieve by image `POST /v2/image_search` ## Request - Base URL: `https://image-search.cnstrc.com` - URL: `https://image-search.cnstrc.com/v2/image_search` - Auth: none required Retrieve AI optimized search results for products (or optionally other sections) by image with optional multi-item detection (segmentation) support. ## Query parameters - `key` string, required: The key of the index to use. - `section` string: The section of the index to use. - `search_crop_type` 'bbox' | 'segment': How to crop detected segments for visual search. Only relevant when `use_segmentation` is `true`. - `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 - `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_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. - `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. - `use_segmentation` boolean: Whether to detect and individually search multiple objects in the image. When `true`, the image is split into detected objects and each is searched separately; results are merged. - `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. - `return_segments` boolean: Whether to include per-segment metadata in the response. Only applicable when `use_segmentation` is `true`. - `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. ## Request body `application/octet-stream` - string, binary ## Response `200` OK - ImageSearchPostResponseV2 - `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: A unique identifier for this search request, used for analytics and behavioral tracking. - `response` object, required - `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 - RangeFacet - `type` 'range', required: If a facet is of type `range`, then no facet options are provided. Instead a `min` and `max` value is provided to specify the range of values that can be sent in `filters`. - `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. - `status` RangeFacetStatus - `min` union: Selected minimum value of the range facet. - … - `max` union: Selected maximum value of the range facet. - … - `min` union: Minimum facet value of the result items. - number - integer - '-inf' | '+inf' | 'inf' - `max` union: Maximum facet value of the result items. - number - integer - '-inf' | '+inf' | 'inf' - 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. - `display_name` string, required: The name of the facet option as it is displayed to end users. Note that in `filters` parameter you need to use not `display_name` but `name`. - `status` 'selected' | '', required: `selected` if this option is selected in the current search request, empty string otherwise. - `value` string, required: The value that should be passed in `filters` to select this option: `filters[name]=value` - `count` integer, required: Number of items in the current search that match this option. - `data` object: Object containing custom data associated with this facet option. An empty object (`{}`) if no data is currently associated with this option. - `range` union[]: Array containing 2 values: the parsed `min` & `max` values that are represented by this facet option. The field exists only for options of a facet with type `range` or `single` if it is configured specially. - … - HierarchicalFacet - `type` 'hierarchical', required - `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` HierarchicalFacetOption[]: An array of possible facet values matching this search. By default, facet options are sorted by relevance. - `display_name` string, required: The name of the facet option as it is displayed to end users. Note that in `filters` parameter you need to use not `display_name` but `name`. - `status` 'selected' | '', required: `selected` if this option is selected in the current search request, empty string otherwise. - `value` string, required: The value that should be passed in `filters` to select this option: `filters[name]=value` - `count` integer, required: Number of items in the current search that match this option. - `data` object: Object containing custom data associated with this facet option. An empty object (`{}`) if no data is currently associated with this option. - `range` union[]: Array containing 2 values: the parsed `min` & `max` values that are represented by this facet option. The field exists only for options of a facet with type `range` or `single` if it is configured specially. - … - `options` object[]: An array of possible facet values matching this search. By default, facet options are sorted by relevance. The field exists only for options of a facet with type `hierarchical`. - … - `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` Result[], 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 - union - … - `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 - `id` string, required: The ID of the group. - `display_name` string: The name of the group as it is displayed to end users. - `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. - `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 - … - `value` string, required - `variations_map` union: Variations data in the format requested by `variations_map` query parameter. - unknown[] - unknown - object - `variation_slice` object: If variation slicing is enabled, this represents the variation slice of the item. - `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, required: The name of the sortable field as it is displayed to end users. - `status` 'selected' | '', required: `selected` if this option is selected in the current search request, empty string otherwise. - `sort_by` string, required: The attribute to sort by, and the value of the sort_by query parameter in the search request. - `sort_order` 'ascending' | 'descending', required - `hidden` boolean, required: `true` if this sort option is hidden, `false` otherwise. - `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. - `collection` Collection - `id` string, required: The ID of the browsed collection. - `display_name` string: The name of the collection as you'd present it to users. - `data` object: Object containing custom data associated with this collection. - `start_time` string, date-time: The start time of the collection if it is time-bound. - `end_time` string, date-time: The end time of the collection if it is time-bound. - `active_overriding_collection` Collection (recursive) - `browse_url` string: The browse results URL. - `segmentation_used` boolean, required: Whether segmentation was actually used to produce results. `false` when `use_segmentation` was not requested or when segmentation failed and the system fell back to whole-image search. - `whole_image_search_fallback` boolean, required: Whether the service fell back to whole-image search after segmentation was requested but failed to produce usable results. Always `false` when `use_segmentation` was not requested. - `segments` Segment[]: Per-segment search results. Present when `use_segmentation` is `true` and `return_segments` is `true`. - `id` integer, required: Zero-based index of this segment in the detection list. - `x1` integer, required: Left x coordinate of the bounding box. - `y1` integer, required: Top y coordinate of the bounding box. - `x2` integer, required: Right x coordinate of the bounding box. - `y2` integer, required: Bottom y coordinate of the bounding box. - `class_id` integer, required: Numeric class identifier from the segmentation model. - `class_name` string, required: Human-readable class name (e.g. 'top', 'pants'). - `confidence` number, float, required: Detection confidence score in the range [0.0, 1.0], where 1.0 is maximum confidence. - `centroid_x` integer, required: X coordinate of the segment interior point. - `centroid_y` integer, required: Y coordinate of the segment interior point. - `neighbours` object[], required: Nearest-neighbour search results for this segment. - `id` string, required: Product ID. - `distance` number, float, required: Distance from the segment embedding to the product embedding. - `data` object: Catalog data for this product from the Browse API. Same shape as response.results[].data. ## Other responses - `400`: Bad Request --- [API](https://skmtc.dev/constructor/apis/image-search.md) - [All operations](https://skmtc.dev/constructor/apis/image-search/llms.txt) - [OpenAPI document](https://skmtc.dev/constructor/apis/image-search/revisions/eeb550f4ee49?raw)