Product Search

Data integration

The Product Search API is designed to be ID-first to provide high performance. This means that the query result contains only Product IDs (together with matching Product Variant IDs when requested) by default, but not the entire resource. This design prefers lower response times over completeness of data, which can be achieved through additional methods as recommended in this section. To integrate the search results of this API with more product data, you have application-side as well as API-wise options.

With application-side caches

If possible, use application-side caches to store the IDs and SKUs returned with the search results together with the corresponding product data.

With Product Projection API

We recommend using the product GraphQL query with the returned Product IDs to retrieve the data you exactly require for your use case.

You can also use the Get ProductProjection by ID endpoint of the Product Projection API to fetch the entire product data of a matching Product.

With Product Projection parameters BETA

If the above retrieval and caching options are not feasible for your use case, the Product Search API also provides some built-in integration with the Product Projection API.

To retrieve the projected product data in an additional productProjection field in the ProductSearchResult, provide the productProjectionParameters field with the ProductSearchRequest.

Set this field to {} to get the full ProductProjection included in the ProductSearchResult, or add query parameters according to your needs, for example {"priceCurrency": "USD"}, to perform Product price selection on the returned ProductProjection.

This integration option calls the Product Projection API and enriches the search result with the data returned by the API call. Because of this additional API call, the search request takes longer to respond to than a request without the parameters.

Activation of the feature

The Product Search feature is not active for the Project by default. Before first use, you have to activate it by using the Change Product Search Indexing Enabled update action with mode: ProductsSearch on the Update Project endpoint.

{
  "action": "changeProductSearchIndexingEnabled",
  "enabled": true,
  "mode": "ProductsSearch"
}

As soon as the Product Search feature is activated for your Project, its Products get indexed, and the Search Products endpoint will become fully functional soon after.

Automatic deactivation

The Product Search feature will be deactivated for a Project automatically if there have been no calls against the Search Products endpoint for the duration of 30 consecutive days. The feature can be reactivated again as described above.

Representations

ProductSearchRequest

{
  "query": {
    "and": [
      {
        "fullText": {
          "field": "name",
          "language": "en",
          "value": "banana"
        }
      },
      {
        "filter": [
          {
            "exact": {
              "field": "variants.attributes.farming",
              "fieldType": "text",
              "value": "organic"
            }
          }
        ]
      }
    ]
  },
  "sort": [
    {
      "field": "name",
      "language": "en",
      "order": "desc"
    }
  ],
  "limit": 10,
  "offset": 0
}

ProductSearchProjectionParams BETA

ProductSearchFacetExpression

Refer to expression for distinct, ranges, or count facets.

ProductPagedSearchResponse

ProductSearchResult

ProductSearchMatchingVariants

ProductSearchMatchingVariantEntry

ProductSearchFacetResult

ProductSearchFacetResultCount

ProductSearchFacetResultBucket

ProductSearchFacetResultBucketEntry

Search Products

{
  "total": 148,
  "offset": 0,
  "limit": 10,
  "facets": [
    {
      "name": "countProducts",
      "buckets": [
        {
          "key": "white",
          "count": 37
        }
      ]
    },
    {
      "name": "countVariants",
      "buckets": [
        {
          "key": "white",
          "count": 301
        }
      ]
    }
  ],
  "results": [
    {
      "id": "8fde2af0-6a2f-4633-9ba4-83566f769a7f",
      "matchingVariants": {
        "allMatched": false,
        "matchedVariants": [
          {
            "id": 1,
            "sku": null
          }
        ]
      }
    }
  ]
}

Searchable Product fields

The following list contains the fields of the Product search index that can be used for the field property in query expressions. For standard fields on Products, the type of field determines which query expressions are supported for the field.

Query expressions are evaluated at the Product-level. A Product matches the query expression if the root-level Product field matches (for example, categories, key, slug), or if any Product Variant matches the variant-level criteria (for example, variants.attributes.*, variants.prices.*).

In case of a not compound expression, no Product Variant of a Product must match the nested query expression. For example, when searching for Products without the XYZ attribute, using the not.exists expression will only match if none of the Product Variants of a Product have the XYZ attribute set.

Attributes

The SearchFieldType of the Attribute determines in which query expressions you can use the Attribute specified by:

variants.attributes.<attribute-name>

To query for multiple values of the same field or for several Attributes in the same request, combine the query expressions with a compound expression.

Boolean fields

Use the following boolean type fields on Products in exact and exists query expressions.

Number and date fields

Use the following fields in exact, exists, and range query expressions. Data type indicates the type of field for the field.

Keyword fields

Use the following keyword type fields, containing unique IDs or keys, in exact, prefix, wildcard, and exists query expressions. To query for multiple values of the same field or for several fields in the same request, combine the query expressions with a compound expression.

Text and localized text fields

Use the following localizedText type fields in exact, fullText, prefix, wildcard, and exists query expressions.

Example query:

The following example demonstrates how to find Product Variants with a price of EUR 22.22:

{
  "query": {
    "and": [
      {
        "exact": {
          "field": "variants.prices.currencyCode",
          "value": "EUR"
        }
      },
      {
        "exact": {
          "field": "variants.prices.centAmount",
          "value": 2222
        }
      }
    ]
  }
}

Facets BETA

Facets give you statistical information about your data. It answers questions like "how many t-shirts of size XL are there?" or "how many TVs are there that cost between US$500 and $600?" The first question is answered by a distinct facet, and the second one by a ranges facet. Each facet has a name assigned to it, so it can be found in the ProductSearchFacetResult.

Distinct facets

The distinct facet counts occurrences of distinct values.

ProductSearchFacetDistinctExpression

ProductSearchFacetDistinctValue

Example:

The following example calculates facets for distinct values within an Attribute called size. The response shows there are 112 Products of size 43, 63 Products of size 44, and 34 Products of size 45.

{
  "facets": [
    {
      "distinct": {
        "name": "sizes",
        "field": "variants.attributes.size",
        "fieldType": "number",
        "limit": 50
      }
    }
  ]
}

{
  "facets": {
    "results": [
      {
        "name": "sizes",
        "buckets": [
          {
            "key": "43",
            "count": 112
          },
          {
            "key": "44",
            "count": 63
          },
          {
            "key": "45",
            "count": 34
          }
        ]
      }
    ]
  }
}

Ranges facets

The ranges facet counts Products that have values within a specified range. These values must be numeric or of type DateTime. You can specify ranges using from and to. Open ranges can be specified by omitting either the from or to values.

ProductSearchFacetRangesExpression

ProductSearchFacetRangesValue

ProductSearchFacetRangesFacetRange

Example:

The following example calculates the number of Products which have the Attribute screenDiagonal within a certain range. The response shows that there are 33 TVs with a screenDiagonal lower than 40, and 165 TVs with a screenDiagonal between 40 and 55.

{
  "facets": [
    {
      "ranges": {
        "name": "screenDiagonalRanges",
        "field": "variants.attributes.screenDiagonal",
        "fieldType": "number",
        "ranges": [
          {
            "to": 40
          },
          {
            "from": 40,
            "to": 55
          },
          {
            "from": 55
          }
        ]
      }
    }
  ]
}

{
  "facets": {
    "results": [
      {
        "name": "screenDiagonalRanges",
        "buckets": [
          {
            "key": "*-40",
            "count": 33
          },
          {
            "key": "40-55",
            "count": 165
          },
          {
            "key": "55-*",
            "count": 82
          }
        ]
      }
    ]
  }
}

You can rename the key values in the response by including them in ranges. The following example shows the ranges renamed to small, medium, and large.

{
  "facets": [
    {
      "ranges": {
        "name": "screenDiagonalRanges",
        "field": "variants.attributes.screenDiagonal",
        "fieldType": "number",
        "ranges": [
          {
            "key": "small",
            "to": 40
          },
          {
            "key": "medium",
            "from": 40,
            "to": 55
          },
          {
            "key": "large",
            "from": 55
          }
        ]
      }
    }
  ]
}

Count facets

The count facet counts the number of Products (or Product Variants).

ProductSearchFacetCountExpression

ProductSearchFacetCountValue

ProductSearchFacetCountLevelEnum

Example:

The following example request contains a count facet for the number of Products as well as one for the number of Product Variants. The example response shows the result of these count facets (200 Products and 1000 Product Variants).

{
  "facets": [
    {
      "count": {
        "name": "all-products"
      }
    },
    {
      "count": {
        "name": "all-variants",
        "level": "variants"
      }
    }
  ]
}

{
  "facets": {
    "results": [
      {
        "name": "all-products",
        "value": 200
      },
      {
        "name": "all-variants",
        "value": 1000
      }
    ]
  }
}

Operations on facets

You can modify facets with following operations to filter and sort them, for instance.

Selecting specific buckets key

Use includes to specify which bucket keys the facet results should include.

Example:

The following example counts the number of Products that have the Categories 53992aac-cbbf-4b97-bb-09142435e1ea and 344c8ceb-01ac-4d76-8f93-bbbc3d0edd5d assigned.

{
  "facets": [
    {
      "distinct": {
        "name": "categories",
        "field": "categories",
        "includes": [
          "53992aac-cbbf-4b97-bb-09142435e1ea",
          "344c8ceb-01ac-4d76-8f93-bbbc3d0edd5d"
        ]
      }
    }
  ]
}

{
  "facets": {
    "results": [
      {
        "name": "categories",
        "buckets": [
          {
            "key": "53992aac-cbbf-4b97-bb-09142435e1ea",
            "count": 243
          },
          {
            "key": "344c8ceb-01ac-4d76-8f93-bbbc3d0edd5d",
            "count": 12
          }
        ]
      }
    ]
  }
}

Filtering buckets by the beginning of the key

The optional field startsWith allows to filter bucket keys in the facets results by the beginning of the key. It also allows to specify case sensitivity for the match.

Example:

The following example filters buckets to match Attribute names that start with a case-insensitive "my":

{
  "facets": [
    {
      "distinct": {
        "name": "attributes",
        "field": "attributes.name",
        "startsWith": {
          "value": "my",
          "caseInsensitive": true
        }
      }
    }
  ]
}

{
  "facets": {
    "results": [
      {
        "name": "attributes",
        "buckets": [
          {
            "key": "My attribute 1",
            "count": 1
          },
          {
            "key": "my attribute 2",
            "count": 2
          }
        ]
      }
    ]
  }
}

Missing values

If the field defined in distinct.field is optional, then all the Products without a value for this field will be ignored by default.

To include the count of Products with missing values, add a missing key and value. The value of missing will be used as the key for the count of Products without a value for distinct.field.

Example:

The following example calculates the number of Products in a specific State. The number of Products without a State is indicated with the key N/A. All other keys represent the id of a State, with the values specifying the count of Products in that State.

{
  "facets": [
    {
      "distinct": {
        "name": "states",
        "field": "state",
        "missing": "N/A",
        "limit": 50
      }
    }
  ]
}

{
  "facets": {
    "results": [
      {
        "name": "states",
        "buckets": [
          {
            "key": "N/A",
            "count": 112
          },
          {
            "key": "995c735c-ad07-4d22-a35b-34e8f5238fd74",
            "count": 63
          },
          {
            "key": "fb77d7dc-94c5-45df-95bc-b8499286e4d55",
            "count": 34
          }
        ]
      }
    ]
  }
}

Sorting buckets in the facets results

The optional sort field allows sorting the bucket results in the facets results. You can sort buckets either by count or key and specify the order of the sort by asc or desc.

ProductSearchFacetDistinctBucketSortExpression

ProductSearchFacetDistinctBucketSortBy

Example:

The following example sorts an Attribute called "name" by key in descending order.

{
  "facets": [
    {
      "distinct": {
        "name": "attributes",
        "field": "variants.attributes.name",
        "sort": {
          "by": "key",
          "order": "desc"
        }
      }
    }
  ]
}

{
  "facets": {
    "results": [
      {
        "name": "attributes",
        "buckets": [
          {
            "key": "z-attribute",
            "count": 1
          },
          {
            "key": "b-attribute",
            "count": 2
          },
          {
            "key": "a-attribute",
            "count": 1
          }
        ]
      }
    ]
  }
}

Count entity for distinct and ranges facet

When faceting you might be interested in counting the number of Products (default) or Product Variants that fall into a particular bucket. You can specify the counting level via the count parameter of distinct and ranges facets.

Example:

In the following example, given 10 Products each with 5 Product Variants, the sizesByProducts buckets will have a count of 10 (each Product has an item of each size) while the sizesByVariants buckets will have a count of 50 (each Product Variant of a given size is counted).

 "facets": [
    {
      "distinct": {
        "name": "sizesByProducts",
        "fieldType": "number",
        "field": "variants.attributes.size",
        "count": "products"
      }
    },
    {
      "distinct": {
        "name": "sizesByVariants",
        "fieldType": "number",
        "field": "variants.attributes.size",
        "count": "variants"
      }
    }
  ]

Scoping of facets

By default, all facets run in the scope of a query. That means if you query, for example, for Products that have been last modified before a certain date and in that same query you have a facet, this facet will only count Products that match the query.

Product Search provides two ways of scoping the facets: the global facet and the filter facet. You can combine both to accurately define the scope of your facets.

ProductSearchFacetScopeEnum

Global facet

To run a facet in global scope, set scope to all.

Example:

In the following example, the "names" facet aggregates all Products, not only the ones with "butter" in their description.

{
  "query": {
    "fullText": {
      "field": "description",
      "value": "butter",
      "language": "en"
    }
  },
  "facets": [
    {
      "distinct": {
        "scope": "all",
        "name": "names",
        "field": "name",
        "language": "en",
        "limit": 50
      }
    }
  ]
}

Filter facet

If you need to run a facet on a subset of Products that is different from the result of the query, you can use a filter facet.

Example:

In the following example, androidTabletOSVersions is scoped only to Products that have the Attribute isTablet set to true.

{
  "query": {
    "exact": {
      "field": "variants.attributes.os",
      "fieldType": "text",
      "value": "Android"
    }
  },
  "facets": [
    {
      "distinct": {
        "name": "androidTabletOSVersions",
        "field": "variants.attributes.osVersion",
        "fieldType": "text",
        "limit": 50,
        "filter": {
          "exact": {
            "field": "variants.attributes.isTablet",
            "fieldType": "boolean",
            "value": true
          }
        }
      }
    }
  ]
}

Sorting

Sorting allows you to control how the results of your search query are sorted. If no sort is specified, the results are sorted by relevance score in descending order. Compound sorting (also known as multi-sort) is applied when you specify multiple sort expressions in order of priority, with each expression having its own sort direction. See the following example:

{
  "sort": [
    {
      "field": "variants.prices.centAmount",
      "order": "asc",
      "mode": "min"
    },
    {
      "field": "score",
      "order": "desc"
    }
  ]
}

For more information about sorting Product Search results, see the documentation for the search query language.

Pagination

Pagination allows you to retrieve a large number of search results by requesting them page by page. For more information about pagination, see the documentation for the search query language.

Product indexing

On average, Products are indexed every 15 minutes. Depending on the amount of data to update, the actual delay—until the product data is up-to-date—can be higher.

Prices

The Product's priceMode determines which Prices are indexed in the variants.prices field.
For the Embedded ProductPriceMode, the API indexes Embedded Prices; for Standalone, the API indexes the Standalone Prices associated with the Product Variant.

The API uses the variants.prices field for sorting, filtering, and faceting on Products, but its content is only retrievable through data integration with Product Projection parameters for Embedded Prices. Standalone Prices cannot be retrieved through the Product Search API.

To ensure good performance of the API, the number of Standalone Prices indexed per Product is limited to 10 000. For Products with Standalone Prices that exceed this limit, the system indexes a selection of the Prices as explained in the Large number of Standalone Prices section.

Only one valid price for each price scope (currency, country, customerGroup, and distributionChannel) is actually indexed. Like other attributes, this process operates on an eventually consistent basis, meaning that invalid prices might still be present in the index immediately after an update. When trying later, the price will be updated.

In case of multiple prices for the same scope, the one with the narrower (valid) time range is always selected over the price without time ranges.

If Price selection parameters are provided in the ProductSearchProjectionParams, the price field in the returned Product Projections is determined by price selection.

Large number of Standalone Prices

The search index can hold up to 10 000 Standalone Prices per Product. In case you have Products with more Standalone Prices than that limit, the API applies the following sorting algorithm when indexing the Product Prices to achieve a fair distribution of indexed Prices across all Product Variants:

For each Product in the Project:

1. Calculate variant limit by dividing 10 000 by the number of Variants on the Product.
2. fetch Prices for all Variants.
3. for each Variant:

• sort Prices by

  • currency (alphabetically by the value.currencyCode)
  • country (alphabetically, missing field is sorted as first)
  • channel (alphabetically by key, missing field is sorted as first)
  • Customer Group (alphabetically by key, missing field is sorted as first)

• truncate Prices that are beyond the variant limit

Localized content

To support exact, full text, prefix, and wildcard query expressions, the Product Search API analyzes the localized product data specific to the supported languages.

Language settings

When Products are indexed, the Product Search API selects the best-fitting language-specific analyzer according to the Project settings. If no languages are set on the Project, the analyzers for the following languages are used by default: en, en-GB, en-CA, en-US, en-AU, de, de-DE, es, se, fi, da, fr, and fr-FR.

Supported languages