This is the documentation for Recommendations AI, Retail Search, and the new Retail console.

Before you begin

Create a Google Cloud project

  1. On the Manage resources page in the Cloud console, select or create a Google Cloud project.

    Go to the Manage Resources page

  2. Make sure that billing is enabled for your Cloud project. Learn how to check if billing is enabled on a project.

Set up the Retail API

To use the Retail API, along with Recommendations AI, you must turn on the Retail API and accept the Discovery Solutions data use terms. If you are also using Retail Search, you must enable it. Using Retail Search incurs additional costs based on the number of queries. For more information, see Retail Search charges.

To set up the Retail API, complete the following steps:

  1. Go to the Retail page in the Cloud console.

    Go to the Retail page

  2. On the Set up Retail API page, click Turn on API.

  3. When Retail API and Recommendations AI display as On, click Continue.

  4. Read the Discovery Solutions data use terms and click Accept if you agree to the data use terms.

    When you accept the data use terms, the Cloud console indicates that the Retail API data use terms are accepted.

  5. If you want to use the project with Recommendations AI only, click Get Started.

  6. If you want to turn on Retail Search in addition to Recommendations AI, do the following:

    1. Click Continue and then click Turn on on the Turn on Retail Search (Optional) page.
    2. Click Get Started.

The Cloud console displays the Retail API components that you have turned on. You can now configure your project's initial settings.

Set up the Retail API for an existing project

If you set up the Retail API on a Google Cloud project before the data use terms went into effect on April 4, 2022, you must accept the Discovery Solutions terms to continue using the Retail API with that project. You must also enable Retail Search for that project, if required.

To accept the Discovery Solutions data use terms for an existing project, complete the following steps:

  1. Go to the Retail page in the Cloud console for your project.

    Go to the Retail page

  2. On the Data use terms page, read the Discovery Solutions data use terms and click Accept if you agree to the terms.

  3. If you want to use the project with Recommendations AI only, click Get Started.

  4. If you want to turn on Retail Search in addition to Recommendations AI, do the following:

    1. Click Continue and then click Turn on on the Turn on Retail Search (Optional) page.
    2. Click Get Started.

Turn off Retail Search or the Retail API

Turn off Retail Search

If you no longer want to use Retail Search, you can turn it off by submitting a support ticket.

To set your ticket to the correct component, select the following fields:

  • Category: Machine Learning
  • Component: Retail Solutions: Retail Search
  • Subcomponent: Account Administration & Billing

For more information on creating a support ticket, see Getting support.

Turn off the Retail API

You can turn off the Retail API at any time by disabling it and Recommendations AI. This also turns off Retail Search.

To turn off the Retail API, complete the following steps:

  1. Go to the Retail API Service Details page in the Cloud console.

    Go to the Retail API Service Details page

  2. Click Disable API.

  3. In the Disable Retail API? box, click Disable.

  4. In the Disable Recommendations AI? box, click Disable.

Get started with the Retail API

When you set up the Retail API for a new project, the Google Cloud console displays the following three panels to help you configure your Retail API project:

  • Catalog: displays your product catalog and a link import your catalog.

  • Event: displays your user events and a link to import historical user events.

  • Serving configs: contains details on your serving configuration and a link to create a new serving configuration.

You can use these panels to import your data and to create an initial configuration for your Retail API project.

Import your product catalog

To import your product catalog, complete the set of steps for your data source. For more information on product catalogs, see Importing catalog information.

Merchant Center Sync

  1. Click Import product catalog to open the Import Data panel.
  2. Choose Product catalog.
  3. Select Merchant Center Sync as your data source.
  4. Select your Merchant Center account.
  5. Select the branch you will upload your catalog to.
  6. Click Import.

Cloud Storage

  1. Click Import product catalog to open the Import Data panel.
  2. Choose Product catalog as your data source.
  3. Select the branch you will upload your catalog to.
  4. Choose Retail Product Catalogs Schema as the schema.
  5. Enter the Cloud Storage location of your data.
  6. If you do not have Retail Search enabled, select the product levels.

    You must select the product levels if this is the first time you are importing your catalog or you are re-importing the catalog after purging it. Learn more about product levels. Changing product levels after you have imported any data requires a significant effort.

    Important: You can't turn on the Retail Search for projects with a product catalog that has been ingested as variants.
  7. Click Import.

BigQuery

  1. Click Import product catalog to open the Import Data panel.
  2. Choose Product catalog.
  3. Select BigQuery as your data source.
  4. Select the branch you will upload your catalog to.
  5. Choose one of the following schemas:
  6. Enter the BigQuery table where your data is located.
  7. (Optional) Under Show advanced options, enter the location of a Cloud Storage bucket in your project as a temporary location for your data.

    If not specified, a default location is used. If specified, the BigQuery and Cloud Storage bucket have to be in the same region.
  8. If you do not have Retail Search enabled and you are using the Merchant Center schema, select the product level.

    You must select the product level if this is the first time you are importing your catalog or you are re-importing the catalog after purging it. Learn more about product levels. Changing product levels after you have imported any data requires a significant effort.

    Important: You can't turn on the Retail Search for projects with a product catalog that has been ingested as variants.
  9. Click Import.

Import your historical user events

To import your historical user events, complete the set of steps for your data source. For more information on historical user events, see Importing historical user events.

Cloud Storage

  1. Click Import user events to open the Import Data panel.
  2. Choose User events.
  3. Select Google Cloud Storage as the data source.
  4. Choose Retail User Events Schema as the schema.
  5. Enter the Cloud Storage location of your data.
  6. Click Import.

BigQuery

  1. Click Import user events to open the Import Data panel.
  2. Choose User events.
  3. Select BigQuery as the data source.
  4. Choose Retail User Events Schema as the schema.
  5. Enter the BigQuery table where your data is located.
  6. (Optional) Enter the location of a Cloud Storage bucket in your project as a temporary location for your data.
    If not specified, a default location is used. If specified, the BigQuery and Cloud Storage bucket have to be in the same region.
  7. (Optional) Under Show advanced options, enter the location of a Cloud Storage bucket in your project as a temporary location for your data.

    If not specified, a default location is used. If specified, the BigQuery and Cloud Storage bucket have to be in the same region.
  8. Click Import.

Create a serving configuration

A serving configuration is a serving entity that associates a model or a set of controls that are used to generate your search or recommendation results.

To create a serving configuration, complete the following steps:

  1. In the Serving configs panel, click Create serving config.
  2. On the Create Serving Config page, choose Search as the product the serving configuration will be used for.
  3. Provide a name for your serving configuration.

    The name must be 1024 characters or less, and can contain only alphanumeric characters, underscores, hyphens, and spaces.
  4. (Optional) If needed, update the ID.

    The ID is generated from the name you provide, and must be unique across your project. It must be 50 characters or less, and cannot contain spaces.
  5. Click Continue.
  6. Choose whether to enable dynamic faceting for this serving configuration.
  7. Choose or create serving controls to optimize your searches with.

    For more information on controls, see Creating and managing controls.

Retail dashboard

When you have completed your initial configuration of your project, the Retail console displays the system state of your Retail API project. The Retail console enables you to manage Retail resources and monitor its activity.

Go to the Retail Cloud console

For more information on the Retail console, see Retail administration console.

Set up authentication for your application

You must set up both of the following authentication methods to access the Retail API:

  • Service Account - Applications use a service account to authenticate calls to Product.

  • API Key - Applications use an API key for calls to user event logging APIs.

Create a service account

  1. Go to the Cloud console Credentials page.

  2. Select the project that you are creating credentials for (the project may already be selected).

  3. Click Create credentials and then select Service account key.

  4. Fill in the following fields:

    Field Value
    Service account New service account
    Service account name enter a name for your service account
    Role Service Accounts > Service Account Token Creator
    Retail > Retail Editor
    Key type JSON
  5. Click Create to create the service account.

    The JSON file that contains the public/private key for the new service account is automatically downloaded to your computer. This JSON file is the only copy of the key for your service account. Be sure to store it in a secure location. The JSON key file must be stored in a location that is accessible from your application (see your-service-account-json-key-file in Authenticate using a service account (OAuth 2.0).

Add the service account to your local environment

If you want to make calls to the Retail API by using the cURL command-line tool, you'll need to make your service account available in your local environment. cURL uses the gcloud auth application-default print-access-token command to obtain an access token for your service account using the Google Cloud CLI. To download and install the gcloud CLI, see gcloud CLI. If you are using the Cloud Shell, the gcloud CLI is already installed.

The GOOGLE_APPLICATION_CREDENTIALS environment variable will not persist if you close down your command window. To make sure that the variable is set to the path to your service account file when you open a new command window, set the value in an initialization shell script.

  export GOOGLE_APPLICATION_CREDENTIALS=path-to-service-account-json-key-file

Create an API key

  1. Go to the Cloud console Credentials page.

  2. In the project drop-down at the top of the Google Cloud console page, select your project (the project may already be selected).

  3. Click Create credentials and then select API key. Do not add any referrer restrictions. Some user privacy settings are known to not pass the referrer url.

    • Take note of the generated API key, which you will use when calling user event logging.
  4. For increased security, add an HTTP restriction to your API Key to restrict access to the Retail service at https://retail.googleapis.com/*.

Examples

Authenticate using a service account (OAuth 2.0)

Here is a Java example of OAuth 2.0 authentication using a service account. More detailed instructions can be found in the authentication documentation. Google has client libraries in 7 languages that you can use to implement OAuth2 authentication in your application. If you prefer to implement the HTTP/REST directly, follow the REST authentication instructions.

In the example, replace your-service-account-json-key-file with the path to the JSON key file for your service account.

// Simple Java example of using Google Cloud OAuth client library.
//
// Please see here for the list of libraries in different languages:
// https://developers.google.com/identity/protocols/OAuth2#libraries
//
// The following example depends on the google api client library.
//
// Maven:
//    <dependency>
//      <groupId>com.google.api-client</groupId>
//      <artifactId>google-api-client</artifactId>
//      <version>1.22.0</version>
//    </dependency>
import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.GenericUrl;
import com.google.api.client.http.HttpRequest;
import com.google.api.client.http.HttpRequestFactory;
import com.google.api.client.http.HttpResponse;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.http.json.JsonHttpContent;
import com.google.api.client.json.GenericJson;
import com.google.api.client.json.jackson2.JacksonFactory;
import java.io.FileInputStream;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collections;
import java.util.List;

public class RetailApiSample {
  public static final String CREATE_PRODUCT_URL =
     "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products";

  public static GoogleCredential authorize() throws Exception {
    return GoogleCredential.fromStream(new FileInputStream("your-service-account-json-key-file"))
        .createScoped(Collections.singleton("https://www.googleapis.com/auth/cloud-platform"))
        .setExpirationTimeMilliseconds(new Long(3600 * 1000));;
  }

  // Build an example product.
  public static GenericJson getProduct() {
    GenericJson categories = new GenericJson()
        .set("categories", Arrays.asList("Electronics > Computers", "Laptops"));
    GenericJson priceInfo = new GenericJson()
        .set("currency_code", "USD")
        .set("price", 800.00)
        .set("original_price", 1000.00);

    return new GenericJson()
        .set("name", "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products/[ProductName]")
        .set("title", "Sample Laptop")
        .set("description", "Indisputably the most fantastic laptop ever created.")
        .set("categories", categories)
        .set("price_info", priceInfo)
        .set("availability", "IN_STOCK")
        .set("available_quantity", 1219);
  }

  public static void main(String[] args) {
    try {
      GoogleCredential credential = RetailApiSample.authorize();

      HttpTransport httpTransport = GoogleNetHttpTransport.newTrustedTransport();
      HttpRequestFactory requestFactory = httpTransport.createRequestFactory();
      HttpRequest request = requestFactory.buildPostRequest(new GenericUrl(CREATE_PRODUCT_URL),
          new JsonHttpContent(new JacksonFactory(), RetailApiSample.getProduct()));
      credential.initialize(request);
      HttpResponse response = request.execute();
      System.out.println("Response content: " + response.parseAsString());
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

What's next