googlemaps: the Python client for Google Maps Platform web services

What googlemaps solves, and who it is actually for

Google Maps Platform exposes its capabilities as a set of separate web services, each with its own URL, its own query parameters and its own response shape. Geocoding, Directions, Distance Matrix, Elevation, Geolocation, Time Zone, Roads, Places, Maps Static and Address Validation are ten distinct HTTP surfaces. If you call them directly, you own URL construction, parameter encoding, error mapping and retry logic for each one.

The googlemaps package collapses that work into a single client object with a method per capability. You construct it once with an API key, then call gmaps.geocode(...), gmaps.directions(...), gmaps.reverse_geocode(...) and so on. The README describes it plainly: "This library brings the Google Maps Platform Web Services to your Python application."

The intended audience is a Python developer building a server-side application that needs Google's map data: a delivery estimator, an address normalizer, a store locator, a routing dashboard. It is not for someone who wants map tiles in a browser, and it is not for someone who wants geocoding without a Google account. The library is a client. Every answer it returns comes from Google's servers, and the same terms and conditions apply as if you had called those endpoints yourself, which the README states explicitly.

How the client is put together

The mechanism is deliberately unglamorous. The package ships as a single googlemaps module, and setup.py declares exactly one runtime dependency: requests>=2.20.0,<3.0. There is no async layer, no connection pool of its own, no response cache, and no local data. Each method call serializes its arguments into query parameters, hands the request to requests, and parses the JSON back into Python dictionaries and lists.

That has a concrete consequence for anyone reading the code: the return values are raw API payloads, not typed objects. geocode_result is a list of dicts whose keys mirror the Geocoding API response. If Google adds a field to a response, you see it without upgrading the library; if Google renames one, your code breaks at the point where you index into it.

The one piece of behaviour the README calls out under Features is retry. "Automatically retry when intermittent failures occur. That is, when any of the retriable 5xx errors are returned from the API." That is the whole reliability story. There is no circuit breaker, no jitter configuration and no documented retry budget in the README, so if you need bounded retry counts you are reading the source or wrapping the client.

Authentication is the other axis. Each request requires an API key or a client ID, and the README is blunt about handling: "This key should be kept secret on your server." That rules out embedding it in client-side code, which is the mistake this warning exists to prevent.

Installing googlemaps and making a first real request

Installation is one pip command. The README uses the upgrade flag:

pip install -U googlemaps

After that, the package is importable as googlemaps, and the client is constructed with a key. The README's own example combines geocoding, reverse geocoding and a transit directions lookup:

import googlemaps
from datetime import datetime

gmaps = googlemaps.Client(key='Add Your Key here')

geocode_result = gmaps.geocode('1600 Amphitheatre Parkway, Mountain View, CA')
reverse_geocode_result = gmaps.reverse_geocode((40.714224, -73.961452))

now = datetime.now()
directions_result = gmaps.directions("Sydney Town Hall", "Parramatta, NSW",
                                     mode="transit", departure_time=now)

Replace the placeholder with a key generated in the Credentials page of the APIs & Services tab in Google Cloud console. Note the shape of the reverse geocode argument: a latitude, longitude tuple, not a string. Note also that departure_time takes a datetime object, not a formatted string; the library handles the conversion.

The README shows two more calls worth knowing about, because they demonstrate that the wrapper tracks newer API surfaces rather than only the classic ones. Address Validation takes a list of address lines plus a region code, and reverse geocoding can be asked for an address descriptor:

addressvalidation_result = gmaps.addressvalidation(['1600 Amphitheatre Pk'],
                                                   regionCode='US',
                                                   locality='Mountain View',
                                                   enableUspsCass=True)

address_descriptor_result = gmaps.reverse_geocode((40.714224, -73.961452),
                                                  enable_address_descriptor=True)

For further examples the README points at the tests directory in the repository rather than at a tutorial. That is a fair signal about the documentation's centre of gravity: the API reference is generated, and the tests are the working examples.

Where googlemaps is the wrong choice

The library cannot help you with cost, and cost is the first thing most teams hit. Every call is a billable Google Maps Platform request under Google's terms. Nothing in the wrapper batches, deduplicates or caches, so a loop that geocodes ten thousand addresses makes ten thousand billed calls. If your workload is a one-off bulk geocode, a batch endpoint or a paid data provider will be cheaper, and the client library is irrelevant to that decision.

The second limitation is the version story. The last tagged release in the repository is v4.10.0 from 2023-01-26, while the last push to master was 2026-07-14. That gap means the released artifact on PyPI may lag behind what is on the branch, so a method you see in the repository's tests is not automatically in the version pip installs. Check the installed version before assuming a newer API surface is available.

Third, the README's support section describes the library as community supported and notes that while it is in version 0.x the maintainers reserve the right to make backwards-incompatible changes. The version on PyPI is 4.10.0, so that specific caveat reads as stale text carried over from an earlier era, but the surrounding promise is more useful: if functionality is removed, the intention stated is to deprecate and give developers a year to update. Treat that as a policy statement, not a guarantee.

Finally, the retry behaviour is narrow by design. It covers retriable 5xx responses. It does not cover quota errors, invalid keys or malformed addresses, and the README does not document rollback or a way to disable retries. If you need deterministic request counts for accounting, you are adding that yourself.

googlemaps versus calling the REST endpoints directly

The obvious alternative is not another Python geocoding package; it is requests plus your own thin wrapper, or an HTTP client like httpx if you want async. The difference in approach is real rather than cosmetic.

Calling the REST endpoints directly gives you control over the transport: connection pooling tuned to your concurrency, your own retry policy with backoff and a hard attempt cap, structured logging of every outbound URL, and async I/O if your application is built on an event loop. The googlemaps client is synchronous and delegates transport to requests. For a service making thousands of concurrent geocoding calls, that difference decides your architecture, and no amount of convenience in the wrapper compensates for it.

The wrapper's advantage is the surface area. Ten APIs, each with different parameter names and response envelopes, become ten methods on one object with consistent argument passing. If you are writing a script, an internal tool, or a backend where map calls are a small fraction of the work, hand-rolling that mapping is wasted effort. The library also tracks newer endpoints such as Address Validation, which saves you from discovering the request shape yourself.

A middle path is common: use googlemaps for the calls and wrap it in your own caching and retry layer. That keeps the parameter mapping and takes back control of the request budget. It is more code than either extreme, and it is the honest answer for a production service with a real bill attached.

Licence, maintenance and the cost of upgrading

The project is licensed under Apache-2.0, and setup.py declares "License :: OSI Approved :: Apache Software License". That is a permissive licence with an explicit patent grant, and it imposes no obligation on your own source. It says nothing about Google Maps Platform usage, which is governed separately by Google's terms; the README points at those terms directly. Do not read the open source licence as permission to use the APIs without an account or without paying.

Upgrade cost is low but not zero. The dependency floor is requests>=2.20.0,<3.0, and the README adds that you need requests 2.4.0 or higher to specify connect or read timeouts, which is a note that predates the current floor and is now moot in practice. Because responses are plain dicts, a Google-side response change can break your code without any library upgrade at all, and a library upgrade can change nothing visible if you only use stable endpoints. The realistic upgrade risk sits in the gap between the last release tag and the branch, and in the maintainers' stated right to break compatibility while the library is described as 0.x.

Maintenance status: the repository is not archived, and the last push was on 2026-07-14. That is recent activity on the branch. The last tagged release, v4.10.0, was published on 2023-01-26, so releases are far less frequent than commits.

Editorial conclusion

Adopt googlemaps if your application already depends on Google Maps Platform data and you want a small Python wrapper rather than hand-written HTTP calls against ten different endpoints. Do not adopt it if you need offline geocoding, a tile server you control, or a way to avoid Google's per-request billing; the library changes nothing about pricing or terms. Before you write production code, verify three things: that your API key is restricted in the Google Cloud console, that the specific APIs you need are enabled on the project, and that your requests library version is at least 2.4.0 if you intend to pass connect or read timeouts. The repository was pushed on 2026-07-14, so the code is current even though the last tagged release, v4.10.0, dates from 2023-01-26.

Frequently asked questions

Official sources

1. googlemaps/google-maps-services-python on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases