Catalogs and catalog information

This page provides best practices for creating your catalog information and populating your catalog data.

Overview

The catalog data you import into Recommendations AI has a direct effect on the quality of the resulting model, and therefore on the quality of the predictions Recommendations AI provides. In general, the more accurate and specific catalog information you can provide, the higher quality your model.

Your catalog should be kept up to date. You can upload catalog changes as often as needed; ideally, every day for catalogs with a high rate of change. You can upload (patch) existing product items; only the changed fields will be updated. There is no charge for uploading catalog information. For more information, see Keeping your catalog up to date.

Product items

The catalog is a collection of product objects. Use the information below to decide what information you will provide when you upload your catalog information.

To see a complete list of all product fields, see the product reference page.

Required product information

The following fields are required; you must provide values for them when you create product items in your catalog. They should also correspond with the values used in your internal product database, and should accurately reflect the product represented, because they are included in training your models.

Field	Notes
`name`	The full, unique resource name of the product. Required for all Product methods except for `import`.
`id`	The product ID used by your product database. The ID field must be unique across your entire catalog. The same value is used when you record a user event, and is also returned by the `predict` method.
`title`	Product title from your product database. A UTF-8 encoded string. Limited to 1250 characters.

Optional catalog information

These fields are not required. However, all catalog information you provide can be used to improve the quality of the model, prediction results, or prediction metrics. Be sure to provide as many fields as possible.

Field	Notes	Used for
`type`	The type of the product. This field is output-only. The possible values are: `PRIMARY` `VARIANT` `COLLECTION` The default value is `PRIMARY` if unspecified.
`primaryProductId`	The ID of the variant group. For `PRIMARY` products, this field must be empty or set to the same value as `id`. For `VARIANT` products, this field is required. This field must be enabled by the Retail API before it can be used.	SKU grouping
`categories[]`	A list of category hierarchies the product belongs to. Categories should be taken from your company's product classification, and should accurately describe the product. You must provide at least one category; multiple categories are also accepted. Subcategories are grouped together in square brackets. For example, suppose a footwear product belongs to both `"Shoes & Accessories" -> "Shoes"` and `""Sports & Fitness > Athletic Clothing > Shoes"]`. Its categories field would be: categories: [ ["Shoes & Accessories", "Shoes"], ["Sports & Fitness > Athletic Clothing > Shoes"] ]
`description`	Product item description from your product database. A UTF-8 encoded string. Limited to 1250 characters. Highly encouraged.
`attributes`	A place to provide information about your product that is not included in other fields, and that you believe could help improve model quality. Highly encouraged.	Model quality
`tags`	The `tags` field enables you to filter your prediction results. Tag values must consist only of alphanumeric characters, underscores, and dashes. Updates to tag values can take up to 24 hours before they can be used to filter prediction results.	Recommendation filtering
`priceInfo`	An object with information about your product's pricing.
`priceInfo.currencyCode`	The three-character alphabetic ISO-4217 code for the currency used in the `price` and `cost` fields of the product.
`priceInfo.price`	The price of your product.
`priceInfo.originalPrice`	Price of the product without any discount. If zero, by default set to be the price.
`priceInfo.cost`	When you provide the cost of a product, it increases the accuracy of the prediction metrics, because the costs you provide are subtracted from the price to calculate the profit.	Recommendation metrics
`priceInfo.cost`	When you provide the cost of a product, it increases the accuracy of the prediction metrics, because the costs you provide are subtracted from the price to calculate the profit.	Recommendation metrics
`availableTime`	The timestamp for when the product becomes available.
`availability`	You can use this field to provide stock information about the product. The possible values are: `IN_STOCK` `OUT_OF_STOCK` `PREORDER` `BACKORDER` The default value is `IN_STOCK`.	Model quality
`availableQuantity`	How many of this item are available. A value of zero does not change the `availability` field to `OUT_OF_STOCK`, nor does it prevent Recommendations AI from recommending this item.
`images`	An object with up to 300 images for the product. Images aid in rendering recommendation results, and prediction preview uses image URLs to display the images when you preview a model's prediction results in Cloud Console.	Model quality
`images.uri`	The URI of the image. Required for `images`.	Model quality
`images.height`	The height of the image in pixels.	Model quality
`images.width`	The width of the image in pixels.	Model quality

Using product levels

When you import your catalog for the first time, you must specify whether you are providing only primary items, or primary items as well as their variants.

Primary items are what the Retail API returns in prediction results. These can be individual (SKU-level) items, or groups of similar items (SKU groups). By default, the Retail API is configured for importing only primary items.
Variant items are versions of a primary product. Variants can only be individual (SKU-level) items. For example, if the primary product is "V-neck shirt", variants could be "Brown v-neck shirt, size XL" and "White v-neck shirt, size S". Primaries and variants are sometimes described as "parent" and "child" items. Importing variants is optional.

To determine the best product level choices for your implementation, you will need to review your catalog data and your website logic. What item IDs are available to you when you capture user event data? What item IDs would be most effective to be returned with predictions? How do those IDs compare and relate to each other?

Use the appropriate steps, depending on whether you are importing from Merchant Center or not:

Determining your product levels for importing from Merchant Center

When you import catalog data from Merchant Center, the Retail API uses ingestionProductType to help identify whether to upload them as primaries or variants, and the merchantCenterProductIdField field to specify whether to use the Merchant Center offer_id or item_group_id as the product ID.

Review your catalog data and your website logic to answer the following questions:

Do I have both primaries and variants in my catalog?
If so, what level of item will I have available when I capture user event data?
What type of items do I need returned with my predictions?

Determine if:

Your catalog has only one level of items. This can mean that either:
- All of your products and events are at the SKU level, and you want SKU-level predictions.
- All of your products and events are at the group level, and you want group-level predictions.
If so, import with only primary items. This is the default import setting.
You want group-level (primary) predictions, but your Merchant Center products are SKU-level. In this case, your import decision depends on how your events are captured.
1. Your events are captured at the group level. If so, use the following settings during import:
  - ingestionProductType set to primary (default)
  - merchantCenterProductIdField set to itemGroupId.
  Where multiple Merchant Center products have the same Merchant Center item_group_id, Recommendations AI imports only one of them as a primary product and uses the item_group_id as its product ID. Products that don't have an item_group_id can't be imported in this case. Recorded events must refer to the primary (group-level) product ID.
2. Your events are captured at the SKU level. If so, use the following settings during import:
  - ingestionProductType set to variant.
  - merchantCenterProductIdField set to offerId (default).
  Recommendations AI imports your products as variants and uses the Merchant Center offer_id as its product ID. Recorded events must refer to the variant (SKU-level) product ID.

Determining your product levels for importing without Merchant Center

Either all of your products must have a value for primaryProductId or none of them can. You cannot import catalog data with primaryProductId set for some items but not for others.

If your catalog has only one level of items, this can mean that either:
- All of your products and events are at the SKU level, and you want SKU-level predictions.
- All of your products and events are at the group level, and you want group-level predictions.
If so, import with only primary items. This is the default, recommended import setting.
If your events and products are SKU-level, you can get group-level predictions. Set ingestionProductType to variant during import.

SKU-level prediction is not supported if you have only group-level events and products.

If you plan to import catalog data from Merchant Center in the future, review your data as described for Merchant Center imports to ensure you are making the correct choice. Changing this configuration can be done only by deleting the catalog and uploading it again (see Changing product-level configuration).

Recommendations AI schema

When importing a catalog from BigQuery, use the Recommendations AI schema below to create a BigQuery table with the correct format and load it with your catalog data. Then, import the catalog.

Recommendations AI schema JSON

JSON

[
 {
   "name": "name",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "id",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "primaryProductId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "categories",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "title",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "description",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "attributes",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "key",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "value",
       "type": "RECORD",
       "mode": "NULLABLE",
       "fields": [
         {
           "name": "text",
           "type": "STRING",
           "mode": "REPEATED"
         },
         {
           "name": "numbers",
           "type": "FLOAT",
           "mode": "REPEATED"
         }
       ]
     }
   ]
 },
 {
   "name": "tags",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "priceInfo",
   "type": "RECORD",
   "mode": "NULLABLE",
   "fields": [
     {
       "name": "currencyCode",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "price",
       "type": "FLOAT",
       "mode": "NULLABLE"
     },
     {
       "name": "originalPrice",
       "type": "FLOAT",
       "mode": "NULLABLE"
     },
     {
       "name": "cost",
       "type": "FLOAT",
       "mode": "NULLABLE"
     }
   ]
 },
 {
   "name": "availableTime",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "availability",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "availableQuantity",
   "type": "INTEGER",
   "mode": "NULLABLE"
 },
 {
   "name": "uri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "images",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "uri",
       "type": "STRING",
       "mode": "REQUIRED"
     },
     {
       "name": "height",
       "type": "INTEGER",
       "mode": "NULLABLE"
     },
     {
       "name": "width",
       "type": "INTEGER",
       "mode": "NULLABLE"
     }
   ]
 }
]