A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Google Maps API is how an app or AI agent works with Google's geospatial data: turning an address into coordinates, finding nearby places, computing a route between two points, or looking up the time zone at a location. Access is granted through an API key, and the key is restricted in the Google Cloud Console to set which APIs it may call and which sites or addresses may use it. The web service APIs are read-oriented lookups, and they signal an empty or failed query through a status field in the response rather than only an HTTP error.
How an app or AI agent connects to Google Maps determines what it can reach. There is the set of web service APIs called with an API key, and a hosted server that exposes a subset of Maps tools to agents, and each is governed by the key behind it and the APIs that key is allowed to call.
The Google Maps Platform web service APIs are HTTPS endpoints called directly with an API key. The older services (Geocoding, Directions, Distance Matrix, Time Zone, Elevation, Roads) are GET requests under maps.googleapis.com/maps/api and roads.googleapis.com, with the key in the URL. The newer services (Places API (New), Routes, Address Validation) are mostly POST requests to their own host with the key in an X-Goog-Api-Key header and a required X-Goog-FieldMask header.
Google publishes a hosted Model Context Protocol server at https://mapstools.googleapis.com/mcp, through Maps Grounding Lite, that exposes a focused set of Maps tools to AI agents and MCP clients: search_places, compute_routes, resolve_names, resolve_maps_urls, and lookup_weather. It is enabled on a Google Cloud project and authenticated with that project's credentials, the same key-and-restriction model as the web service APIs.
An API key is a single string that identifies the calling project. The older web services take it as a key query parameter in the URL; the newer Places, Routes, and Address Validation APIs take it as an X-Goog-Api-Key header. The key carries no per-method scopes. Its reach is set entirely by the restrictions placed on it in the Google Cloud Console: which APIs it may call, and which HTTP referrers, IP addresses, or apps may use it.
The Google Maps Platform web service APIs are split into areas an agent can call, like turning an address into coordinates, finding places, computing routes, and looking up a time zone or elevation. Almost every method reads geospatial data and returns a result; none of them change a customer's own records.
Methods for converting between addresses and geographic coordinates.
Methods for finding places and reading their details, on the Places API (New).
Methods for computing routes and travel distances and times between points.
Methods for snapping GPS traces to roads and reading speed limits.
Methods for looking up the time zone, elevation, or validity of a location.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
GeocodingMethods for converting between addresses and geographic coordinates.3 | ||||||
| GET | /maps/api/geocode/json | Convert an address into geographic coordinates (forward geocoding). | read | Geocoding API | Current | |
Read-only. Key must be allowed to call the Geocoding API. Acts ongeocode Permission (capability) Geocoding APIVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /maps/api/geocode/json | Convert latitude and longitude coordinates into a human-readable address (reverse geocoding), via the latlng parameter. | read | Geocoding API | Current | |
Read-only. Same endpoint as forward geocoding, using latlng instead of address. Acts ongeocode Permission (capability) Geocoding APIVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1:validateAddress | Validate and standardize a postal address, returning corrections and a confidence verdict (addressvalidation.googleapis.com). | read | Address Validation API | Current | |
Read-only validation. POST with a JSON address body; key sent as a query parameter or header. Acts onaddress Permission (capability) Address Validation APIVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
PlacesMethods for finding places and reading their details, on the Places API (New).5 | ||||||
| POST | /v1/places:searchText | Find places from a free-text query, like 'pizza near me' (Places API New; places.googleapis.com). | read | Places API | Current | |
Read-only. Requires an X-Goog-FieldMask header naming the fields to return; the field mask sets the billing tier. Acts onplace Permission (capability) Places APIVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/places:searchNearby | Find places within a circular area, optionally filtered by place type (Places API New). | read | Places API | Current | |
Read-only. POST only; requires an X-Goog-FieldMask header. Acts onplace Permission (capability) Places APIVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/places/{PLACE_ID} | Read detailed information about a single place by its place ID, like hours, phone, rating, and address (Places API New). | read | Places API | Current | |
Read-only. Requires an X-Goog-FieldMask header (or fields parameter) naming the fields to return. Acts onplace Permission (capability) Places APIVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/places:autocomplete | Return place and query predictions for a partial text input, for type-ahead search (Places API New). | read | Places API | Current | |
Read-only. POST with the partial input in the JSON body; can use a session token to group keystrokes for billing. Acts onplace Permission (capability) Places APIVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/{NAME}/media | Fetch a place photo by its photo resource name, sized with maxHeightPx or maxWidthPx (Places API New). | read | Places API | Current | |
Read-only. The photo resource name comes from a Place Details, Text Search, or Nearby Search response. Acts onphoto Permission (capability) Places APIVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Routes & DistanceMethods for computing routes and travel distances and times between points.4 | ||||||
| GET | /maps/api/directions/json | Compute directions between an origin and destination, with optional waypoints and travel mode (legacy Directions API). | read | Directions API | Current | |
Read-only. The Routes API computeRoutes is the newer replacement for new integrations. Acts onroute Permission (capability) Directions APIVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /maps/api/distancematrix/json | Compute travel distance and time for a matrix of origins and destinations (legacy Distance Matrix API). | read | Distance Matrix API | Current | |
Read-only. Billed by element (origins times destinations). The Routes API computeRouteMatrix is the newer replacement. Acts ondistance_matrix Permission (capability) Distance Matrix APIVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /directions/v2:computeRoutes | Compute one or more routes between an origin and destination with the newer Routes API (routes.googleapis.com). | read | Routes API | Current | |
Read-only. POST with a JSON body; requires an X-Goog-FieldMask header. Replaces the legacy Directions API. Acts onroute Permission (capability) Routes APIVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /distanceMatrix/v2:computeRouteMatrix | Compute distance and time for a matrix of origins and destinations with the newer Routes API. | read | Routes API | Current | |
Read-only. POST with a JSON body and an X-Goog-FieldMask header. Replaces the legacy Distance Matrix API. Acts onroute_matrix Permission (capability) Routes APIVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
RoadsMethods for snapping GPS traces to roads and reading speed limits.3 | ||||||
| GET | /v1/snapToRoads | Snap up to 100 GPS points to the most likely roads they were travelled on (roads.googleapis.com). | read | Roads API | Current | |
Read-only. Accepts up to 100 points per request via the path parameter. Acts onroad Permission (capability) Roads APIVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/nearestRoads | Return the road segments nearest to a set of coordinates (Roads API). | read | Roads API | Current | |
Read-only. Takes a points parameter of coordinates. Acts onroad Permission (capability) Roads APIVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/speedLimits | Return posted speed limits for road segments or a set of snapped points (Roads API). | read | Roads API | Current | |
Read-only. Available on Asset Tracking plans; takes place IDs or a path of points. Acts onspeed_limit Permission (capability) Roads APIVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Location contextMethods for looking up the time zone, elevation, or validity of a location.2 | ||||||
| GET | /maps/api/timezone/json | Return the time zone, offset, and daylight-saving offset for a location and timestamp. | read | Time Zone API | Current | |
Read-only. Takes a location and a timestamp. Acts ontimezone Permission (capability) Time Zone APIVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /maps/api/elevation/json | Return the elevation for one or more locations on the Earth's surface. | read | Elevation API | Current | |
Read-only. Takes a locations parameter, or a path and samples for elevation along a line. Acts onelevation Permission (capability) Elevation APIVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| Event | What it signals | Triggered by |
|---|
Google Maps meters each API by a queries-per-minute and, on some APIs, a queries-per-second ceiling, set per project in the Google Cloud Console, and bills per call against a monthly volume.
Google Maps meters each API independently, set per project in the Google Cloud Console. Most web services default to a queries-per-minute ceiling, like 3,000 per minute, and some also enforce a queries-per-second limit, like 25 per second on Geocoding. The Roads API has its own ceiling. A project can request higher quotas, and going over returns the OVER_QUERY_LIMIT status (or HTTP 429 on the newer APIs). Billing is pay-per-call against monthly volume, so a custom daily quota can be set in the Console to cap spend.
The search APIs return a bounded page rather than a cursor over everything. A legacy Places Text Search or Nearby Search returns up to 20 results per page and up to 60 in total, fetched with a next_page_token. Places API (New) returns up to 20 places per call, raised with a pageSize parameter and continued with a pageToken. Geocoding, Directions, and the lookup APIs return their full result set in one response.
Limits are per request, not per page. A request URL is capped at 16,384 characters across the web services. Snap to Roads accepts up to 100 GPS points per call, a Distance Matrix request is bounded by origins times destinations elements, and Places API (New) caps a single search at 20 results unless pageSize is raised.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 200 | ZERO_RESULTS | On the classic web services, the request succeeded with HTTP 200 but the query matched no results, like an address that could not be located or a route that could not be built. | Treat it as an empty result, not a failure. Check the input parameters and widen the query if a match was expected. |
| 200 | OVER_QUERY_LIMIT | The project has exceeded its rate limit (queries per second or per minute) for that API. Returned with HTTP 200 and this status on the classic web services. | Back off and retry with exponential backoff, smooth the request rate, or raise the quota for the API in the Google Cloud Console. |
| 200 | REQUEST_DENIED | The request was refused: the API key is missing or invalid, the key is not allowed to call this API, billing is not enabled, or the request was sent over HTTP instead of HTTPS. | Confirm a valid key is sent, that the key's API restrictions include this API, that billing is enabled, and that the request uses HTTPS. |
| 200 | INVALID_REQUEST | The request was malformed, usually a missing or invalid required parameter, like an address or location that was not supplied. | Check the required parameters for that API and resend; the request is not retryable as-is. |
| 403 | PERMISSION_DENIED | On the newer Places, Routes, and Address Validation APIs, the key is not authorized for the request, for example the API is not enabled on the project or the key's restrictions exclude it. | Enable the API on the project and confirm the key's API and application restrictions allow this call. |
| 429 | RESOURCE_EXHAUSTED | On the newer APIs, the per-minute or per-second quota for the project has been exhausted. | Retry with exponential backoff and request a higher quota in the Google Cloud Console if the limit is hit consistently. |
| 400 | INVALID_ARGUMENT | On the newer APIs, the request body or parameters were invalid, including a missing X-Goog-FieldMask header where one is required. | Validate the JSON body and include a valid field mask naming the fields to return, then resend. |
The core Google Maps web service APIs are unversioned and addressed by path; newer APIs like Places, Routes, and Address Validation carry a version segment in their path, and changes ship through dated release notes rather than a pinned account version.
The classic web services (Geocoding, Directions, Distance Matrix, Time Zone, Elevation, Roads) are unversioned and addressed by path under /maps/api; the newer services carry a path version (Places and Address Validation at /v1, Routes at /directions/v2). There is no per-account pinned version. Google ships changes through dated release notes and keeps the stable web services backward-compatible.
Google released hosted, remote Model Context Protocol servers for Google services, including Maps Grounding Lite at mapstools.googleapis.com/mcp, giving AI agents a managed endpoint for places, routing, and weather grounding.
Google introduced the rebuilt Places API (New) under places.googleapis.com/v1 and the Routes API under routes.googleapis.com, both using POST requests with a required X-Goog-FieldMask header, replacing the legacy GET-based Places and Directions and Distance Matrix services for new integrations.
Track the release notes; the older web services stay backward-compatible while newer ones add features under their own path version.
Google Maps Platform release notes ↗Bollard AI sits between a team's AI agents and Google Maps. Grant each agent only the Maps capabilities it needs, geocoding, places, or routing, and every call is checked and logged.