Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Clear out junk files and repair common Windows errors3Scan for outdated or missing drivers - takes under a minuteUse Google Maps Platform Web Services from Python by creating a billed Google Cloud project, enabling only the APIs you need, restricting a server-side API key, and then calling either the community-supported googlemaps client or the HTTPS endpoints directly. The same setup supports geocoding, reverse geocoding, directions, distance calculations, places, address validation, elevation, roads, time zones, geolocation, and static maps.
This guide walks through setup, working Python examples, direct HTTP alternatives, service selection, security, quotas, reliability, and common failures. Google changes product names, endpoint versions, quotas, and prices, so verify the current service reference and pricing before deploying.
What you need before writing Python
- A Google Cloud project (new or existing).
- A billing account attached to that project. Google states that Maps Platform products require billing and that every request must include a valid API key or client ID.
- The specific Maps Platform APIs your application will call.
- A restricted API key stored outside source code.
- Python 3 and a virtual environment for your application.
There is no single “Google Maps API” endpoint. Web services are separate products with different request shapes, returned data, quotas, and billing. Enable only what your workflow uses.
Set up a project and restricted API key
- In Google Cloud Console, select or create a project and attach a billing account.
- Open APIs & Services > Library and enable the products you need, such as Geocoding, Directions, Places, or Address Validation. Enable specialized products such as Elevation, Roads, Time Zone, Geolocation, or Maps Static only when required.
- Go to APIs & Services > Credentials, create an API key, and apply API restrictions so the key can call only the enabled services.
- Apply an application restriction appropriate to a server-side workload. A backend key is normally kept off browser code; choose IP, server, or another restriction supported by your deployment model.
- Put the key in an environment variable or secret manager. Do not commit it to Git, put it in a notebook shared publicly, or embed it in a client-side bundle. Rotate it immediately if it leaks.
- Set quota alerts or limits in Cloud Console and monitor usage. Limits are generally expressed as queries per minute (QPM), although some products use other units; do not assume one product’s quota applies to another.
Install the Python client
The commonly used Python package is a community-supported wrapper around Maps Platform Web Services. Install it in your virtual environment:
#1 Best Overall
python -m venv .venv
# macOS/Linux
source .venv/bin/activate
# Windows PowerShell: .venvScriptsActivate.ps1
pip install -U googlemapsBecause the wrapper is community supported rather than covered by Google’s standard deprecation policy or support agreement, pin and review dependency updates, and test when Google changes an API or endpoint.
First request: geocode an address
Geocoding converts a human-readable address into coordinates and structured address components. Reverse geocoding does the opposite: it converts latitude and longitude into nearby address information.
import os
import googlemaps
api_key = os.environ["GOOGLE_MAPS_API_KEY"]
gmaps = googlemaps.Client(key=api_key)
results = gmaps.geocode("1600 Amphitheatre Parkway, Mountain View, CA")
if not results:
raise LookupError("No geocoding result")
first = results[0]
location = first["geometry"]["location"]
print(first["formatted_address"])
print(location["lat"], location["lng"])For reverse geocoding, pass a coordinate pair:
results = gmaps.reverse_geocode((37.4221, -122.0841))
for result in results:
print(result.get("formatted_address"))Do not assume the first result is always the address your business wants. Inspect result types, components, and the returned status, then apply your own acceptance rules before saving data.
Get driving, walking, bicycling, or transit directions
The Directions service returns route legs, distance, duration, and (where available) transit details. A transit route generally needs a departure or arrival time.
Rank #2
import os
from datetime import datetime, timezone
import googlemaps
# Keep this key in your environment, not in the file.
gmaps = googlemaps.Client(key=os.environ["GOOGLE_MAPS_API_KEY"])
directions = gmaps.directions(
"Sydney Town Hall",
"Parramatta, NSW",
mode="transit",
departure_time=datetime.now(timezone.utc),
)
if not directions:
raise LookupError("No route returned")
route = directions[0]
print(route.get("summary"))
for leg in route["legs"]:
print(leg["distance"]["text"], leg["duration"]["text"])
for step in leg["steps"]:
print(step["html_instructions"])For a driving route, change mode to driving. Walking and bicycling availability, transit coverage, traffic behavior, and route options depend on the requested region and current service rules. Validate the response before indexing nested fields.
Compare many origins and destinations with Distance Matrix
Use Distance Matrix when the question is “How long is each origin-to-destination combination?” rather than “What is the full turn-by-turn route?”
matrix = gmaps.distance_matrix(
["Seattle, WA", "Portland, OR"],
["San Francisco, CA", "Sacramento, CA"],
mode="driving",
)
for row in matrix["rows"]:
for element in row["elements"]:
print(element["status"], element.get("distance"), element.get("duration"))Matrix responses contain one element per origin-destination pair. Check each element’s status; a successful top-level response does not guarantee that every pair has a route.
Choose the right Maps Platform service
| Need | Service or client method | Implementation note |
|---|---|---|
| Address to coordinates | Geocoding | Inspect result types and components before storing a match. |
| Coordinates to address | Reverse geocoding | Results can include several nearby interpretations. |
| Turn-by-turn route | Directions | Choose travel mode and supply a suitable time for transit or traffic-sensitive requests. |
| Many travel-time comparisons | Distance Matrix | Process each matrix element’s status independently. |
| Search or retrieve places | Places | For Places API (New), use field masks and request only needed fields. |
| Postal-address checks | Address Validation | Availability and returned fields vary by supported location. |
| Terrain height | Elevation | Use for elevation profiles or point queries. |
| Road snapping and context | Roads | Useful when GPS traces need road alignment. |
| Local time at coordinates | Time Zone | Convert timestamps using the returned zone information. |
| Device location estimate | Geolocation | Requires the inputs supported by that service. |
| Map image | Maps Static | Returns a rendered map image rather than interactive map behavior. |
Places API (New) and field masks
Places requests can return a large set of fields. For Place Details, Nearby Search, and Text Search, use a field mask containing only the properties your application needs. This can reduce response latency and control billing-related usage. Treat the current Places API reference as authoritative when migrating from legacy Places methods.
Rank #3
Direct HTTPS requests from Python
The client library is convenient, but direct HTTPS gives you explicit control over URL construction, timeouts, retries, headers, logging, and the exact API version. Use the current endpoint and parameter names documented for the product you enabled.
import os
import requests
params = {
"address": "1600 Amphitheatre Parkway, Mountain View, CA",
"key": os.environ["GOOGLE_MAPS_API_KEY"],
}
response = requests.get(
"https://maps.googleapis.com/maps/api/geocode/json",
params=params,
timeout=15,
)
response.raise_for_status()
payload = response.json()
if payload.get("status") != "OK":
raise RuntimeError(payload.get("status"))
print(payload["results"][0]["formatted_address"])This example uses a commonly documented geocoding route; check Google’s current reference before production use because endpoint versions and legacy services can change. Never log the complete key or sensitive user data in request URLs.
Reliability: timeouts, retries, and response validation
Set bounded timeouts
A request without a timeout can occupy workers indefinitely during a network failure. Set connect and read limits with requests, and configure equivalent transport behavior if your wrapper version exposes it.
Retry selectively
Retry transient network failures and explicitly retryable server responses with exponential backoff and a cap. Do not blindly retry authentication errors, invalid requests, or quota denials; those require configuration or code changes. Add jitter when many workers retry together.
Validate before persistence
- Check the HTTP status and the API’s own status field.
- Handle empty result arrays and missing nested keys.
- Record the request type, elapsed time, response status, and a correlation identifier without recording the secret.
- Store the source timestamp and assumptions when route or place data will be reused.
Plan for dependency and API changes
The googlemaps package is community supported. Pin a known-good version, review release notes, run integration tests against a non-production project, and review Google’s current API documentation when a service is renamed, versioned, or deprecated.
Billing, quotas, and cost controls
Google requires a billing account and a valid key for Maps Platform use. Pricing, included credits, and product-specific units can change, so obtain current figures from Google before publishing a budget or presenting a per-call estimate. The reported 30,000 QPM figure for Maps JavaScript API Dynamic Maps is product-specific and should not be generalized to Python web services.
- Enable only required APIs and restrict each key.
- Use Places field masks.
- Cache results only where your use and Google’s terms permit it, and choose a retention policy deliberately.
- Set quota alerts, watch dashboards, and investigate sudden increases.
- Separate development and production projects when practical.
Common errors and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
| “API key not valid” or authentication failure | Missing, mistyped, deleted, or over-restricted key | Confirm the environment variable, project, and key restrictions; rotate if exposed. |
| “This API project is not authorized” | The product is not enabled or the key’s API restriction excludes it | Enable the exact API and update the restriction. |
| Billing-related denial | No billing account attached or billing status problem | Attach and verify billing for the active project. |
| Empty results | Unrecognized address, unsupported coverage, or overly strict filters | Inspect the full status and result types; normalize input and handle “no match” explicitly. |
| Quota or rate-limit response | Project or product limit exceeded | Reduce concurrency, add bounded backoff, and review quotas and traffic patterns. |
| Timeouts | Network, upstream latency, or an oversized request | Set timeouts, retry only transient failures, reduce requested fields, and measure latency. |
| Code breaks after an API change | Legacy endpoint, response shape, or wrapper dependency changed | Read the current service reference, update deliberately, and run contract tests. |
Security checklist for production
- Keep keys server-side in environment variables or a secret manager.
- Use separate restricted keys for separate workloads where that limits blast radius.
- Restrict by API and application, and review restrictions after infrastructure changes.
- Redact keys, addresses, coordinates, and user identifiers from logs according to your privacy requirements.
- Rotate any key that appears in a public repository, client bundle, ticket, or log.
- Use least-privilege service enablement and quota alerts.
Or skip the browser setup
If your project also needs dependable screenshots of map pages or other URLs, ScreenshotNeo provides a website screenshot API and MCP server. It is separate from Google Maps Platform: you send one GET request and receive a PNG, JPEG, WebP, or PDF.
Its cleanup steps accept cookie or consent banners and remove more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be disabled. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing result. AI clients such as Claude and Cursor can use its MCP tools take_screenshot, get_page_info, and capture_pdf.
Free tools Windows power users keep installed
One-click scans. No signup required.
Python:
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpNode.js:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);See the ScreenshotNeo documentation for capture options. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.
Best Value
Frequently Asked Questions
Can I call Google Maps Web Services without a billing account?
No. Google’s stated requirement is a billing account plus a valid API key for Maps Platform products.
Is the googlemaps Python package an official Google-supported client?
It is a community-supported client library. Monitor releases and Google API documentation rather than assuming Google’s standard deprecation or support commitments apply.
Should I put my key in a Python script?
Keep the key outside source code, such as an environment variable or secret manager, and restrict it by API and application.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Which service should I use for many route comparisons?
Use Distance Matrix for origin-destination travel-time or distance comparisons; use Directions when you need route legs and turn-by-turn detail.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
