{"id":9788,"library":"google-maps-places","title":"Google Maps Places API Client Library","description":"The `google-maps-places` client library provides a Python interface for the Google Maps Places API (v1). It allows developers to programmatically access place information, including searches, details, and photos. This library is part of the broader `google-cloud-python` ecosystem and currently at version `0.8.0`, implying it's in a preview or early access stage. Google Cloud client libraries typically receive frequent updates for bug fixes and new features, often on a weekly or bi-weekly basis for individual sub-libraries.","status":"active","version":"0.8.0","language":"en","source_language":"en","source_url":"https://github.com/googleapis/google-cloud-python/tree/main/packages/google-maps-places","tags":["google cloud","places api","maps","geolocation","geocoding","points of interest"],"install":[{"cmd":"pip install google-maps-places","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core functionality for Google APIs, including gRPC transport.","package":"google-api-core","optional":false},{"reason":"Handles authentication to Google Cloud services, including Application Default Credentials (ADC).","package":"google-auth","optional":false},{"reason":"Protobuf message serialization/deserialization.","package":"proto-plus","optional":false}],"imports":[{"note":"The Places API client is namespaced under `google.maps.places_v1`, not `google.cloud.places` or `google.maps.places` due to its specific API version and differentiation from other Google Cloud services.","wrong":"from google.cloud.places import PlacesClient","symbol":"PlacesClient","correct":"from google.maps.places_v1 import PlacesClient"}],"quickstart":{"code":"import os\nfrom google.maps.places_v1 import PlacesClient\nfrom google.api_core.exceptions import GoogleAPIError\n\n# Ensure your environment is authenticated. For local development, run:\n# `gcloud auth application-default login`\n# Or set GOOGLE_APPLICATION_CREDENTIALS environment variable to a service account key file.\n# The Google Maps Places API also needs to be enabled for your GCP project.\n\ntry:\n    # Initialize the client. It uses Application Default Credentials by default.\n    client = PlacesClient()\n\n    # Construct a request to find places from a text query.\n    # Specify 'fields' to control the data returned and reduce costs.\n    request = PlacesClient.FindPlaceFromTextRequest(\n        text_query=\"restaurants near Times Square, New York\",\n        fields=[\"id\", \"displayName\", \"formattedAddress\", \"rating\"],\n        language_code=\"en\", # Optional: influence results language\n        region_code=\"us\"    # Optional: bias results towards a region\n    )\n\n    response = client.find_place_from_text(request=request)\n\n    if response.places:\n        print(\"Found Places:\")\n        for place in response.places:\n            print(f\"- Name: {place.display_name.text}\")\n            print(f\"  Address: {place.formatted_address}\")\n            print(f\"  Rating: {place.rating if place.rating else 'N/A'}\")\n            print(f\"  ID: {place.id}\")\n    else:\n        print(\"No places found for the query.\")\n\nexcept GoogleAPIError as e:\n    print(f\"An API error occurred: {e}\")\n    print(\"Common causes: Places API not enabled, incorrect authentication, or rate limits.\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\n","lang":"python","description":"This quickstart demonstrates how to initialize the `PlacesClient` and perform a basic `FindPlaceFromText` query. Authentication is handled by Google's Application Default Credentials (ADC), which requires prior setup (e.g., `gcloud auth application-default login` for local development or setting `GOOGLE_APPLICATION_CREDENTIALS`). The Places API must also be enabled in your Google Cloud project."},"warnings":[{"fix":"Ensure your environment is authenticated via `gcloud auth application-default login` for local development, or by setting the `GOOGLE_APPLICATION_CREDENTIALS` environment variable. For deployment on Google Cloud, credentials are usually inferred automatically. Enable the Google Maps Places API in your GCP project.","message":"Authentication for `google-maps-places` (a Google Cloud library) relies on Application Default Credentials (ADC) by default, not a direct API key parameter. Users familiar with `google-maps-services-python` or other Maps Platform SDKs might expect to pass an `api_key` argument, which is not supported directly by `PlacesClient`.","severity":"gotcha","affected_versions":"0.x.x (all versions)"},{"fix":"Pin your library version (e.g., `google-maps-places==0.8.0`) and review release notes carefully when upgrading to newer minor versions. Expect code changes to be required during upgrades.","message":"As a `0.x.x` version library, `google-maps-places` is considered pre-GA (General Availability). This means the API surface, methods, and underlying protobuf structures are subject to breaking changes between minor versions (e.g., 0.7.x to 0.8.x) without strict semantic versioning guarantees.","severity":"breaking","affected_versions":"0.x.x (all versions)"},{"fix":"Implement proper error handling, exponential backoff, and consider caching results for frequently accessed places. Monitor your API usage in the Google Cloud Console to understand and adjust quotas if necessary.","message":"The Places API, like many Google APIs, enforces quotas and rate limits. Frequent requests or large batches can quickly hit these limits, leading to `ResourceExhausted` errors.","severity":"gotcha","affected_versions":"0.x.x (all versions)"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Ensure the library is installed with `pip install google-maps-places` and verify the import statement is `from google.maps.places_v1 import PlacesClient`.","cause":"The `google-maps-places` library is either not installed, or the import path is incorrect.","error":"ModuleNotFoundError: No module named 'google.maps.places_v1'"},{"fix":"1. Go to the Google Cloud Console for your project. 2. Navigate to 'APIs & Services' -> 'Enabled APIs & Services' and ensure 'Places API' is enabled. 3. If using ADC, verify the service account or user account has the 'Places API User' role or equivalent permissions. 4. If using API keys (less common for this specific client, see warnings), ensure the key has access to the Places API and is restricted correctly.","cause":"The API key or Application Default Credentials (ADC) used do not have the necessary permissions, or the Google Maps Places API is not enabled in your Google Cloud Project.","error":"google.api_core.exceptions.PermissionDenied: 403 The caller does not have permission"},{"fix":"Carefully review the API documentation for the specific request method you are using. Pay close attention to required fields, valid enum values, and the correct format for parameters like `fields` (e.g., `['id', 'displayName.text']`). The error message usually provides more specific details about which argument is invalid.","cause":"One or more parameters in your API request (e.g., `FindPlaceFromTextRequest`, `SearchNearbyRequest`) are incorrectly formatted, have invalid values, or are missing required fields. This often happens with `fields` or geo-coordinates.","error":"google.api_core.exceptions.InvalidArgument: 400 Request contains an invalid argument."}]}