This is the unified documentation for Retail API. This includes Recommendations AI, Retail Search, and the unified Retail console (which is applicable to both Recommendations AI and Retail Search users). To use the new console or Retail Search while they are in the restricted GA phase, submit a form here to contact Cloud sales. If you are using the v1beta version of Recommendations AI, migrate to the GA version: Migrating to the Retail API from beta.

To see documentation for only Recommendations AI and the Recommendations AI-only console, go to the How-to guides for Recommendations AI and the API reference documentation for Recommendations AI.

Before you begin

This page outlines the steps you must take before using the Retail API.

Set up your project

You must create a Google Cloud project in order to access the Retail API. To set up a project, follow these steps:

  1. Go to the Cloud Console Manage resources page.

    Go to the Manage Resources page

  2. On the drop-down at the top of the page, select the organization in which you want to create a project.

  3. Click Create Project.

  4. In the New Project window that appears, enter a project name and select a billing account as applicable.

  5. If you want to add the project to a folder, enter the folder name in the Location box.

  6. When you're finished entering new project details, click Create.

  7. Enable the Retail API for your Google Cloud project.

    ENABLE THE RETAIL API

    Click the ENABLE button in the Google Cloud console to enable the API.

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 Authenticating 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 Cloud SDK. To download and install the SDK, see Cloud SDK.

  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

Authenticating 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();
    }
  }
}

Authenticating using an API key

Here is an example of authenticating using an API key from the command line using the curl command. Replace api-key with the API key that you created in the previous section.

URL="https://retail.googleapis.com/v2/projects/[PROJECT_ID]/locations/global/catalogs/default_catalog/userEvents:write?key=api-key"

DATA='{
  "user_attributes": {
    ...
  },
  "user_event_detail": {
    ...
  }
}'

echo $URL
curl -H 'Content-Type: application/json' -X POST -d "${DATA}"  $URL

Access the Retail management console

The Retail console enables you to manage Retail resources and monitor its activity from the browser-based Google Cloud Console.

See Retail administration console for an overview of what you can do in the console.

Go to the Retail Cloud Console

What's next