Responses from API requests to the Search, Browse, Recommendations, Autocomplete and Image Search endpoints follow a similar data structure. This facilitates ease of integration: the view logic to render products can depend on the same data being available regardless of the endpoint that a request was sent to.

Autocomplete is able to return results from multiple sections, however the Products section returns data in the same format as defined under response.results below. For more information about the response structure from Autocomplete, please refer to this resource.

Constructor's API returns JSON responses, including both data on what was requested and the response to the query.

In the absence of a section parameter, Constructor generally defaults to providing results only for the Products section of a given index, however this may be configured per index.

request

The request property reflects and summarizes the query parameters that were understood and processed by the API. It "echoes" the original request parameters, providing a clear and concise representation of what the API recognized and acted upon. This includes details such as the search term, pagination, sorting preferences, and any filters applied.

🚧

Caution

The request property and any nested descendants is intended for debugging and development purposes only. It should not be used in production code as it may be subject to change.

Values with a default (for example, page, num_results_per_page, section) will always be returned. Otherwise, only the parameters sent in the request will be returned.

For privacy reasons, certain parameters like API keys and user identifiers are intentionally omitted from the request object in the response.

• page: indicates the current page number of the results being viewed.
• num_results_per_page: specifies how many results are returned per page.
• term: the search term or query input. This will be blank for Browse requests.
• section: identifies the section of the index queried - usually defaulting to "Products."
• sort_by: the sort method applied (for example, "price").
• sort_order: the direction of sort - "ascending" or "descending."
• filters: lists any filters applied to narrow down the result set, such as product attributes or categories.
• filter_match_types: describes how filters are matched (for example, exact match, any match).
• browse_filter_name: indicates the specific browse filter name (key) supplied. This property will not be returned for product requests other than Browse.
• browse_filter_value: indicates the specific browse filter value supplied. This property will not be returned for product requests other than Browse.
• fmt_options: contains formatting option information such as groups_max_depth and groups_start, which control the depth and starting point of group information included in the response.
• features: indicates the state of various features that affect how results are generated and personalized (value of the map is boolean, true means feature is enabled).
• feature_variants: indicates the version (variant) of various features that affect how results are generated and personalized (value of the map is null if default feature behavior is applied, and string with a variant name otherwise).
• variations_map: includes detail of any variations mapping applied to the request.
• us: an array of strings clarifying user segments applied to the request.

The inclusion of this property in the response helps in debugging, verifying that the service correctly interpreted the request and ensuring that the response corresponds accurately to the intended query.

response

The response property encapsulates the main payload of the response, containing detailed information about the results. This property is structured to provide a comprehensive overview of the data retrieved by the request, including but not limited to, the results themselves, facets, groups, sort options, and additional metadata. Here's a breakdown of the key components typically found within the response property:

result_sources

The result_sources property provides a summary of the origins of results returned.

It typically contains two main items: token_match and embeddings_match. Each of these items includes a count of results that came from their respective sources.

• token_match: represents the summary of results that were obtained by directly matching the keywords or tokens in the search query with the items in the database.
• embeddings_match: represents the summary of results that originated from cognitive embeddings, which means the results were found by understanding the context or meaning of the search query, rather than just matching keywords.

"result_sources": {
  "token_match": {
    "count": 123
  },
  "embeddings_match": {
    "count": 456
  }
}

This structure allows you to understand how the results were derived, giving insight into the effectiveness of keyword matching versus contextual understanding in producing product results.

features

The features property refers to specific functionalities or enhancements applied to the result set. These features are designed to improve the relevance, personalization, and overall user experience of the product discovery capabilities on a website. Each feature within the features array in the response is described by several fields:

• enabled: this field indicates whether the feature is currently active (true) or inactive (false). It allows you to quickly understand which enhancements are applied to the current set of results.
• feature_name: this is the technical name or identifier of the feature. It specifies the exact feature being referred to, such as auto_generated_refined_query_rules, manual_searchandizing, personalization, or query_items. This name is used internally to reference and manage the feature.
• display_name: this field provides a user-friendly name for the feature, intended to be more readable and understandable than the technical feature_name. It's designed to clearly convey the purpose or effect of the feature to users or administrators who may not be familiar with technical identifiers.
• variant: the variant field indicates if there are different versions or variations of the feature being applied. This can be useful for testing or for applying slightly different behaviors of the same feature under certain conditions. It displays the variant of the feature if any variants exist.

"features": [
  {
    "display_name": "Affinity Engine",
    "enabled": true,
    "feature_name": "auto_generated_refined_query_rules",
    "variant": null
  },
  {
    "display_name": "Searchandizing",
    "enabled": true,
    "feature_name": "manual_searchandizing",
    "variant": null
  },
  {
    "display_name": "Personalization",
    "enabled": true,
    "feature_name": "personalization",
    "variant": null
  },
  {
    "display_name": "Learn To Rank",
    "enabled": true,
    "feature_name": "query_items",
    "variant": null
  }
]

These features collectively contribute to the customization and optimization of search and browse experiences, leveraging Constructor's capabilities such as the Affinity Engine, Searchandising, Personalization, and Learn To Rank. By adjusting these features, you can fine-tune how products, categories, and other content are presented to users based on their search queries or browsing behavior.

facets

The facets property is a structured representation of the filters that can be applied to narrow down product discovery results. These facets are typically used to provide users with a way to refine their search or browse queries based on common product attributes such as brand, price, rating, or any other custom-defined criteria relevant to the catalog.

• name: this is the internal name or identifier for the facet. It is used in the API requests to specify which facet to filter by (utilizing the filters parameter). This name matches what is supplied in the customer product catalog.
• display_name: this is the human-readable name for the facet, intended for display purposes in user interfaces. This can be configured through facet configuration.
• type: indicates the type of facet, either single, multiple or range. If a facet is of type single, then only one of the options may be selected (typically displayed as a radio button). If the type is multiple, then multiple options may be selected (typically displayed as checkboxes). If the type is range, then no options are provided. Instead a min and max value is provided to specify the range of values that can be sent in filters.
• status: object containing min and max values. Only provided at the facet field level for facets of type range. Specifies the currently selected range. If no range is currently selected, status will be an empty object ({}).
• hidden: a boolean value indicating whether the facet is hidden from end users. Hidden facets can be used for administrative purposes or for features not intended to be directly manipulated by the user.
• data: an object containing custom data associated with this facet. An empty object ({}) is returned if no data is currently associated with this facet. For assistance associating custom data with your facets, please reach out to your integration engineering contact.
• options: the list of possible facet values matching this query. Only provided if type is single or multiple. By default, facet options are sorted by relevance. To configure the sort order of your facet options, please reach out to your integration engineering contact. Number of options is limited, by default, to 500. The limit can be adjusted via facet configuration API.

Facet option fields

• value: the value that should be passed in filters to select this option. For example, filters[name]=value.
• display_name: the human-readable name for the option, intended for display purposes.
• data: an object containing custom data associated with this facet. An empty object ({}) is returned if no data is currently associated with this facet. For assistance associating custom data with your facets, please reach out to your integration engineering contact.
• status: indicates the selection status of the facet option, such as selected for options that are currently applied as filters.
• count: the number of items or results that match this facet option.

"facets": [
  {
    "name": "Brand",
    "display_name": "Brand",
    "type": "multiple",
    "options": [
      {
        "value": "Natural Balance",
        "display_name": "Natural Balance",
        "count": 8
      },
      {
        "value": "WholeHearted",
        "display_name": "WholeHearted",
        "count": 10
      }
    ]
  }
]

The facets property is essential for building dynamic filtering interfaces, allowing users to easily refine results based on specific criteria. It provides a rich set of metadata about the available filters, their values, and the number of results associated with each, enabling a more interactive and user-friendly experience.

collection

This property is only available in responses from Browse when requesting data for a Collection.

The collection property within browse responses is an object that provides information when a Collection-specific request is made (for example, /browse/collection_id/<collection_id>). It contains several fields that describe the collection, including its identifier, display name, and custom metadata.

• collection_id: identifier of the browsed collection. It is a unique string that represents the specific collection being queried.
• display_name: the human-readable name of the collection. It is a string that can be used directly within the UI to represent the collection to website users.
• data: a JSON object containing custom metadata attached to the collection. The structure of this object can vary depending on the specific data associated with the collection.

"collection": {
  "collection_id": "summer_collection",
  "display_name": "Summer Collection",
  "data": {
    "season": "Summer",
    "year": 2023,
    "theme": "Beach"
  }
}

In summary, the collection property encapsulates key details about a collection. This allows clients of the API to understand which collection the response pertains to and display relevant information about it alongside the results.

groups

The groups property provides a flat or hierarchical structure of groups (commonly known as categories) associated with the items in the result set. This structure helps in understanding the classification of items and can be used to refine or navigate through the search or browse results more effectively.

When an index has a flat group hierarchy, the groups property returns a flat array of groups. Each group in this array has no children, and its parents array is empty. This structure is straightforward and indicates that there are no sub-categories within these groups.

For indexes with hierarchical group structures, the groups property returns a nested list of groups. Each group can have children, indicating sub-categories or sub-groups. The top-level groups have their parents array empty, while sub-groups have their parents array filled with the group_id of their parent categories.

• display_name: the name of the group as it should be presented to users.
• group_id: a unique identifier for the group. It can consist of any ASCII characters.
• children: an array of groups that are children of the group, indicating a hierarchical structure. This is empty if there are no sub-groups.
• count: the number of item results within the group that match the search or browse request. This field is not present when the group is listed in the parents array. The count is the sum of the counts of its children.
• parents: an array containing the group_id of any parent groups. This is empty for top-level categories.

"groups": [
  {
    "display_name": "Pet Supplies",
    "group_id": "pet-supplies",
    "children": [
      {
        "display_name": "Dog Food",
        "group_id": "dog-food",
        "children": [
          {
            "display_name": "Dry Dog Food",
            "group_id": "dry-dog-food",
            "children": [],
            "count": 150
          },
          {
            "display_name": "Wet Dog Food",
            "group_id": "wet-dog-food",
            "children": [],
            "count": 100
          }
        ],
        "count": 250
      },
      {
        "display_name": "Cat Food",
        "group_id": "cat-food",
        "children": [],
        "count": 200
      }
    ],
    "count": 450
  }
]

The groups property is a versatile tool for categorizing and organizing search and browse results, enhancing the user's ability to navigate and understand the structure of the items returned by the API. It can be used to build navigation menus or filters, allowing users to drill down into specific categories or sub-categories based on their interests.

sort_options

The sort_options property in API responses from search and browse requests is an array that contains objects representing the different ways results can be sorted. Each object within the sort_options array specifies a particular sorting method available. These objects include several fields that define the sorting behavior and presentation:

• sort_by: indicates the criterion used for sorting, such as "price" or "brand."
• sort_order: specifies the direction in which items should be sorted. Either "ascending" or "descending."
• display_name: a human readable name for the sort option, intended for display in the UI. For example, "Price, High to Low" or "Brand name, A-Z."
• status: indicates whether this sort option is currently selected. For example, a sort option with a "selected" status is the one currently being applied to results.

"sort_options": [
  {
    "sort_by": "price",
    "sort_order": "descending",
    "display_name": "Price, High to Low",
    "status": ""
  },
  {
    "sort_by": "price",
    "sort_order": "ascending",
    "display_name": "Price, Low to High",
    "status": ""
  }
]

By default, results are sorted by attractiveness (relevance), but users may choose to sort them by other properties depending on the available sort_options. This feature allows for a more tailored and user-friendly search or browse experience, enabling users to easily find what they're looking for by sorting the results according to their preferences.

refined_content

The refined_content property is designed to attach custom, arbitrary JSON data to specific queries based on predefined rules. This feature allows for the inclusion of additional, structured data that can be tailored to enhance the response for particular search or browse queries.

"refined_content": [
  {
    "data": {
      // arbitrary JSON
    }
  }
],

There are no restrictions on the attached data with the exception that the maximum size is 200KB. Several rules can be attached to the same query - refined_content is an array of objects where each item is a returned match for the specified query.

results

The results property is an array that contains the items (or products) that match the query or browse criteria specified by the user. Each item within the results array is represented as an object with various fields providing detailed information about the item. These fields can include, but are not limited to, the item's name, ID, image URL, URL to the item's page, price, brand, and any other relevant data such as facets, groups, and variations.

Here's a breakdown of the key components typically found within each item in the results array:

Default data

• data: contains the core details of the item, including attributes like groups (categories the item belongs to), facets (key-value pairs that describe the item's characteristics, such as brand or price), and variations (different versions of the item, such as color or size variations).
• is_slotted: indicates whether the item has been placed in its position as a result of searchandising (manual adjustments to search or browse results).
• labels: contains miscellaneous properties of the item for the specific search or browse request, such as whether the item is sponsored. The is_sponsored property specifies if the slotted product is advertised or promoted.
• matched_terms: lists all terms within the item matching the user's query (regardless of whether they are misspelled).
• value: represents the name or primary value of the item, typically item_name.

Additional data

• id: The unique identifier for the item within the index.
• image_url: a URL that references the item's image.
• url: the URL of the item's page where more details can be found or the item can be purchased.
• variation_id: the ID of the selected (best matching) variation - sometimes referred to as the "face out" variation. All metadata of the matching variation will be merged into the item's data object.
• variations: a list of variations for the item, providing options that the user may choose from. Most commonly these are different colors or sizes of an item.

If the variations_map request argument is passed, the variations field is removed from the response. Instead, a variations_map field is added which contains only the requested information as documented in Variations mapping.

"results": [
  {
    "data": {
      "id": "123",
      "value": "Natural Balance Dog Food",
      "image_url": "https://www.constructor.io/images/doge.jpg",
      "url": "https://www.constructor.io/pages/dog",
      "facets": {
        "Brand": "Natural Balance",
        "Price": 17.90,
      },
      "groups": [
        {
          "display_name": "dry food",
          "group_id": "dry-food",
          "path": "/pet-food/dog-food/"
        }
      ],
      "variations": [
        {
          "data": {
            "id": "4321",
            "facets": {
              "Color": "Black"
            },
            "image_url": "https://www.constructor.io/images/black_doge.jpg",
            "url": "https://www.constructor.io/pages/dog_black"
          }
        }
      ]
    },
    "is_slotted": true,
    "labels": {
      "is_sponsored": true
    },
    "matched_terms": ["dog"]
  }
],

The results property is essential for displaying search or browse results to users, allowing them to see the items that match their criteria and select items for further details or purchase.

redirect

This property is only available in responses from Search when a redirect rule matches the given query.

The redirect property in API responses from search requests is an object that contains information about a redirect action that should be taken based on the search query. This property is used when a search query matches any Redirect rules that have been previously configured.

• data: an object that contains the target URL and any metadata defined in the redirect rule. The url attribute within this object specifies the destination where the user should be redirected.
• matched_terms: a list of strings representing all the terms in the redirect match definition that matched the search query. This shows which keywords triggered the redirect.
• matched_user_segments: a list of strings representing all the user segments in the redirect match definition that matched the search query. This indicates if the redirect was also conditioned on specific user segments.

"redirect": {
  "data": {
    "url": "https://example.com/special-offer"
  },
  "matched_terms": [
    "special offer",
    "discount"
  ],
  "matched_user_segments": [
    "returning_customer",
    "high_spender"
  ]
}

The purpose of this property is to guide the user directly to a specific URL or page, rather than showing them search results. This can be particularly useful for guiding users to a dedicated landing page or a specific product page when certain keywords are searched.

total_num_results

The total_num_results property represents the total number of results found for the given request. This property is an integer value that indicates the overall count of items that match the search or browse criteria, before any pagination is applied.

"total_num_results": 123

This property provides a summary of how many items are available or relevant to the user's request, allowing for an understanding of the size of the result set. This can be particularly useful for implementing pagination or showing users how many total items are available in relation to their search or browse query.

result_id

The result_id attribute serves as a unique identifier for each request.