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

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

REST Resource: projects.locations.catalogs.catalogItems

Resource: CatalogItem

CatalogItem captures all metadata information of items to be recommended.

JSON representation
{
  "id": string,
  "categoryHierarchies": [
    {
      object (CategoryHierarchy)
    }
  ],
  "title": string,
  "description": string,
  "itemAttributes": {
    object (FeatureMap)
  },
  "languageCode": string,
  "tags": [
    string
  ],
  "itemGroupId": string,
  "productMetadata": {
    object (ProductCatalogItem)
  }
}
Fields
id

string

Required. Catalog item identifier. UTF-8 encoded string with a length limit of 128 bytes.

This id must be unique among all catalog items within the same catalog. It should also be used when logging user events in order for the user events to be joined with the Catalog.

categoryHierarchies[]

object (CategoryHierarchy)

Required. Catalog item categories. This field is repeated for supporting one catalog item belonging to several parallel category hierarchies.

For example, if a shoes product belongs to both ["Shoes & Accessories" -> "Shoes"] and ["Sports & Fitness" -> "Athletic Clothing" -> "Shoes"], it could be represented as:

 "categoryHierarchies": [
   { "categories": ["Shoes & Accessories", "Shoes"]},
   { "categories": ["Sports & Fitness", "Athletic Clothing", "Shoes"] }
 ]
title

string

Required. Catalog item title. UTF-8 encoded string with a length limit of 1 KiB.

description

string

Optional. Catalog item description. UTF-8 encoded string with a length limit of 5 KiB.

itemAttributes

object (FeatureMap)

Optional. Highly encouraged. Extra catalog item attributes to be included in the recommendation model. For example, for retail products, this could include the store name, vendor, style, color, etc. These are very strong signals for recommendation model, thus we highly recommend providing the item attributes here.

languageCode

string

Optional. Deprecated. The model automatically detects the text language. Your catalog can include text in different languages, but duplicating catalog items to provide text in multiple languages can result in degraded model performance.

tags[]

string

Optional. Filtering tags associated with the catalog item. Each tag should be a UTF-8 encoded string with a length limit of 1 KiB.

This tag can be used for filtering recommendation results by passing the tag as part of the predict request filter.

itemGroupId

string

Optional. Variant group identifier for prediction results. UTF-8 encoded string with a length limit of 128 bytes.

This field must be enabled before it can be used. Learn more.

productMetadata

object (ProductCatalogItem)

Optional. Metadata specific to retail products.

ProductCatalogItem

ProductCatalogItem captures item metadata specific to retail products.

JSON representation
{
  "costs": {
    string: number,
    ...
  },
  "currencyCode": string,
  "stockState": enum (StockState),
  "availableQuantity": string,
  "canonicalProductUri": string,
  "images": [
    {
      object (Image)
    }
  ],

  // Union field price can be only one of the following:
  "exactPrice": {
    object (ExactPrice)
  },
  "priceRange": {
    object (PriceRange)
  }
  // End of list of possible types for union field price.
}
Fields
costs

map (key: string, value: number)

Optional. A map to pass the costs associated with the product.

For example: {"manufacturing": 45.5} The profit of selling this item is computed like so:

  • If 'exactPrice' is provided, profit = displayPrice - sum(costs)
  • If 'priceRange' is provided, profit = minPrice - sum(costs)
currencyCode

string

Optional. Only required if the price is set. Currency code for price/costs. Use three-character ISO-4217 code.

stockState

enum (StockState)

Optional. Online stock state of the catalog item. Default is IN_STOCK.

availableQuantity

string (int64 format)

Optional. The available quantity of the item.

canonicalProductUri

string

Optional. Canonical URL directly linking to the item detail page with a length limit of 5 KiB..

images[]

object (Image)

Optional. Product images for the catalog item.

Union field price. Product price. Only one of 'exactPrice'/'priceRange' can be provided. price can be only one of the following:
exactPrice

object (ExactPrice)

Optional. The exact product price.

priceRange

object (PriceRange)

Optional. The product price range.

ExactPrice

Exact product price.

JSON representation
{
  "displayPrice": number,
  "originalPrice": number
}
Fields
displayPrice

number

Optional. Display price of the product.

originalPrice

number

Optional. Price of the product without any discount. If zero, by default set to be the 'displayPrice'.

PriceRange

Product price range when there are a range of prices for different variations of the same product.

JSON representation
{
  "min": number,
  "max": number
}
Fields
min

number

Required. The minimum product price.

max

number

Required. The maximum product price.

Image

Catalog item thumbnail/detail image.

JSON representation
{
  "uri": string,
  "height": integer,
  "width": integer
}
Fields
uri

string

Required. URL of the image with a length limit of 5 KiB.

height

integer

Optional. Height of the image in number of pixels.

width

integer

Optional. Width of the image in number of pixels.

Methods

create

Creates a catalog item.

delete

Deletes a catalog item.

get

Gets a specific catalog item.

import

Bulk import of multiple catalog items.

list

Gets a list of catalog items.

patch

Updates a catalog item.