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 to fetch the entire product data of a matching Product.

With Product Projection parameters

If the aforementioned retrieval and caching options are not feasible for your use case, the Product Search API offers some built-in integration with the Product Projection API also. To do this, provide the productProjectionParameters field with the ProductSearchRequest and the ProductSearchResult contains the projected product data in an additional productProjection field. This integration option prevents you from making an additional API call to the Product Projection API, but the search request takes longer to respond. A best-effort caching approach is in place for this integration but without guarantees on the freshness or possibility of caching the product data.

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: ProduductsSearch 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.

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
          }
        ]
      }
    }
  ]
}

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

ProductSearchFacetExpression

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

ProductPagedSearchResponse

ProductSearchResult

ProductSearchMatchingVariants

ProductSearchMatchingVariantEntry

ProductSearchFacetResult

ProductSearchFacetResultCount

ProductSearchFacetResultBucket

ProductSearchFacetResultBucketEntry

Searchable Product fields

The following list contains the Product fields 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.

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

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
          }
        }
      }
    }
  ]
}

Product indexing

After the Product Search feature is activated, Products are indexed every 15 minutes.

Prices

Prices are indexed in the variants.prices field, and they can be used for sorting, filtering and faceting.

The content of the variants.prices field is determined by the Product's priceMode. When the priceMode is set to Standalone, the variants.prices field contains Standalone prices. Otherwise, it contains Embedded prices.

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