Get recommendations

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

After you have uploaded your documents and recorded user events, you can request recommendations for specific users based on the recorded user events for that user and their current activity.

Discovery for Media returns a list of ranked document 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

Before you can access Discovery for Media, you must create a Google Cloud project and set up authentication using the steps in Before you begin.

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

Get a recommendation

For recommendation cost details, see Pricing.

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

  • The service account you use needs to have role "Discovery Engine Viewer" or above.

  • Replace SERVING_CONFIG_ID with the serving config where you will use the recommendations. 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 Discovery Engine.

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

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data '{
              "filter": "FILTER_STRING",
              "validateOnly": false,
              "userEvent": {
                  "eventType": "view-item",
                  "userPseudoId": "USER_PSEUDO_ID",
                  "documents": [{
                    "id": "DOCUMENT_ID"
                  }]
                  "userInfo": {
                      "userId": "USER_ID",
                      "userAgent": "USER_AGENT"
                  },
                  "pageInfo": {
                    "uri": "URI",
                    "referrerUri": "REFERRER_URI",
                    "pageViewId": "PAGE_VIEW_ID"
                  }
              }
            }' \
https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_NUMBER/locations/global/dataStores/default_data_store/servingConfigs/SERVING_CONFIG_ID:recommend

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 recommendation, and return it with user events for those URLs.

Recommendation diversity

Diversification affects whether results returned from a single recommendation request are from different categories of your document datastore.

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

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

If you need to control the diversity of a particular recommendation, you can do so using the RecommendRequest.params field. This overrides any serving config-level diversification setting that would otherwise apply to this recommendation.

Use recommendation filters

You can filter the recommendations returned by Media Recommendations by using the filter field in the recommend method. See the API reference documentation for the servingConfigs.recommend filter field.

The filter field accepts tag expressions.

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

Tag expressions can contain the boolean operators OR or NOT, which must be separated from the tag values by one or more spaces. Tag expressions that use the boolean operators must be enclosed in parentheses.

Only items that satisfy all specified filter expressions are returned.

Some example filter strings:

"filter": "filter_tags: ANY(\"learning\")"

"filter": "filter_tags: ANY(\"learning\", \"exclusive\")"

The following example returns only items that have either the learning or the exclusive tag (or both) and also does not have the items-to-exclude tag. 

"filter": "(filter_tags: ANY(\"learning\", \"exclusive\")) AND NOT (filter_tags: ANY(\"items-to-exclude\"))"