googlemaps

library4.10.0pypypi✓ verified 23d ago

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.

gcp http-networking

pip install googlemaps

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GOOGLEMAPS

googlemaps

gcppythonv4.10.0

Install

4.7s avg

Import

365ms

Disk

20MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v4.10.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.376s · 22.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 4.7s · import 0.354s · 23MB

20MB installed

● package 20MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Client

✓ from googlemaps import Client

✗ import googlemaps

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}'.")

Debug

Known issues

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

affects: All versions

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

affects: All versions

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

affects: All versions of `googlemaps` when interacting with underlying Google Maps Platform API versions that have breaking changes (e.g., Geocoding API v3 to v4).

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

affects: All versions

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

affects: Versions < 4.7.2 had Python 3.5 issues. Other Google Maps client libraries (different packages) may have higher Python requirements for all versions.

Upgrade

Version history

4.10.0latest on PyPI · released Jan 26, 2023

Audit

Dependencies

requestsrequiredUsed for HTTP requests, implicitly required for timeout and connection management. Version >=2.4.0 is required for some client features.

Agent activity

22 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/googlemaps/google-maps-services-python ↗

packagehttps://pypi.org/project/googlemaps/ ↗

homepagehttps://developers.google.com/maps ↗