Getting recommendations

Caution: As of January 2021, this documentation for the beta product Recommendations Engine API is no longer updated. See the documentation for the GA version of this product, Retail API: Getting recommendations

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

After you have uploaded your catalog items 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.

Note: Recommendations AI returns a list of ranked catalog item identifiers. You are responsible for rendering the results on your website with images and text.

Before you begin

Before you can access the Recommendations AI API, you must create a Google Cloud project and set up authentication using the steps in Before you begin.

In particular, if you plan to use API keys for authenticating requests for recommendations, you must register the key.

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.

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:

• Replace api-key with an API key that you have registered to use with for the predict method.

• Replace placement with the placement where you will use the predictions. Learn more.

• If you imported Google Analytics 360 user events using BigQuery, set visitor-id 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, replace experiment-group with 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 Recommendations AI.

• Optionally, provide a filter to narrow the potential catalog items returned. Learn more.

Note: If your recommendation is not yet active, or you want to test your method call, you can call this method with the dryRun flag set to true. This call returns a dummy result, and does not incur charges. You can see whether your recommendation is active on the Dashboard tab.

curl -X POST \
    -H "Content-Type: application/json; charset=utf-8" \
    --data  '{
          "filter": "filter-string",
          "dryRun": false,
          "userEvent": {
               "eventType": "detail-page-view",
               "userInfo": {
                    "visitorId": "visitor-id",
                    "userId": "user-id",
                    "ipAddress": "ip-address",
                    "userAgent": "user-agent"
               },
              "eventDetail": {
                  "experimentIds": "experiment-group"
               },
              "productEventDetail": {
                  "productDetails": [
                       {
                        "id": "product-id"
                       }
                  ]
              }
         }
     }'
https://recommendationengine.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/catalogs/default_catalog/eventStores/default_event_store/placements/placement:predict?key=api-key

You should see results similar to the following:

{
  "results": [{"id": "sample-id-1"}, {"id": "sample-id-2"}],
  "recommendation_token": "sample-rec-token"
}

You must associate the recommendation_token value with any URL you serve as a result of this prediction, and return it with user events for those URL. 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 catalog items when you uploaded them, you can specify that only items 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.

  Note: Tag expression updates can take up to 24 hours to become available for use in filtering predictions.

• filterOutOfStockItems

  The filterOutOfStockItems flag filters out any catalog items 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"