Embracing Product Discovery AI, also known as the Retail API, from Google Cloud can be a highly technical endeavor. However, the incredible results of Google’s AI-powered search and discovery solutions often make this endeavor worthwhile. At Nimstrata, we set out to become experts at leaning into the complexity of Google’s Retail API and have written this article to help you with your own implementation.
This article assumes that you’ve already uploaded a product catalog to the Retail API and are now seeking to understand how to configure the various settings inside of the Google Cloud Retail dashboard.
Before diving into each setting, it’s helpful to understand the difference between placements and serving configurations because you’ll see both referenced throughout the official documentation. If you’re developing a custom solution to add Retail API functionality to your website, you’ll notice that there are two methods that look very similar in the API reference docs:
1POST https://retail.googleapis.com/v2/{placement=projects/*/locations/*/catalogs/*/servingConfigs/*}:search1POST https://retail.googleapis.com/v2/{placement=projects/*/locations/*/catalogs/*/placements/*}:searchSimply put, placements are a legacy implementation of passing servingConfigs into the Retail API. Placements are still supported, but using serving configurations moving forward is recommended. In lieu of placements, the concatenated string of a serving configuration URI now looks like this:
projects/your-project-name/locations/global/catalogs/default_catalog/servingConfigs/default_serving_config
If we parse the hierarchy of the structure, you will see:
Projects —> Locations —> Catalogs —> Serving Configs
Let’s dive into each one.
Projects
The project parameter corresponds to the Google Cloud project that the Retail product catalog belongs to. At the time of this writing, Google Cloud only supports one product catalog per project, so this parameter is unlikely to change during your implementation. If multi-tenancy is supported in the future, it will likely be addressed in the catalogs/* portion of the URI and multiple catalogs will belong to one project.
Locations
The location is always global because the Retail API is a global Google Cloud service.
Catalogs & Branches
As mentioned in the Projects section above, today each Google Cloud project can only have one catalog, and it is a static parameter in the URI named default_catalog. However, catalogs can have different branches, but the catalog parameter in the URI will always call the default_branch.
Branches operate like versions of the default_catalog and are easiest to understand if you visit the “Data” tab of the Google Cloud Retail Dashboard.
If you’d like to upload new data to your catalog without affecting your current data, you can simply use a different branch. This is great for experimentation, testing, and development stores. The Retail API offers three branches, 0, 1, and 2. The default catalog will be set to Branch 0. Making a branch a “Default Branch” is what makes it active, and “Purging” a branch deletes all of the data in that branch.
This leaves us with one parameter that actually changes when calling the API for results, servingConfigs.
Entities
Entities were added at the beginning of 2024 and allow retailers who serve multiple brands or regions (such as the United States and Canada) from a single catalog to include an entity parameter in search and browse requests. If you use entities, be sure to also include the entity field when importing real-time user events, or else the data will be unjoined. By doing this, the Recommendations AI predict endpoint will function correctly automatically, because it simply uses the entity values user events.
An important note with entities is that it does not support multiple currencies. At this time, you still need another catalog (and Google Cloud project) for each additional currency.
Serving Configurations
Serving configurations are entities that associate controls and models with your default_catalog. Two serving configurations will be automatically created for you when you activate the Retail API, default_search and recently_viewed_default.
You’ll also see that recently_viewed_default is already associated with a pre-built model called, Items you recently viewed.
An important concept to understand is that search and browse requests call the same search API endpoints. Calling the search endpoint without a query string is referred to as a browse request in the documentation. If you’re making a call to the API without a search query, you will need to pass in a category and filter, more details are in this article.
Controls
Controls are applied to serving configurations and affect how Retail Search treats queries and returns results. There are several controls available including filtering, redirects, and synonyms. The best place to keep up to date on the list of available controls is this page.
This screenshot shows an example of a Serving Control applied to the default_search serving configuration that would boost the position of medium shirts in search results when a user types in, “shirt.”
Multiple controls can be connected to a search/browse serving configuration.
You’ll also see two tabs on this page titled, Attribute Controls and Autocomplete Controls.
Attribute Controls are closely related to your product catalog data and can be set to change the behavior of indexing, faceting, searching, and filtering results. You can put your cursor over the black question mark “?” in the console to see an explanation of each attribute control.
Autocomplete Controls allow you to change the behavior of your auto-complete settings, including Auto learning or importing your own suggested list of terms. The suggested list of terms is not just a CSV, it follows a specific format to ensure that the terms are weighted correctly. Applying a pre-build BigQuery schema to a new dataset is the best place to begin with custom autocomplete term lists.
Models
Models are applicable to Recommendations AI only. By default, you can only have 10 continuously training models and a total of 20 models. This default quota is to protect your cloud bill, as model training charges a separate fee.
A model can only be associated with a single Recommendations AI serving configuration.
There are seven pre-built models for Recommendations AI at the time of this writing, they are:
Recommended for you
Others you may like
Frequently bought together
Similar items
Buy it again
Page-level optimization
On Sale
Each of these models can also be configured with a business objective. We’re biased at Nimstrata, but we believe the algorithm training abilities of these models and the ability to pick a business objective is what sets Google Cloud’s Product Discovery AI service miles apart from the competition. Business objectives include:
Click-through rate (CTR)
Conversion rate (CVR)
Revenue per session
Each model has different data volume requirements and you’ll notice that many of the requirements rely on significant amounts of user event data. Correctly importing historical user event data and recording real-time user events is just as important as your product catalog data.
User events capture activities on your website such as page views, adding items to a cart, and completed purchases. These events are at the core of the algorithm training model to successfully recommend products to new and existing users.
You can also select how often a model is tuned, choosing between every three months and manual.
New Retail API users are unlikely to stray far from the default_search serving configuration to deliver search results. However, you can create several serving configurations. For example, if you want a unique search experience on your mobile app, creating a new Search and Browse serving configuration and assigning it different Controls allow you to do so.
Summary
This article provided an explanation for the most common configurations inside of Google Cloud's Retail dashboard. If you are having trouble displaying the intended results, be sure to start with Serving Configurations and work your way into individual controls and models that may be affecting the output.
