googlemaps: the Python client for Google Maps Platform web services
Python client library for Google Maps API Web Services
At a glance
- What is it?
- The googlemaps package wraps ten Google Maps Platform web service APIs behind one Python client. It is a thin HTTP layer with retries, not an offline geocoder, and every call is billed by Google.
- Who is it for?
- 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.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 46 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 21, 2026, and from our analysis. They are not legal advice.
Star history
- googlemaps/google-maps-services-python4,981 ★ · +2
| Repository | 2026-09-23 | 2026-11-21 |
|---|---|---|
| googlemaps/google-maps-services-python | 5k | 5k |
2 Stars in the last 59 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
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. The package delegates HTTP to requests, its only declared runtime dependency.
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."
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 googlemapsAfter 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 the example builds now with datetime.now() for the departure time.
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. 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-10-06. 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 states that this library is not a Google Maps Platform Core Service, so the Google Maps Platform Terms of Service, including Technical Support Services, Service Level Agreements and Deprecation Policy, do not apply to the code in this library.
Finally, the retry behaviour is narrow by design. It covers retriable 5xx responses. 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 covers Address Validation, though the README states that newer APIs such as Places API (New) and the Routes API will not be added to this client library.
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.
Maintenance status: the repository is not archived, and the last push was on 2026-10-06. 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-10-06, so the code is current even though the last tagged release, v4.10.0, dates from 2023-01-26.
Frequently asked questions
Is the Google Maps API still free?
The README does not state pricing. It does say that the same Google Maps terms and conditions apply when the APIs are accessed through this library, and that each Google Maps Web Service request requires an API key or client ID generated in Google Cloud console. Check Google's own terms for billing.
What coding language does the googlemaps client library use?
It is a Python library. The repository's primary language is Python, setup.py declares python_requires='>=3.5', and the README lists Python 3.5 or later as a requirement.
How do I install the googlemaps Python package?
The README gives one command: pip install -U googlemaps. The package is named googlemaps on PyPI and its only declared runtime dependency is requests.
Does the googlemaps client retry failed requests?
Yes, but only for intermittent failures. The README states that it automatically retries when any of the retriable 5xx errors are returned from the API. Other error classes are not covered by that description.
Which Google Maps APIs does the googlemaps Python client cover?
The README lists seven: Elevation, Geocoding, Geolocation, Time Zone, Roads, Maps Static and Address Validation, plus three legacy APIs: Directions (Legacy), Distance Matrix (Legacy) and Places (Legacy), which as of October 2026 can no longer be enabled for new Google Cloud projects.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/googlemaps-google-maps-services-python)Star history chart for your README
[](https://hysenlabs.com/projects/googlemaps-google-maps-services-python)Was this useful?