Retail is being renamed to Vertex AI Search for retail. We are in the process of updating content to reflect the new branding.

Get recommendations

This page describes how to request product recommendations for a specific user and user event.

After you have uploaded your products and recorded user events, you can request product recommendations for specific users based on the recorded user events for that user and their current activity. It can take up to 48 hours for new products and user events to be reflected in the recommendation model.

Vertex AI Search for retail returns a list of ranked product identifiers. You are responsible for rendering the results on your website with images and text.

Never cache personalized results from an end user, and never return personalized results to a different end user.

Before You Begin

You must create a Google Cloud project and set up authentication using the steps in Before you begin.

In addition, before you can request predictions from recommendations, you need a trained and tuned recommendation (model) and one or more active serving configs.

Evaluate recommendations

Before you update your website code to request recommendations, you can use preview prediction results to confirm that your model and serving config are working as you expect.

For more information about serving configs, see About serving configs.

You can preview serving config results either from the Evaluate page, or by going to a serving config's Details page in the console and clicking its Evaluate tab. The following steps show you how to preview from the Evaluate page.

To preview recommendations returned by your serving config:

Go to the Evaluate page in the Search for Retail console.

Go to the Evaluate page
Click the Recommendations tab, if it isn't already selected.
Select the serving config you want to preview.
Optional: Enter a visitor ID to preview recommendations for that user.
If the Associated items section is shown, click Add item and enter a product ID to get associated recommendations for that item. You can add multiple associated items.

Adding items is available only if the selected serving config's model type requires products as input for recommendations. Recommended for You models don't require associated items to be entered.
Click Prediction preview to see the prediction results.

To see the Details page for the serving config you're previewing, click View serving config under the Select serving config field.

For prediction cost details, see Pricing.

curl

To get a recommendation, make a POST request to the predict REST method and provide the appropriate request body:

The service account you use needs to have role "Retail Viewer" or above.
Replace SERVING_CONFIG_ID with the serving config where you will use the predictions. Learn more.
If you imported Google Analytics 360 user events using BigQuery, set visitorId to the Google Analytics client ID. See the Google Analytics documentation for how to get the client ID.
If you are running an A/B experiment, set experimentIds to the ID for this experiment group. Learn more.
Provide a user event object for the user action that initiated the recommendation request.

Note that this user event is not recorded; it is only used to provide context for this recommendation request. You should also record the user event the same way you record other user events.
Optionally, provide a filter to narrow the potential products returned. Learn more.

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data '{
              "filter": "FILTER_STRING",
              "validateOnly": false,
              "userEvent": {
                  "eventType": "detail-page-view",
                  "visitorId": "VISITOR_ID",
                  "userInfo": {
                      "userId": "USER_ID",
                      "ipAddress": "IP_ADDRESS",
                      "userAgent": "USER_AGENT"
                  },
                  "experimentIds": "EXPERIMENT_GROUP",
                  "productDetails": [{
                      "product": {
                        "id": "PRODUCT_ID"
                     }
                  }]
              }
            }' \
https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/servingConfigs/SERVING_CONFIG_ID:predict

You should see results similar to the following:

{
  "results": [{"id": "sample-id-1"}, {"id": "sample-id-2"}],
  "attribution_token": "sample-atr-token"
}

You must associate the attribution_token value with any URL you serve as a result of this prediction, and return it with user events for those URLs. Learn more.

Java

public static PredictResponse predictWithNextPageToken(UserEvent userEvent, int pageSize,
    String nextPageToken)
    throws IOException, InterruptedException {
  PredictionServiceClient predictionClient = getPredictionServiceClient();

  PredictRequest request = PredictRequest.newBuilder()
      .setPlacement(HOME_PAGE_PLACEMENT_NAME)
      .setUserEvent(userEvent)
      .setPageSize(pageSize)
      .setPageToken(nextPageToken)
      .setValidateOnly(true)
      .build();

  PredictResponse response = predictionClient.predict(request);

  predictionClient.shutdownNow();
  predictionClient.awaitTermination(2, TimeUnit.SECONDS);

  return response;
}

Price reranking

Price reranking causes recommended products with a similar recommendation probability to be ordered by price, with the highest-priced items first. Relevance is still also used to order items, so enabling price reranking is not the same as sorting by price.

Price reranking can be set on the serving config level, or per prediction request.

When you choose a price reranking setting when creating a serving config in the Search for Retail console, that setting applies to all recommendations served by that configuration, without you having to take further action.

If you need to control the price reranking of a particular recommendation, you can do so using the PredictRequest.params field. This overrides any configuration-level reranking setting that would otherwise apply to this recommendation.

Recommendation diversity

Diversification affects whether results returned from a single prediction request are from different categories of your product catalog.

Diversification can be set on the serving config level, or per prediction request.

When you choose a diversification setting when creating a serving config in the Search for Retail console, that setting applies by default to all recommendations served by that configuration, without you having to take further action.

If you need to control the diversity of a particular recommendation, you can do so using the PredictRequest.params field. This overrides any configuration-level diversification setting that would otherwise apply to this recommendation. See for accepted values.

Use recommendation filters

You can filter the recommendations returned by recommendations by using the filter field in the predict method. For information, see Filter recommendations.

Prediction calls with Page-Level Optimization models

Providing recommendations using Page-Level Optimization requires an extra prediction call step.

Make an initial prediction call using a serving config containing the Page-Level Optimization model. The prediction response returns a sorted list of serving config IDs representing the model to use for each panel.

Then make a prediction call for each panel using the serving config ID that the Page-Level Optimization model recommended for it. The prediction response contains the model name (such as Recommended for You) and list of recommended items to display in that panel.

Price reranking, recommendation diversity, and recommendation filters are not available for serving configs using the Page-Level Optimization model.

Monitor and troubleshoot recommendations

After setting up your website to get recommendations, we recommend that you set up alerts. See Set up an alert for prediction errors.

To troubleshoot errors, see Monitor and troubleshoot.