Google Maps Places API Client Library

Common errors

• ModuleNotFoundError: No module named 'google.maps.places_v1'

  cause The `google-maps-places` library is either not installed, or the import path is incorrect.
  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`.

• google.api_core.exceptions.PermissionDenied: 403 The caller does not have permission

  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.
  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.

• google.api_core.exceptions.InvalidArgument: 400 Request contains an invalid argument.

  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.
  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.

Warnings

• gotcha 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`.
  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.
• breaking 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.
  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.
• gotcha 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.
  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.

Install

• pip install google-maps-places Install stable version

Imports

• PlacesClient
  wrong:

  from google.cloud.places import PlacesClient

  correct:

  from google.maps.places_v1 import PlacesClient

  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.

Quickstart

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.

import os
from google.maps.places_v1 import PlacesClient
from google.api_core.exceptions import GoogleAPIError

# Ensure your environment is authenticated. For local development, run:
# `gcloud auth application-default login`
# Or set GOOGLE_APPLICATION_CREDENTIALS environment variable to a service account key file.
# The Google Maps Places API also needs to be enabled for your GCP project.

try:
    # Initialize the client. It uses Application Default Credentials by default.
    client = PlacesClient()

    # Construct a request to find places from a text query.
    # Specify 'fields' to control the data returned and reduce costs.
    request = PlacesClient.FindPlaceFromTextRequest(
        text_query="restaurants near Times Square, New York",
        fields=["id", "displayName", "formattedAddress", "rating"],
        language_code="en", # Optional: influence results language
        region_code="us"    # Optional: bias results towards a region
    )

    response = client.find_place_from_text(request=request)

    if response.places:
        print("Found Places:")
        for place in response.places:
            print(f"- Name: {place.display_name.text}")
            print(f"  Address: {place.formatted_address}")
            print(f"  Rating: {place.rating if place.rating else 'N/A'}")
            print(f"  ID: {place.id}")
    else:
        print("No places found for the query.")

except GoogleAPIError as e:
    print(f"An API error occurred: {e}")
    print("Common causes: Places API not enabled, incorrect authentication, or rate limits.")
except Exception as e:
    print(f"An unexpected error occurred: {e}")