This is the documentation for Recommendations AI, Retail Search, and the new Retail console. To use Retail Search in the restricted GA phase, contact Cloud sales.

If you are only using Recommendations AI, remain on the Recommendations console and refer to the Recommendations AI documentation.

Getting recommendations

This page describes how to request 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.

Before You Begin

Before you can access the Retail API, 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 AI, you need a trained and tuned recommendation (model) and one or more active serving configurations.

Recommendation preview

Before you update your website code to request recommendations, you can use prediction preview to confirm that your configuration is working as you expect.

Make sure you have first created a serving configuration for Recommendations AI.

To preview recommendations returned by your serving configuration:

  1. Go to the Retail Evaluate page in the Google Cloud Console.

    Go to the Evaluate page

  2. Select the serving configuration you want to preview.

  3. Enter a visitor ID to preview recommendations for that user.

  4. Click Prediction preview to see the prediction results.

Getting a recommendation

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 configuration 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 to the Retail API.

  • 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/placements/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 configuration level, or per prediction request.

When you choose a price reranking setting when creating a serving configuration in Cloud 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 via the Retail API 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 configuration level, or per prediction request.

When you choose a diversification setting when creating a serving configuration in Cloud 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 via the Retail API using the PredictRequest.params field. This overrides any configuration-level diversification setting that would otherwise apply to this recommendation. See for accepted values.

Using recommendation filters

You can filter the recommendations returned by Recommendations AI by using the filter field in the predict method.

The filter field accepts two forms of filter specification:

  • Tag expressions

    If you added tag values to your products when you uploaded them, you can specify that only products that match all of the tags you filter on are returned as recommendations. Learn more.

    Tag expressions can contain the boolean operators OR or NOT, which must be separated from the tag values by one or more spaces. Tag values can also be immediately prepended by a dash (-), which is equivalent to the NOT operator. Tag expressions that use the boolean operators must be enclosed in parentheses.

  • filterOutOfStockItems

    The filterOutOfStockItems flag filters out any products with a stockState of OUT_OF_STOCK.

You can combine these two types of filters; only items that satisfy all specified filter expressions are returned.

Some example filter strings:

"filter": "tag=\"spring-sale\""
"filter": "filterOutOfStockItems"
"filter": "tag=\"spring-sale\" tag=\"exclusive\" filterOutOfStockItems"

The following example returns only items that are in stock that have either the `spring-sale` or the `exclusive` tag (or both) and also does not have the `items-to-exclude` tag.

"filter": "tag=(\"spring-sale" OR \"exclusive\") tag=(-\"items-to-exclude\") filterOutOfStockItems"