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 placements.

Recommendation preview

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

To preview recommendations returned by your model:

  1. Go to the Recommendations AI Models page in the Google Cloud Console.
    Go to the Recommendations AI Models page

  2. Click the model name to open its details page.

  3. Click the placement you want to preview.

  4. (Optional) Enter a user ID to preview results for that user.

  5. Click Prediction preview to see the prediction results.

Prediction preview with sample images returned

Getting a recommendation

For prediction cost details, see Pricing.


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 PLACEMENT_ID with the placement where you will use the predictions. [Learn more][placements].

  • 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"
          }' \[PROJECT_ID]/locations/global/catalogs/default_catalog/placements/PLACEMENT_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.

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"