{"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":"python","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":[{"wrong":"from google.cloud.retail_v2 import RetailServiceClient","symbol":"RetailServiceClient","correct":"from google.cloud.retail_v2 import RetailServiceClient"}],"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,"search_vec":"'2.10.0':75 'ai':27,85 'ai-pow':26 'allow':13 'api':22,24,69 'break':62 'broader':45 'brows':39 'chang':63 'client':9 'cloud':2,7,20,48,78 'commerc':33,82 'current':72 'develop':14 'e':32,81 'e-commerc':31,80 'experi':40 'featur':58 'frequent':53 'gcp':86 'googl':1,6,19,47,77 'google-cloud':76 'google-cloud-python':46 'google-cloud-retail':5 'includ':34 'interact':16 'librari':10 'minor':61 'monorepo':50 'new':57 'occasion':60 'often':55 'part':42 'person':35 'power':28 'provid':25 'python':12,49,66 'receiv':52 'recommend':36,83 'retail':3,8,21,79 'revis':70 'search':37,84 'solut':29 'specif':65 'updat':54 'version':67,73","created_at":"2026-04-16T18:48:03.886660+00:00","updated_at":"2026-04-16T18:48:03.886660+00:00","problems":{"verify_error":"Traceback (most recent call last):\n  File \"<string>\", line 1, in <module>\nImportError: cannot import name 'RetailServiceClient' from 'google.cloud.retail_v2' (/tmp/tmp59us20yo/venv/lib/python3.12/site-packages/google/cloud/retail_v2/__init__.py). Did you mean: 'CatalogServiceClient'?"},"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.10.0","cli_name":"","cli_version":null,"type":"library","homepage":"https://cloud.google.com/retail/docs","github":"https://github.com/googleapis/google-cloud-python","docs":null,"changelog":null,"pypi":"https://pypi.org/project/google-cloud-retail/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["gcp","ai-ml","llm-agents"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"import_fail","verified_at":"2026-07-03","last_verified":"2026-07-03","next_check":"2026-07-10","install_tag":null}}