Google Maps Platform Python Client

4.10.0 · active · verified Fri Apr 10

The `googlemaps` Python client library provides a convenient interface for accessing Google Maps Platform web services, including Directions, Distance Matrix, Elevation, Geocoding, Places, Roads, and Time Zone APIs. It simplifies common tasks such as authentication, automatic rate limiting, and retries on failure. The library is actively maintained, with regular releases (current version 4.10.0) adding new features and bug fixes.

Warnings

breaking API keys are sensitive credentials. They should *always* be restricted by IP address, HTTP referrer, or application type in the Google Cloud Console to prevent unauthorized usage and unexpected billing. Avoid hardcoding keys directly in public-facing client-side code.
Fix: Configure API key restrictions in Google Cloud Console. Use environment variables (e.g., `os.environ.get('GOOGLE_MAPS_API_KEY')`) for server-side applications. Use separate, restricted API keys for different application types (e.g., server vs. web client).
gotcha While the client library includes automatic retry and rate-limiting logic, heavy usage can still exceed Google Maps Platform API quotas (e.g., 50 queries/second for Geocoding) or daily limits, leading to `OVER_QUERY_LIMIT` or `OVER_DAILY_LIMIT` errors. For Places API `next_page_token` pagination, adding a small `time.sleep()` between requests might be necessary to avoid issues, even with built-in retries.
Fix: Monitor API usage in Google Cloud Console. Implement exponential backoff for custom retry logic, if needed. For batch processing, introduce deliberate delays (`time.sleep()`) between requests to stay within per-second limits. Consider volume pricing if exceeding free tier limits.
breaking The underlying Google Maps Platform APIs (e.g., Geocoding, Places) periodically release new major versions (e.g., V4). These external API changes can introduce breaking changes in request parameters (e.g., snake_case to lowerCamelCase for V4 requests) and response field names, even if the `googlemaps` Python client library version is up-to-date. Ensure your code aligns with the specific version of the Google Maps API you are calling.
Fix: Consult Google Maps Platform migration guides (e.g., Geocoding v3 to v4 migration guide) when major API versions are released. Be aware of changes in parameter naming conventions and response structures.
gotcha The Python Client for Google Maps Services is a community-supported library and is *not* covered by the standard Google deprecation policy or support agreements. While actively maintained, critical enterprise applications may require additional internal support planning.
Fix: Be aware of the community support model. For critical applications, ensure internal expertise or a support strategy is in place.
gotcha The `googlemaps` library officially supports Python >=3.5. However, other Google Maps-related client libraries (e.g., `google-maps-places` for the *new* Places API) might have higher Python version requirements (e.g., >=3.7 or >=3.9). Also, `googlemaps` versions prior to v4.7.2 had known issues with Python 3.5 support.
Fix: For `googlemaps`, ensure Python >=3.5 (and preferably >=3.7 for broader compatibility). Verify Python version compatibility for *all* Google Maps-related client libraries you intend to use.

Install

pip install googlemaps Install stable version

Imports

Client
```
import googlemaps
gmaps = googlemaps.Client(key='YOUR_API_KEY')
```
The common pattern is to import the top-level `googlemaps` package and then instantiate `googlemaps.Client`.

Quickstart

This quickstart demonstrates initializing the Google Maps client with an API key (preferably from an environment variable) and performing a basic geocoding request to convert an address into geographic coordinates. Ensure your Google Maps API key is enabled for the Geocoding API and properly restricted.

import os
import googlemaps

# Set your API key as an environment variable (e.g., GOOGLE_MAPS_API_KEY)
api_key = os.environ.get('GOOGLE_MAPS_API_KEY', 'YOUR_API_KEY')

if api_key == 'YOUR_API_KEY' or not api_key:
    print("WARNING: Please set the GOOGLE_MAPS_API_KEY environment variable or replace 'YOUR_API_KEY' in the code.")
    exit()

gmaps = googlemaps.Client(key=api_key)

# Geocoding an address
address = "1600 Amphitheatre Parkway, Mountain View, CA"
geocode_result = gmaps.geocode(address)

if geocode_result:
    print(f"Geocoding for '{address}':")
    for result in geocode_result:
        location = result['geometry']['location']
        print(f"  Latitude: {location['lat']}, Longitude: {location['lng']}")
else:
    print(f"No geocoding results found for '{address}'.")

view raw JSON →