{"id":9021,"library":"google-cloud-retail","title":"Google Cloud Retail","description":"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.","status":"active","version":"2.10.0","language":"en","source_language":"en","source_url":"https://github.com/googleapis/google-cloud-python/tree/main/packages/google-cloud-retail","tags":["google-cloud","retail","e-commerce","recommendations","search","ai","gcp"],"install":[{"cmd":"pip install google-cloud-retail","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core library for Google Cloud API interactions, including request/response handling and exceptions.","package":"google-api-core","optional":false}],"imports":[{"note":"The client class is typically versioned (e.g., `_v2`) and resides within the versioned submodule, not directly under the top-level package.","wrong":"from google.cloud.retail import RetailServiceClient","symbol":"RetailServiceClient","correct":"from google.cloud.retail_v2 import RetailServiceClient"},{"note":"API message types (e.g., `types.Product`, `types.Catalog`) are also found within the versioned submodule.","wrong":"from google.cloud.retail import types","symbol":"types","correct":"from google.cloud.retail_v2 import types"}],"quickstart":{"code":"import os\nfrom google.cloud.retail_v2 import RetailServiceClient\n\n# Ensure GOOGLE_APPLICATION_CREDENTIALS is set or gcloud is authenticated\n# For local development, run: gcloud auth application-default login\n\nproject_number = os.environ.get('GCP_PROJECT_NUMBER', 'YOUR_PROJECT_NUMBER') # e.g., '1234567890'\nlocation_id = 'global' # or a specific region, e.g., 'us-central1'\n\ntry:\n    client = RetailServiceClient()\n    parent = f\"projects/{project_number}/locations/{location_id}\"\n    \n    print(f\"Listing catalogs for parent: {parent}\")\n    response = client.list_catalogs(parent=parent)\n    \n    found_catalogs = False\n    for catalog in response:\n        print(f\"  Catalog name: {catalog.name}, Display name: {catalog.display_name}\")\n        found_catalogs = True\n    \n    if not found_catalogs:\n        print(\"No catalogs found. Ensure the project number and location are correct and the Retail API is enabled.\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"Make sure 'GCP_PROJECT_NUMBER' environment variable is set or replace 'YOUR_PROJECT_NUMBER'.\")\n    print(\"Also, ensure the Google Cloud Retail API is enabled for your project.\")","lang":"python","description":"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."},"warnings":[{"fix":"Always import `RetailServiceClient` and `types` from the specific API version submodule, such as `from google.cloud.retail_v2 import RetailServiceClient, types`.","message":"Google 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`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Many 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Authentication 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`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Resource 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Change the import statement to specify the API version: `from google.cloud.retail_v2 import RetailServiceClient`.","cause":"Attempting to import the client class from the top-level `google.cloud.retail` package instead of its versioned submodule.","error":"ImportError: cannot import name 'RetailServiceClient' from 'google.cloud.retail'"},{"fix":"Set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the path of your service account key file, or run `gcloud auth application-default login` in your terminal to set up user credentials.","cause":"The client library could not find valid Google Cloud credentials in the environment or user's configuration.","error":"google.auth.exceptions.DefaultCredentialsError: Could not automatically determine credentials. Please set GOOGLE_APPLICATION_CREDENTIALS or explicitly create credentials and pass them to the client."},{"fix":"Verify that the `project_number`, `location_id`, and other resource identifiers are correct and that the Google Cloud Retail API is enabled for the specified project. Check IAM permissions for the principal making the request.","cause":"The resource specified in the request (e.g., project, location, catalog, product) does not exist or the authenticated user does not have permission to access it.","error":"google.api_core.exceptions.NotFound: 404 Not Found: Requested entity was not found."},{"fix":"Carefully review the API documentation for the specific method being called to ensure all required fields are present and correctly formatted. Pay close attention to resource name formats and enum values.","cause":"A field in the request payload (e.g., product data, configuration settings) does not conform to the API's requirements, or a resource name is malformed.","error":"google.api_core.exceptions.InvalidArgument: 400 Request contains an invalid argument."}]}