Google Maps Services Python

google-maps-services-python is Google’s official Python client for the Google Maps Platform Web Service APIs. It wraps geocoding, reverse geocoding, directions, distance matrix, places, elevation, roads, timezone, and address-validation endpoints behind a single googlemaps.Client, handling authentication, request signing, retry/backoff, and rate limiting for you.

Because it’s maintained directly by Google, it tracks Maps Platform API changes closely and is the reference client referenced in Google’s own documentation, making it the default choice for Python applications that need geolocation, routing, or places data backed by Google’s data set.

What You Get

• A unified Client covering geocoding/reverse geocoding, directions, distance matrix, elevation, and timezone APIs
• Places API support for place search, details, autocomplete, and photos
• Roads API methods for snap-to-roads, speed limits, and nearest-roads lookups
• Address validation API support for verifying and standardizing postal addresses
• Built-in request signing, retry-with-backoff, and rate-limiting so callers don’t have to reimplement Google’s API quota handling

Common Use Cases

• Geocoding user-entered addresses into coordinates for a delivery or logistics application
• Computing driving/walking directions and ETAs between two points via the Directions or Distance Matrix API
• Building a places-autocomplete search box backed by the Places API
• Validating and standardizing shipping addresses at checkout using the Address Validation API

Under The Hood

Architecture - client.py implements the shared Client object handling authentication (API key or client-ID/secret signing), retries, timeouts, and rate limiting; every other module (geocoding.py, directions.py, distance_matrix.py, elevation.py, places.py, roads.py, timezone.py, geolocation.py, addressvalidation.py) is a thin, function-per-endpoint wrapper that builds request parameters via convert.py’s shared serialization helpers (e.g. formatting lat/lng pairs, waypoints, and enums into the wire format Google’s APIs expect) and calls back into the shared client. This one-client-many-modules layout keeps cross-cutting concerns (auth, retry, errors) in one place while each API surface stays independently maintainable.

Tech Stack - Pure Python with a single runtime dependency (requests>=2.20.0,<3.0), packaged with classic setup.py/setup.cfg and tested via nox (noxfile.py) across Python versions. No async variant is provided — all calls are synchronous, blocking HTTP requests through requests.

Code Quality - The tests/ directory contains 13 test modules, one per API surface, mirroring the source layout and giving direct coverage of each endpoint wrapper’s parameter serialization and response handling. exceptions.py defines library-specific exceptions (e.g. for API errors, timeouts, and over-query-limit responses) rather than surfacing raw requests exceptions, and a coverage.xml artifact in the repo indicates coverage is tracked in CI.

API Design - Usage is uniformly gmaps = googlemaps.Client(key=...) followed by gmaps.<method>(...), so switching between geocoding, directions, or places requires no new setup — only a different method call with different keyword arguments. The main friction for new users is that many parameters (place types, travel modes, region biasing) are Maps-Platform-specific enums/strings documented externally rather than as Python enums in the library itself, so effective use requires cross-referencing Google’s own API docs alongside the client’s docstrings.