This is the documentation for Recommendations AI, Retail Search, and the new Retail console. To use Retail Search in the restricted GA phase, contact Cloud sales.

If you are only using Recommendations AI, remain on the Recommendations console and refer to the Recommendations AI documentation.

Implementing Retail

This page provides step-by-step guidance for implementing the Retail API.

Introduction

When you use Recommendations AI or Retail Search, you'll use the Retail API to ingest user event and catalog data, and to serve predictions or search results on your site.

The Retail API uses the same data for both Recommendations AI and Retail Search, so if you use both, you don't need to ingest the same data twice.

See the User event requirements and best practices for user event data that Retail and Retail Search use. If you use Recommendations AI models, User event data requirements lists additional requirements depending on your model type and optimization objective. These requirements help Retail API can generate quality results.

The average integration time for the Retail API is in the order of weeks. Note that for Retail Search, the actual duration depends heavily on the quality and quantity of data to ingest.

If you are using Google Tag Manager or Google Merchant Center, you can implement the Retail API with Google marketing.

You can use the Retail API to get personalized results for your website whether or not you are using Google marketing tools. If you are not, see Implementing the Retail API.

Implementing the Retail API with Google marketing

If you use the Google marketing stack (Google Tag Manager and Google Merchant Center), you can use those products to provide data that the Retail API can use.

Step Description
1. Set up a Google Cloud project You can use an existing Google Cloud project if you have one already.
2a. Import your product catalog using Merchant Center

You can also directly import your product catalog, but linking to Merchant Center reduces the steps needed to import your catalog.

Note that Merchant Center does not support the collections product type. Before importing, make sure to review Merchant Center limitations to check if it meets your catalog needs.

2b. Configure Tag Manager to record user events User events track user actions such as clicking on a product, adding an item to a shopping cart, or purchasing an item. You can start recording user events in parallel to the catalog import. Once the catalog import is complete, rejoin any events that were uploaded before the import completed.
3. Import historical user events

Your models need sufficient training data before they can provide accurate predictions. Providing historical user event data enables you to start model training without having to wait months for enough user event data to be collected from your site. Learn more.

4. Create your serving configuration, model, and controls

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. When you create a serving configuration, you can simultaneously create a model (for Recommendations AI only) or controls (for Retail Search only). You can also create these separately.

If you use Recommendations AI, choose a model type based on the location of your serving configuration and its objectives. Review the available recommendation types, optimization objectives, and other model tuning options to determine the best options for your business objectives. (For Retail Search serving configurations, a default model is automatically created by the Retail API.)

5. Allow time for model tuning

Creating a model initiates model training. Initial model training and tuning takes 2-5 days to complete.

6. Preview your serving configuration

After your model has been activated, preview your serving configuration's recommendations or search results to ensure your setup is functioning as expected.

7. Set up an A/B experiment (Optional)

You can use an A/B experiment to compare the performance of your website when using the Retail API to a baseline version that does not use the Retail API.

8. Evaluate your configuration

Assess the metrics provided by Cloud Console to help you determine how incorporating the Retail API is affecting your business.

View the metrics for your project on the Monitoring & Analytics page of Cloud Console.

Implementing the Retail API

Use the following steps to integrate the Retail API into your website.

Step Description
1. Set up a Google Cloud project

To use the Retail API, create a Google Cloud project and create authentication credentials including an API key and an OAuth token (either using a user account or a service account) to access the project.

2a. Import your product catalog

You can add items to your product catalog individually by using the Products.create method. For large product catalogs, we recommend that you add items in bulk using the Products.import method.

2b. Record user events

User events track user actions such as clicking on a product, adding an item to a shopping cart, or purchasing an item, and so on. The Retail API relies on user event data in order to generate personalized results. User events need to be ingested in real time to accurately reflect the behavior of your users.

You can start recording user events in parallel to the catalog import. Once the catalog import is complete, rejoin any events that were uploaded before the import completed.

3. Import historical user events

Your models need sufficient training data before they can provide accurate predictions. Providing historical user event data enables you to start model training without having to wait months for enough user event data to be collected from your site. Learn more.

4. Create your serving configuration, model, and controls

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

When you create a serving configuration, you can simultaneously create a model or controls, or create them separately.

For Recommendations AI, the location of your serving configuration and its objectives impact model tuning. Review the available recommendation types, optimization objectives, and other model tuning options to determine the best options for your business objectives.

5. Allow time for training

Creating your model or serving configuration initiates training. Initial model training and tuning takes 2-5 days to complete.

6. Preview your serving configuration

After your configuration has been activated, preview your serving configuration's recommendations or search results to ensure your setup is functioning as expected.

7. Set up an A/B experiment (Optional)

You can use an A/B experiment to compare the performance of your website when using the Retail API to a baseline version that does not use the Retail API.

8. Evaluate your configuration

Assess the metrics provided by Cloud Console to help you determine how incorporating the Retail API is affecting your business.

View the metrics for your project on the Monitoring & Analytics page of Cloud Console.

Terms of Service

Product usage is under Google Cloud's Terms and Conditions and customer information will be used in accordance with Google's Privacy Policy.

For quality assurance, a small sample set of search queries and search results from Retail API logs are sent for human rating to third-party vendors including Cognizant Worldwide Limited.