In an e-commerce context, items (products) are often offered in several variations, such as different sizes, fits and/or colors. Constructor's item API allows customers to define all the variations available for each item, so that end users can choose to filter on size, fit and/or color.

A single variation is a fully qualified product. For example, if an item comes in 3 sizes and 4 colors, you can upload 12 variations of that item, 1 for each size/color combination. All information that is shared across variations of a single item should be uploaded at the item level. All variation-specific information must be uploaded at the variation level.

Items are not required to have variations - you'll only need to use them if that's how you represent your product catalog. In addition, within a single index or dataset some products may have variations, and others may not.

Examples of metadata that are usually at the product level are things like:

• brand
• construction
• department
• material

Examples of metadata that are usually at the variation level are:

• size
• color
• SKU
• price

In most cases, products are represented as unique "tiles" within a product listing page, where variations are typically presented as options within a given tile.

Variation matching

Variation search and matching works as "search within search."

Constructor's Search (as well as Browse and Autocomplete) first identifies all products that match a query - where a query encompasses a search term and zero or more filter selections - or a browse group id and zero or more filter selections.

Next, Constructor searches within each item (typically, a product) to identify all matching variations for the query in question.

Finally, Constructor identifies the best matching variation among those that match the query. First the algorithm will look for any variation with is_default attribute set to true, then will search for the best variation match based on NLP, ranking optimizations and variation suggested_score.

Results

Items are returned one-by-one, with the best matching variation's data "rolled up" at the top level for each returned item. Other matching variations are returned in an array on the item record. During request time, it is possible to specify what fields of variation to return and even perform an aggregation across all of an item variations by using the variations mapping request argument of the Search, Browse and Autocomplete endpoints.