Get recommendations

REST

To use the API to get media recommendations, use the servingConfigs.recommend method:

1. Find your engine ID and serving config ID. If you already have your engine ID and serving config IDs, skip to step 2.

   1. In the Google Cloud console, go to the AI Applicationspage.

      AI Applications

   2. Click the name of the app.

   3. In the navigation pane, click Configurations.

   4. If you have only one serving config, get the serving config ID that is displayed in the Servingtab.

      If you have multiple serving configs listed in the Servingtab, find the serving config that you want to get recommendations from. Your serving config ID is the value in the IDcolumn.

   5. Click the Trainingtab. Your engine ID is the value in the App IDrow.

2. Make sure the app is ready for previewing:

   1. In the Google Cloud console, go to the AI Applicationspage.

      AI Applications

   2. Click the name of the app.

   3. Click Configurations> Training. If Ready to queryis Yes, then the app is ready for preview.

3. Get recommendations.

   curl  
   -X  
   POST  
    \ 
   -H  
    "Authorization: Bearer 
    $( 
   gcloud  
   auth  
   print-access-token ) 
    " 
     
    \ 
   -H  
    "Content-Type: application/json; charset=utf-8" 
     
    \ 
   -d  
    '{ 
    "validateOnly": false, 
    "userEvent": { 
    "eventType": "view-item", 
    "userPseudoId": " USER_PSEUDO_ID 
   ", 
    "documents": [{ 
    "id": " DOCUMENT_ID 
   " 
    }], 
    "filter": " FILTER_STRING 
   "            } 
    }' 
     
    \ 
     
    "https://discoveryengine.googleapis.com/v1beta/projects/ PROJECT_ID 
   /locations/global/collections/default_collection/dataStores/ DATA_STORE_ID 
   /servingConfigs/ SERVING_CONFIG_ID 
   :recommend" 
   

   Replace the following:

   • PROJECT_ID : the ID of your project.
   • DATA_STORE_ID : the ID of your data store.
   • DOCUMENT_ID : the ID of document that you want to preview recommendations for. Use the ID that you used for this document at the time you ingested your data.
   • USER_PSEUDO_ID : a UTF-8 encoded string, which acts as a unique pseudonymized identifier that tracks the users. It can have a maximum length of 128 characters. Google strongly recommends using this field because it improves model performance and personalization quality. You can use an HTTP cookie for this field, which uniquely identifies a visitor on a single device. Some important considerations are as follows:
     • This identifier doesn't change when the visitor signs in or out of a website.
     • This field must not be set to the same identifier for multiple users. Otherwise, same user ID can combine event histories of different users and degrade model quality.
     • This field must not include personally identifiable information (PII).

     For more information, see userPseudoId .

   • SERVING_CONFIG_ID : the ID of your serving config.
   • FILTER : optional. A text field that lets you to filter on a specified set of fields, using filter expression syntax. The default value is an empty string, which means no filter is applied. For more information, see Filter recommendations .

You should see results similar to the following:

 { 
  
 "results" 
 : 
  
 [{ 
 "id" 
 : 
  
 "sample-id-1" 
 }, 
  
 { 
 "id" 
 : 
  
 "sample-id-2" 
 }], 
  
 "attributionToken" 
 : 
  
 "abc123" 
 } 

Google recommends associating attribution tokens, which we include with each search response and recommendation, with actions that a user takes in response to those search responses and recommendations. This can improve the quality of your search responses and recommendations over time. To do this, append attributionToken values to the URLs for each of the links that you display on your website for search responses or recommendations—for example, https://www.example.com/54321/?rtoken=abc123 . When a user clicks one of these links, include the attributionToken value in the user event that you record.