Managing catalog information

This page describes how to manage your catalog information after you have imported it into Recommendations AI. You can read, write, and delete catalog items.

To keep your catalog up to date as your catalog information changes, you import your catalog the same way as the very first time. For help with importing your catalog, see Importing catalog information.

Uploading a single catalog item

curl command

You create a single catalog item by using the catalogitems.create REST method.

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data '{
    "id": "product-id",
    "languageCode": "en",
    "title": "product-title",
    "description": "product-description",
    "productMetadata": {
        "currencyCode": "USD",
        "exactPrice": {
            "displayPrice": "9.95"
        },
        "canonicalProductUri": "https://www.example.com/757997/goldfield-nevada-columbia-hotel/",
        "images": [
            {
                "uri": "https://www.example.com/images/set529/card00207_fr.jpg",
                "height": 390,
                "width": 600
            },
            {
                "uri": "https://www.example.com/images/set529/thumbs/card00207_fr.jpg",
                "height": 162,
                "width": 250
            }
        ],
        "stockState": "IN_STOCK",
        "availableQuantity": 1
    },
    "categoryHierarchies": [
        {"categories": ["US State & Town Views", "Nevada", "Goldfield"]},
        {"categories": ["More Topics", "Casinos & Gambling"]},
        {"categories": ["More Topics", "Hotels"]},
        {"categories": ["New Additions"]}
    ],
    "itemAttributes": {
        "categoricalFeatures": {
            "addDate": {"value": ["2018-12-26"]},
            "city": {"value": ["Goldfield"]},
            "state": {"value": ["NV"]},
            "county": {"value": ["Esmeralda"]},
            "publisher": {"value": ["Gray News Co."]},
            "type": {"value": ["Postcard"]},
            "era": {"value": ["Divided Back"]},
            "condition": {"value": ["unused"]}
        },
        "numericalFeatures": {
            "width_in": {"value": ["5.5"]},
            "height_in": {"value": ["3.5"]}
        }
    },
    "tags": ["spring-sale"]
}' \
 "https://recommendationengine.googleapis.com/v1beta1/projects/[PROJECT_ID]/locations/global/catalogs/default_catalog/catalogItems"

If the request is successful, the catalogItem object is returned.

Updating catalog information

As your product catalog changes, you can refresh your catalog by uploading changes in products such as new products, prices, and stock status in real time. You can upload only products that have been added or changed; you do not need to reload your entire catalog.

curl command

You update catalog information by using the patch method.

The following example updates the title for a specific catalog item:

curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data "{ "title": "new-title-value" }" \
    "https://recommendationengine.googleapis.com/v1beta1/projects/[PROJECT_ID]/locations/global/catalogs/default_catalog/catalogItems/product-id?updateMask=title"

Deleting catalog information

Although Recommendations AI provides a way to delete catalog items, keep in mind that if you record a user event that relates to a catalog item that has been deleted, Recommendations AI cannot process the user event properly and it might be deleted. In addition, including historical catalog data improves the quality of your model and is critical for prediction performance.

You should set the stockState of obsolete catalog items to OUT_OF_STOCK rather than deleting them.

curl command

You delete a catalog item by using the delete method, replacing [CATALOG_ITEM_ID] with the ID of the item you want to delete.

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    "https://recommendationengine.googleapis.com/v1beta1/projects/[PROJECT_ID]/locations/global/catalogs/default_catalog/catalogItems/[CATALOG_ITEM_ID]"

Listing catalog information

After you have uploaded your catalog information, you can list your catalog items, or retrieve a single catalog item.

Listing catalog items

curl command

You list your catalog items by making a GET request to the catalogitems endpoint. You can also apply query parameters, as shown in the following example:

curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"  \
     -H "Content-Type: application/json; charset=utf-8" \
    "https://recommendationengine.googleapis.com/v1beta1/projects/[PROJECT_ID]/locations/global/catalogs/default_catalog/catalogItems?pageSize=2"

You should see output similar to the following:

{
    "catalogItems": [
        {
            "id": "1234",
            "categoryHierarchies": [
                {
                    "categories": [
                        "Electronics",
                        "Computers & Tablets"
                    ]
                },
                {
                    "categories": [
                        "Laptops"
                    ]
                }
            ],
            "title": "Awesome Laptop",
            "description": "Arguably the best laptop",
            "languageCode": "en",
            "tags": [
                "some_tag_1",
                "some_tag_2"
            ],
            "productMetadata": {
                "exactPrice": {
                    "displayPrice": 47.99,
                    "originalPrice": 50.99
                },
                "currencyCode": "USD",
                "availableQuantity": "5000",
                "canonicalProductUri": "https://some.awesome.product_page",
                "images": [
                    {
                        "uri": "https://product.image.url",
                        "height": 120,
                        "width": 120
                    }
                ]
            }
        },
    ],
    "nextPageToken": "1516870376-233"
}

Retrieving a catalog item

curl command

You retrieve a catalog item by making a GET request to the catalogitems endpoint, replacing [CATALOG_ITEM_ID] with the ID of the catalog item you want to retrieve:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"  \
    "https://recommendationengine.googleapis.com/v1beta1/projects/[PROJECT_ID]/locations/global/catalogs/default_catalog/catalogItems/[CATALOG_ITEM_ID]"

You should see output similar to the following:

{
    "id": "12345",
    "categoryHierarchies": [
        {
            "categories": [
                "Electronics"
            ]
        }
    ],
    "title": "Title 1516863121-922449",
    "description": "Description 1516863121-922449",
    "languageCode": "en",
    "productMetadata": {
        "exactPrice": {
            "displayPrice": 1000,
            "originalPrice": 100
        },
        "currencyCode": "USD",
        "availableQuantity": "1",
        "canonicalProductUri": "example.com/myproduct"
    }
}

Viewing aggregated information about your catalog

You can view aggregated information about your catalog and preview uploaded catalog items in the in the Catalog tab on the Recommendations AI Data page.

Recommendations AI Catalog Import Data

Rejoining catalog events

You can rejoin catalog events by making a GET request to the userEvents:rejoinCatalog endpoint.

Note that this uses the v1alpha1 version of the Recommendations AI API. You must have the Recommendations AI Admin IAM role.

curl command

Set catalog_rejoin_type according to the types of events you're rejoining:

  • 0: Trigger rejoin for both joined and unjoined events.
  • JOINED_EVENTS: Trigger rejoin for only joined events.
  • UNJOINED_EVENTS: Trigger rejoin for only unjoined events.

The following example triggers a rejoin for only unjoined events:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data "{
     'catalog_rejoin_type': 'UNJOINED_EVENTS'
     }" \
    "https://recommendationengine.googleapis.com/v1alpha/projects/[PROJECT_ID]/locations/global/catalogs/default_catalog/eventStores/default_event_store/userEvents:rejoinCatalog"

Changing catalog item level configuration

When importing a catalog, you must specify if the catalog items are masters or variants. If these catalog levels change or were specified incorrectly, use the procedure below to correct their configuration. You must have the Recommendations AI Admin IAM role.

  1. Make sure no imports are occurring while you reconfigure the catalog item levels. This ensures data does not get uploaded at the wrong level.

  2. Determine what type of catalog item levels you plan to change:

    • Event catalog item levels (e.g. changing Variant/Master to Master/Master): Proceed to step 3.
    • Predict item levels only (e.g. changing Variant/Master to Variant/Variant): Proceed to step 4.
  3. If you plan to change event catalog item levels, purge all user events using the purge method.

  4. Delete all catalog items. See deleting catalog items.

  5. Change the catalog item level configuration.

    This procedure depends on how you import. Follow the appropriate procedure in Importing Catalog Information to set the catalog levels to their new configuration.

  6. Finish importing the new catalog with the modified level configuration, using your chosen procedure in Importing Catalog Information.

  7. If you did not purge your events, rejoin both joined and unjoined user events.

  8. Tune all existing models.

    To tune a model, go to the Models page, click the model name to view its details page, then click Manual Tune in the button bar.

    Go to the Recommendations AI Models page