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.
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:
Go to the Recommendations AI Models page in the Google Cloud console.
Go to the Recommendations AI Models pageClick the model name to open its details page.
Click the placement you want to preview.
(Optional) Enter a user ID to preview results for that user.
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 thepredict
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.
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
orNOT
, 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 theNOT
operator. Tag expressions that use the boolean operators must be enclosed in parentheses.filterOutOfStockItems
The
filterOutOfStockItems
flag filters out any catalog items with astockState
ofOUT_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"