Registry / gcp / google-cloud-retail

google-cloud-retail

library2.10.0pypypiunverified

The `google-cloud-retail` client library for Python allows developers to interact with the Google Cloud Retail API. This API provides AI-powered solutions for e-commerce, including personalized recommendations, search, and browsing experiences. As part of the broader `google-cloud-python` monorepo, it receives frequent updates, often with new features and occasional minor breaking changes for specific Python versions or API revisions. The current version is 2.10.0.

gcp ai-ml llm-agents

pip install google-cloud-retail

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GOOGLE-CLOUD-RETAI

google-cloud-retail

gcppythonv2.10.0

Install

6.1s avg

Import

—

Disk

90MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.10.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.000s · 90.3MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 6.1s · import 0.000s · 88MB

90MB installed

● package 90MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

RetailServiceClient

✓ from google.cloud.retail_v2 import RetailServiceClient

✗ from google.cloud.retail_v2 import RetailServiceClient

This quickstart demonstrates how to initialize the `RetailServiceClient` and list the catalogs configured for a Google Cloud project. It uses environment variables for project configuration and handles potential authentication issues. Replace `YOUR_PROJECT_NUMBER` or set `GCP_PROJECT_NUMBER` environment variable.

import os from google.cloud.retail_v2 import RetailServiceClient # Ensure GOOGLE_APPLICATION_CREDENTIALS is set or gcloud is authenticated # For local development, run: gcloud auth application-default login project_number = os.environ.get('GCP_PROJECT_NUMBER', 'YOUR_PROJECT_NUMBER') # e.g., '1234567890' location_id = 'global' # or a specific region, e.g., 'us-central1' try: client = RetailServiceClient() parent = f"projects/{project_number}/locations/{location_id}" print(f"Listing catalogs for parent: {parent}") response = client.list_catalogs(parent=parent) found_catalogs = False for catalog in response: print(f" Catalog name: {catalog.name}, Display name: {catalog.display_name}") found_catalogs = True if not found_catalogs: print("No catalogs found. Ensure the project number and location are correct and the Retail API is enabled.") except Exception as e: print(f"An error occurred: {e}") print("Make sure 'GCP_PROJECT_NUMBER' environment variable is set or replace 'YOUR_PROJECT_NUMBER'.") print("Also, ensure the Google Cloud Retail API is enabled for your project.")

Debug

Known issues

gotchaGoogle Cloud client libraries often use versioned imports (e.g., `_v2`, `_v2beta`). Using the wrong version or attempting to import from the root `google.cloud.retail` directly will result in an `ImportError`.

fix

Always import `RetailServiceClient` and `types` from the specific API version submodule, such as `from google.cloud.retail_v2 import RetailServiceClient, types`.

affects: All versions

gotchaMany Retail API operations (e.g., `import_products`, `tune_model`, `create_product`) are long-running operations (LROs) that return an `Operation` object. You must poll this object to check its status and retrieve the final result, as the initial call does not block until completion.

fix

After calling an LRO method, use `operation.result()` to wait for completion and retrieve the result, or `operation.done()` and `operation.metadata()` for asynchronous polling. Consult the method's documentation for the expected response type.

affects: All versions

gotchaAuthentication is typically handled automatically via `google-auth`, but requires `GOOGLE_APPLICATION_CREDENTIALS` environment variable for service accounts, or `gcloud auth application-default login` for user credentials. Failure to set this up correctly leads to `DefaultCredentialsError`.

fix

Ensure `GOOGLE_APPLICATION_CREDENTIALS` points to a valid service account key file, or run `gcloud auth application-default login` in your terminal for user-based authentication. Confirm the authenticated principal has sufficient IAM permissions for the Retail API.

affects: All versions

gotchaResource names in Google Cloud Retail API (e.g., for products, catalogs, branches) follow a specific format like `projects/{project_number}/locations/{location_id}/catalogs/{catalog_id}/branches/{branch_id}/products/{product_id}`. Incorrectly formatted resource names can lead to `InvalidArgument` or `NotFound` errors.

fix

Always construct resource names using the client's helper methods, such as `client.catalog_path(...)`, `client.product_path(...)`, or carefully follow the documented format for each API call.

affects: All versions

Upgrade

Version history

2.10.0latest on PyPI · released Mar 26, 2026

Audit

Dependencies

google-api-corerequiredCore library for Google Cloud API interactions, including request/response handling and exceptions.

Agent activity

40 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/googleapis/google-cloud-python ↗

packagehttps://pypi.org/project/google-cloud-retail/ ↗

homepagehttps://cloud.google.com/retail/docs ↗