Important: Recommendations AI has migrated to the Retail API, which is now generally available.

The Recommendations AI API (service endpoint and this documentation set remain available, but they will no longer be updated. We recommend migrating your recommendations to the Retail API (service endpoint See the new documentation:

Frequently asked questions

Have other challenges or don't see your issue outlined below? Please report a bug or request a feature and join the cloud-recommendations-users Google group or Stack Overflow discussions.


Do you have client libraries for the Recommendations AI API, or more sample code?

Yes. You can see the client libraries guide for Recommendations AI here for setup and reference information for each library.

The Google API Discovery Service can also be used instead of raw REST calls.

Are all the recommendation models personalized?

The "Recommended for you" and "Others you may like" models make personalized recommendations when provided with user history. The "Frequently bought together" model is not personalized.

See Recommendation model types.

Will I receive personalized recommendations immediately, or will I need to wait for these to improve over time?

Recommendations improve as you collect more user history. The "Recommended for you" model shows popular products and the "Others you may like" model shows similar products based mostly on other's views. Both of these models start taking user behavior into account immediately, so it's important to send real-time events. See Recommendation model types.

User events need to be sent in real-time, or very close to real-time, for personalization to be effective. If user events are only submitted daily, or in batches throughout the day, the personalized models may not perform as well as they could if real-time events were sent.

Are you using Google user demographic data in your models?

The models only use the catalog and user event data that you provide. If you want to include demographic data, you can include these as categorical or numerical features in the user event FeatureMaps. This data is not currently used by the models, but it may be used in the future.

Do not include personally identifiable information (PII) such as email addresses or usernames. We suggest you anonymize demographic data, such as by hashing the values or using group IDs.

Can I make recommendations based on the event history of a group of users, rather than a single user's history?

Currently, recommendations are based on a single visitor ID or user ID. You would need to make individual requests and then combine the results to base recommendations on a group's history. If the users have common metadata attributes, you could use group IDs as user IDs to provide group-level recommendations.

I noticed that you can submit image URLs for catalog items. Do the models take into consideration the product images?

Not at this time. These fields are provided so that you can retrieve this metadata along with the returned recommendation results, in order to aid in rendering recommendation results. Prediction preview also uses image URLs to display the images when you preview a model's prediction results in Cloud Console.

My company isn't a retail ecommerce website. Can I still use Recommendations AI for predicting x,y,z?

We've had customers use Recommendations AI for content recommendations, video streaming and gaming, and other use cases. However, our content and experience is currently designed with the retail ecommerce use case in mind and may not be suited for other use cases yet.

Can I place recommendations on any page of my site?

Yes, but the models are each designed for specific use cases and may work best on certain pages. See Recommendation model types.

"Frequently bought together" and "Others you may like" require item IDs, so they should be used for recommendations using, for example, a product ID or items in a cart. "Frequently bought together" typically works best on add-to-cart or checkout pages, while "Others you may like" works best on product detail pages. "Recommended for you" could be placed on any page, since it only requires a visitor ID as input, but it is designed as a home page placement.

Can I use Recommendations AI for recommendations in email newsletters?

Yes. This can be done by making a call to the API with a visitor ID or user ID, then incorporating the results into an email template. If you want the items to be loaded dynamically at email-read time, you would need to use an intermediary endpoint, such as a Google Cloud Function, to send the predict request. The API only provides a list of ordered product IDs and metadata, so you will also need to write your own code to render the image results.

Can I use Recommendations AI for other non-web use cases (mobile apps, kiosks)?

Yes. You can set up an endpoint (eg. Google Cloud Function) to get results for the app. You also need a similar mechanism to send real-time events.

I don't have 3+ months of event data. Can I still use Recommendations AI? Can I add more data at a later point?

If you can record sufficient traffic for real-time events, recent data can be used for training. If you have additional data available at a later date, you can upload it after the initial model training. The newly backfilled data gets incorporated into the models during daily retraining. However, if the data is significantly different than the events that were used for the initial training, the models may need to be retuned.

The models work best with at least three months of product page views, home page views, and add-to-cart events for all model, and ideally one to two years of purchase history for the "Frequently bought together" model.

One to two weeks of detail page views can be enough to start training "Others you may like" and "Recommended for you" models, while "Frequently bought together" usually requires more since there are typically fewer purchases per day than there are page views. Model quality can be significantly improved with more data; the minimum amount may not produce optimal results. A year's worth of purchases, for example, allows the models to better take advantage of seasonality and trends.

Can I recommend categories along with items?

Recommendations AI currently returns product recommendations only, but you can get the categories for each product returned as part of the results.

Can I deploy Recommendations AI on a website without modifying my existing server-side code?

This is possible, but you still need an endpoint to handle the AJAX request because the Recommendations AI predict API is authenticated and uses a POST request. This can be done using a Google Cloud Function, App Engine, or a similar service.

Do you have integrations for uploading data from SQL databases or other systems, such as BigQuery?

Yes. For events, there is sample code that reads from BigQuery. See a Google Analytics sample dataset for BigQuery.

I think feature x,y,z would be great. Can you add this to Recommendations AI?

We'd love to hear from you. Feature requests can be submitted through your account team, Google Support, or the issue-tracker.

Catalogs and catalog items

How does Recommendations AI handle cold starts for new catalog items?

For items that do not have any purchase history, we make recommendations based on similar items. In these cases, it is especially important to have good product titles, categories, and descriptions defined in the catalog.

For cold-start users (visitors with no history) the models start with the most popular general items, and become more personalized in real time as more user events are received.

See Catalogs and catalog information and the catalog item reference page.

Can I use my Merchant Center catalog for recommendations?

Yes, you can export a Merchant Center catalog to BigQuery using the Merchant Center Data Transfer Service. Then we can read the catalog directly from BigQuery. See Importing catalog data from Merchant Center.

How else can I import my catalog?

  • BigQuery: Import directly from a table or view.
  • Cloud Storage: Import using text files with one JSON catalog item per line.
  • Inline import: Import with an API call, using text files with one JSON catalog item per line.
  • Create catalog items: Use the catalogItems create method.

How can I keep my catalog updated? How often does the catalog need to be updated?

See Keeping your catalog up to date.

If you have an easy way to get notified of catalog changes (such as via Pub/Sub, message queue, events, etc.) then you can update the catalog in real-time using the import or create API methods.

Otherwise, we recommend updating your catalog daily. You can do a full update from Cloud Storage or BigQuery, or an incremental update (i.e., new and changed items only).

For example, Cloud Scheduler can be used to make a daily BigQuery import call.

Are there minimum and maximum catalog sizes?

There is no minimum, but very small catalog sizes (< 100 items) may not see much benefit from recommendations due to there being very few different products to recommend.

If you have a large catalog with more than 10 million items, using it requires approval from Google Support.

See the documentation for default quotas and limits.

My company operates websites in multiple countries. Should I use one catalog for all of my data?

It is usually best to have just one catalog with all items. Events must be submitted all using a single currency. There is currently no way to have multiple catalogs within the same project, but recommendations can be filtered to a specific site using filter tags.

If the catalogs are considerably different between sites and the user event patterns are also quite different, we typically recommend having a separate project for each site with their own independent recommendations.

However, if there are similar sites with low traffic compared to the main site, it may be best to use a single catalog if there are not enough events to produce high quality models for all individual sites.

To use a single catalog, the catalog item IDs should be consistent, i.e., the same product should have a single item ID on all sites so that there is no duplication of products within the catalog.

Filter tags may take up to 24 hours to update, so if there are country-specific availability (out of stock) requirements, they normally need to be handled by a business rule that filters out the results after the predict response.

I have multiple websites with a shared catalog or similar items. Can Recommendations AI provide cross-site recommendations?

We typically recommend using a single catalog like this only if there is significant overlap between the sites; they should share many or all of the same products. Then, as with multi-region sites, you can use filter tags to return only site-specific items for a particular predict call.

If the sites do not share many, or any, catalog items, or have very different usage patterns, then multiple catalogs should be used. Using multiple catalogs requires a separate GCP project for each catalog.

Does including more metadata improve the model? Does the model consider fields x,y,z?

See Required catalog item information for required fields.

Other metadata fields are optional (eg. images, itemAttributes). They may be used for prediction preview, results analysis, training, and tuning. We recommend including useful attributes such as color, size, material, etc. These fields can be returned as part of predict results by specifying returnCatalogItem:true, so they can be useful for rendering results. Images and item attributes are used for prediction preview in Cloud Console.

Which attributes of a catalog item are used as inputs of model training?

A combination of both user behavior and product attributes is used. The primary fields used are ID, title, category hierarchy, price, and URL. You can include other key-value attributes that might be useful in the FeatureMap.

Image URLs are more of a convenience feature; you can return this metadata as part of the prediction results by specifying returnCatalogItem:true, which can save an extra call to retrieve this information. Having image URLs also allows prediction preview to display the images when you preview a model's prediction results in Cloud Console.

What languages are supported for my catalog items?

See the languageCode field of the CatalogItem object for an an up-to-date list of supported language codes. For other languages, contact your Google account manager.

My catalog has master/variants or parent/child SKUs. Are these supported?

Yes. This would be similar to the item_group_id in Merchant Center. You need to determine how you want to get recommendations back (at the parent or child level) and if the events are at the parent or child level.

See Using catalog levels for more about catalog levels.

Determine and set your correct catalog level before sending any items or events. The catalog level can be changed, but requires rejoining the items and retuning the models.

User events

Can I integrate with Google Analytics 360?

You can use historical data from Google Analytics 360 (GA360). Similar to Merchant Center data, GA360 data can be exported to BigQuery, and then Recommendations AI can read the events directly from BigQuery.

For real-time events, we recommend integrating tracking pixels with Google Tag Manager, because events are delayed from GA360.

How do I feed events into Recommendations AI?

Users typically import historical events using Cloud Storage or API import, then stream real-time events using the JavaScript Pixel or Tag Manager tag on the live site, or via the write method on the backend.

What if I can't send all of the user event types listed as required for a model? What are the minimum event types needed for each model?

Each model and optimization objective has slightly different requirements. See the User event data requirements.

Model performance is typically better when there are more events per catalog item. For sites with large amounts of traffic and smaller catalogs, you may be able to start with a smaller volume of historical events, but still typically need at least a few weeks of historical data as well as real-time events going forward.

I have add-to-cart and purchase-complete events that don't have a value for revenue or quantity. What should I submit?

If you don't have a value for quantity, you can pass a default value of 1 without affecting model results. Items should always have displayPrice set (this can be whatever is shown to the user, such as a discount price). The originalPrice and cost are optional.

My data only covered limited types of events. Can I still use Recommendations AI?

See User event data requirements for the minimum data requirements of each model type.

Prediction results

Is there a limit to the number of predictions I can return?

By default, a prediction request returns 20 items in the response. This can be increased or decreased by submitting a value for pageSize.

If you need to return more than 100 items, contact Google Support to increase the limit. Note, however, that returning more than 100 items can increase response latency.

Am I able to view the reasons why a model made a specific product recommendation?

Not currently.

Can I download and cache prediction results?

Since prediction results improve in real-time in response to user activity on your site, we don't recommend using cached predictions. The models retrain daily to incorporate changes to your catalog and react to new trends in user events, which also changes results.

I need to rerank the returned recommendations based on a business rule. Is this supported?

Yes. But while you can re-rank the returned recommendations based on your business rules, be aware that re-ordering or filtering recommended results can reduce the overall effectiveness of the model at achieving the optimization goal that you chose.

Price reranking orders relevant high-priced items first in the set of recommendations returned and is available as a built-in customization for the "Others you may like" and "Recommended for you" models.

See Price reranking.

Are there restrictions on the number of filter tags that I can create and use?

There are no hard limits on the number of unique tags that you can create or use. However, the system is not designed to handle many filter tags per item. We recommend keeping filter tags limited to a maximum of 10 per catalog item if possible. More than 10 values can be used across the entire catalog; this is a per-item limit. The limit for total tags (the total sum of all per-item tag counts) is 100,000,000.

See the documentation for Recommendations AI quotas and limits.


I've uploaded my catalog & events, but I'm still getting this response when I call the predict API: "Recommendation model is not ready. You can set 'dryRun' to true in prediction request for integration purpose, which returns arbitrary catalog items from your Catalog (please DO NOT use this for production traffic)."

This usually means that your model has not finished training. If it has been more than 10 days since you created the model and you are continuing to get this response, please contact Support.

How long does it take to train a model?

Initial model training and tuning takes 2-5 days to complete. Subsequently, models are automatically retrained daily unless disabled. See Pausing and resuming training for a model.

Can I download or export the model?


Can I use models I created in an existing project in a new project?

No. You need to create and retrain the models in the new project.

I want to use a model for my category pages. Can I do that?

Yes. "Recommended for you" is useful on category pages. A category page is similar to a home page, except that you display only items from that category. You can achieve this using a standard Recommended for you model with filter tags. For example, you can add customized filter tags (corresponding to each category page) to the items in your catalog. When you send the prediction request, set the user event object as category-page-view and specify a specific category page's tag in the `filter` field. Only recommendation results matching the requested filter tag are returned. Diversity should be disabled in this use case, because diversity can conflict with category-based filter tags.

Recommendations AI Cloud Console

I purged a number of events, but the dashboard still shows the counts for those event types.

This is expected. The Cloud Console dashboard shows the number of events ingested over a certain period of time; it doesn't show the current count or number of events.

To verify that events were deleted, use the list API for a particular time range or event type.

How can I tell if there are errors with my catalog or user events?

Most API calls for catalog item updates or user events return an error if there is a problem with syntax or the request can't be processed for some reason.

The Cloud Console dashboard shows percentage of unjoined events, which is also a useful metric to use for spotting catalog or event issues. Unjoined events (or unjoined predict calls) happen when an item ID is specified that isn't in the catalog. This usually means the catalog is out of date and the new or changed catalog items need to be uploaded, but it can also be due to bad item IDs being passed. Check your requests to make sure the item IDs map correctly to the catalog, then check the catalog you uploaded to be sure the items exist.

Cloud Monitoring and Cloud Logging can be used to monitor the status of events. For example, you can receive alerts if there are no events over a given period of time, or if predict calls drop below a certain threshold.

Why do my recommendation placements show as inactive? How do I activate them?

In order to use recommendation placements, you first need to submit catalog and user event data to train the corresponding model. Once a model has been trained, the dashboard indicates that the model is ready to query.