{"id":2522,"library":"googlemaps","title":"Google Maps Platform Python Client","description":"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.","status":"active","version":"4.10.0","language":"en","source_language":"en","source_url":"https://github.com/googlemaps/google-maps-services-python","tags":["google maps","geocoding","places","directions","maps api","location"],"install":[{"cmd":"pip install googlemaps","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Used for HTTP requests, implicitly required for timeout and connection management. Version >=2.4.0 is required for some client features.","package":"requests","optional":false}],"imports":[{"note":"The common pattern is to import the top-level `googlemaps` package and then instantiate `googlemaps.Client`.","wrong":"from googlemaps import Client\ngmaps = Client('YOUR_API_KEY')","symbol":"Client","correct":"import googlemaps\ngmaps = googlemaps.Client(key='YOUR_API_KEY')"}],"quickstart":{"code":"import os\nimport googlemaps\n\n# Set your API key as an environment variable (e.g., GOOGLE_MAPS_API_KEY)\napi_key = os.environ.get('GOOGLE_MAPS_API_KEY', 'YOUR_API_KEY')\n\nif api_key == 'YOUR_API_KEY' or not api_key:\n    print(\"WARNING: Please set the GOOGLE_MAPS_API_KEY environment variable or replace 'YOUR_API_KEY' in the code.\")\n    exit()\n\ngmaps = googlemaps.Client(key=api_key)\n\n# Geocoding an address\naddress = \"1600 Amphitheatre Parkway, Mountain View, CA\"\ngeocode_result = gmaps.geocode(address)\n\nif geocode_result:\n    print(f\"Geocoding for '{address}':\")\n    for result in geocode_result:\n        location = result['geometry']['location']\n        print(f\"  Latitude: {location['lat']}, Longitude: {location['lng']}\")\nelse:\n    print(f\"No geocoding results found for '{address}'.\")","lang":"python","description":"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."},"warnings":[{"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).","message":"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.","severity":"breaking","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"All versions of `googlemaps` when interacting with underlying Google Maps Platform API versions that have breaking changes (e.g., Geocoding API v3 to v4)."},{"fix":"Be aware of the community support model. For critical applications, ensure internal expertise or a support strategy is in place.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"Versions < 4.7.2 had Python 3.5 issues. Other Google Maps client libraries (different packages) may have higher Python requirements for all versions."}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}