This is the unified documentation for Retail API. This includes Recommendations AI, Retail Search, and the unified Retail console (which is applicable to both Recommendations AI and Retail Search users). To use the new console or Retail Search while they are in the restricted GA phase, submit a form here to contact Cloud sales. If you are using the v1beta version of Recommendations AI, migrate to the GA version: Migrating to the Retail API from beta.

To see documentation for only Recommendations AI and the Recommendations AI-only console, go to the How-to guides for Recommendations AI and the API reference documentation for Recommendations AI.

Adjusting Result Size

This page provides an overview of query expansion and relevance thresholding.

Example dataset

This page uses the following dataset as an example. Only the fields necessary for explanation are included.

Query Expansion

Query expansion increases the recall for query terms with few results, especially long tail queries.

Java

public static SearchResponse searchProductsWithQueryExpansion(String visitorID, String query)
    throws IOException {
  SearchRequest searchRequest =
      SearchRequest.newBuilder()
          .setPlacement(PLACEMENT_NAME)
          .setVisitorId(visitorID)
          .setQuery(query)
          .setQueryExpansionSpec(
              QueryExpansionSpec.newBuilder().setCondition(QueryExpansionSpec.Condition.AUTO))
          .build();
  return SearchServiceClient.create().search(searchRequest).getPage().getResponse();
}

For example, if you search "Google Pixel 5" without query expansion, you might only get "google_pixel_5" in the result. With query expansion, you might get "google_pixel_4a_with_5g", "google_pixel_4a" and "google_pixel_5_case" as well.

Relevance Thresholding

Relevance thresholds provide trade-off on the precision and recall spectrum.

Java

public static SearchResponse searchProductsWithRelevanceThreshold(
    String visitorID, String query, RelevanceThreshold relevanceThreshold) throws IOException {
  SearchRequest searchRequest =
      SearchRequest.newBuilder()
          .setPlacement(PLACEMENT_NAME)
          .setVisitorId(visitorID)
          .setQuery(query)
          .setRelevanceThreshold(relevanceThreshold)
          .build();
  return SearchServiceClient.create().search(searchRequest).getPage().getResponse();
}

For example, if you search "Google Pixel 5" with the default relevance threshold, you might only get the product with ID "google_pixel_5" in the result. With the LOW relevance threshold, you might get products with ID "google_pixel_4a_with_5g", "google_pixel_4a", "google_pixel_5_case", "google_pixel_4a_with_5g_case" and "google_pixel_4a_case". With the LOWEST relevance threshold, you might further get the products with ID "google_pixel_stand", "google_pixel_buds" and even other Nest speakers.