This page provides step-by-step guidance for implementing the Retail API.
Introduction
When you use Recommendations AI or Retail Search, you 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 tools.
You can use the Retail API to get personalized results for your website whether or not you are using additional Google tools. If you are not, see Implement the Retail API.
Never cache personalized results from an end user, and never return personalized results to a different end user.
Implement the Retail API with Google tools
If you use 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. After 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 config, model, and controls |
A serving config is a serving entity that associates a model and, optionally, controls. These are used when generating your search or recommendation results. When you create a serving config, you can simultaneously create a model (for Recommendations AI only) and controls. You can also create these separately. If you use Recommendations AI, choose a model type based on the location of your serving config 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 configs, 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, but can take longer for large datasets. |
| 6. Preview your serving config |
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 Google Cloud console to help you determine how incorporating the Retail API is affecting your business. View the metrics for your project on the Analytics page of Google Cloud console. |
Implement the Retail API without additional Google tools
If you are not using Tag Manager and Merchant Center, use the following steps to integrate Retail 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
|
| 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. After 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 config, model, and controls |
A serving config is a serving entity that associates settings with a model and, optionally, controls. These are used when generating your search or recommendation results. When you create a serving config, you can simultaneously create a model and 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 config initiates training. Initial model training and tuning takes 2-5 days to complete, but can take longer for large datasets. |
| 6. Preview your serving config |
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 Google Cloud console to help you determine how incorporating the Retail API is affecting your business. View the metrics for your project on the Analytics page of Google Cloud console. |
Terms of Service
Product usage is under Google Cloud's Terms and Conditions or relevant offline variant. The Google Cloud Privacy Notice explains how we collect and process your personal information relating to the use of Google Cloud and other Google Cloud services.
For quality assurance, a small sample set of search queries and search results from Retail API logs, which include customer data, are sent for human rating to third-party vendors disclosed as Third-Party Subprocessors for Retail Search. Additional tests using search queries and search results from Google Search logs that are publicly collected datasets are sent for human rating to different third-party vendors for quality assurance. The Google Search logs are not categorized as customer data.