The Maps Tools Resolution API provides batch processing endpoints to resolve location names and URLs to Google Maps Place IDs.
API Access & Authentication
Authentication Methods
The APIs support both API Keyand OAuth 2.0credentials:
1. API Key
You can authenticate requests by appending a valid Google Maps Platform API Key
to the request URL or in X-Goog-Api-Key
header:
https://mapstools.googleapis.com/v1alpha:resolveNames?key=YOUR_API_KEY
2. OAuth 2.0 Scopes
If using OAuth authorization, the following scopes are supported:
-
https://www.googleapis.com/auth/maps-platform.mapstools(Recommended)
Request Validation & Constraints
To prevent excessive load and ensure fast response times, batch requests are strictly validated:
- Batch Size Limit: Both APIs allow a maximum of 20 itemsper request.
- ResolveNames Requirements:
- Each queries item must specify a non-empty text parameter.
- Queries must represent a specific place name or address (e.g., "Googleplex, Mountain View, CA", "Eiffel Tower, Paris").
- General categorical searches (e.g., "restaurants in New York") or generic chain names without a location (e.g., "Starbucks") are not supportedand may fail resolution.
- ResolveMapsUrls Requirements:
- Each URL must be a structurally valid Google Maps URL.
- Supported formats include:
- Standard place URL:
https://www.google.com/maps/place/... - Shortened URL:
https://maps.app.goo.gl/...
- Standard place URL:
- General query-based Maps URLs (e.g.,
https://maps.google.com/?q=restaurant) and URLs that do not point to a single unique place are not supported.
Handling Partial Errors
Both APIs are designed as batch processors. If some items in a batch fail to resolve, the overall request does not failwith a top-level error. Instead, the API returns a Partial Successresponse.
How to Interpret the Response
- Guaranteed 1:1 Alignment: The returned results (for
ResolveNames) or entities (forResolveMapsUrls) lists map 1:1with the input list. - Empty Elements for Failures: If an item at index
ifailed to resolve, the result list will contain an empty object{}at indexi. - failedRequests Map: The response contains a
failedRequestsmap.- The keyis the 0-based index of the failed item (represented as a string in JSON).
- The valueis a
google.rpc.Statusobject containing the specific error code (from standard gRPC/HTTP statuses) and a detailed message explaining why it failed.
Top-Level Failures
A top-level HTTP error (e.g., 400 Bad Request
) is returned only if the
request fails validation (e.g., when passing more than 20 items, or missing
required fields).
API Specification & Curl Examples
1. ResolveNames API
Method: POST
https://mapstools.googleapis.com/v1alpha:resolveNames
Request Body Format
{
"queries"
:
[
{
"text"
:
"string"
}
],
"locationBias"
:
{
"viewport"
:
{
"low"
:
{
"latitude"
:
nu
mber
,
"longitude"
:
nu
mber
},
"high"
:
{
"latitude"
:
nu
mber
,
"longitude"
:
nu
mber
}
}
},
"regionCode"
:
"string"
}
-
queries(Required): Repeated list of queries to resolve (Max 20). -
locationBias(Optional): Viewport bounding box to bias results towards a local region. -
regionCode(Optional): CLDR country code (e.g. "US", "FR") to bias results.
Curl Example: Successful Resolution
This query resolves "Googleplex" and "Eiffel Tower".
curl
-X
POST
\
-H
"Content-Type: application/json"
\
-d
'{
"queries": [
{ "text": "Googleplex, Mountain View, CA" },
{ "text": "Eiffel Tower, Paris" }
]
}'
\
"https://mapstools.googleapis.com/v1alpha:resolveNames?key=KEY"
JSON Response
{
"results"
:
[
{
"entity"
:
{
"place"
:
"places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
},
"confidence"
:
"HIGH"
},
{
"entity"
:
{
"place"
:
"places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
},
"confidence"
:
"HIGH"
}
]
}
Curl Example: Mixed Results (Partial Failure)
In this example, the first item is non-resolvable garbage text, and the second item is a valid place.
curl
-X
POST
\
-H
"Content-Type: application/json"
\
-d
'{
"queries": [
{ "text": "This is not a real place name at all 123456789" },
{ "text": "Eiffel Tower, Paris" }
]
}'
\
"https://mapstools.googleapis.com/v1alpha:resolveNames?key=KEY"
JSON Response
{
"results"
:
[
{},
{
"entity"
:
{
"place"
:
"places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
},
"confidence"
:
"HIGH"
}
],
"failedRequests"
:
{
"0"
:
{
"code"
:
5
,
"message"
:
"Place not found."
}
}
}
2. ResolveMapsUrls API
Method: POST
https://mapstools.googleapis.com/v1alpha:resolveMapsUrls
Request Body Format
{
"urls"
:
[
"string"
]
}
-
urls(Required): Repeated list of Google Maps URL strings to resolve (Max 20).
Curl Example: Successful Resolution
Resolving a standard Google Maps place link.
curl
-X
POST
\
-H
"Content-Type: application/json"
\
-d
'{
"urls": [
"https://www.google.com/maps/place/Googleplex/@37.4220041,-122.0862515,17z/data=!3m1!4b1!4m6!3m5!1s0x808fba024255ad8f:0x6ca26666619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6"
]
}'
\
"https://mapstools.googleapis.com/v1alpha:resolveMapsUrls?key=KEY"
JSON Response
{
"entities"
:
[
{
"place"
:
"places/ChIJj61VQgK6j4AR4GeTYWZmomw"
}
]
}
Curl Example: Mixed Results (Partial Failure)
Resolving one valid place URL and one malformed/unsupported URL.
curl
-X
POST
\
-H
"Content-Type: application/json"
\
-d
'{
"urls": [
"https://www.google.com/maps/place/Googleplex/@37.4220041,-122.0862515,17z/data=!3m1!4b1!4m6!3m5!1s0x808fba024255ad8f:0x6ca26666619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6",
"https://www.google.com/not-a-place"
]
}'
\
"https://mapstools.googleapis.com/v1alpha:resolveMapsUrls?key=KEY"
JSON Response
{
"entities"
:
[
{
"place"
:
"places/ChIJj61VQgK6j4AR4GeTYWZmomw"
},
{}
],
"failedRequests"
:
{
"1"
:
{
"code"
:
3
,
"message"
:
"Invalid URL."
}
}
}
Curl Example: Validation Failure
Attempting to pass more than 20 URLs in a single request.
python3
-c
'import json; print(json.dumps({"urls": ["https://www.google.com/maps/place/Googleplex"] * 21}))'
|
\
curl
-X
POST
\
-H
"Content-Type: application/json"
\
-d
@-
\
"https://mapstools.googleapis.com/v1alpha:resolveMapsUrls?key=KEY"
JSON Response
{
"error"
:
{
"code"
:
400
,
"message"
:
"Request contains more than 20 URLs."
,
"status"
:
"INVALID_ARGUMENT"
}
}
