Maps Tools Resolution API

The Maps Tools Resolution API is part of Maps Grounding Lite. It provides batch endpoints that resolve location names and Google Maps URLs to Google Maps Place IDs. You can use the returned Place IDs with other Google Maps Platform APIs. Each response also includes a link that saves the resolved places as a list in Google Maps.

The Resolution API is available both as REST methods and as tools on the Maps Grounding Lite MCP server:

Capability	REST method	MCP tool
Resolve location names or addresses to places	`resolveNames`	`resolve_names`
Resolve Google Maps URLs to places	`resolveMapsUrls`	`resolve_maps_urls`

Before you begin

To use the Resolution API, you need a Google Cloud project with billing enabled and the Maps Grounding Lite API service enabled. For instructions, see Enable the Maps Grounding Lite service on your Google Cloud project.

API access and authentication

The Resolution API supports both API key and OAuth 2.0 credentials.

API key

You can authenticate requests by passing a valid Google Maps Platform API key in the X-Goog-Api-Key header or by appending it to the request URL:

https://mapstools.googleapis.com/v1:resolveNames?key=API_KEY

In the examples on this page, replace API_KEY with your API key.

OAuth 2.0 scopes

If you use OAuth authorization, the following scope is supported:

https://www.googleapis.com/auth/maps-platform.mapstools

Usage limits

The following default quotas apply to the Resolution API:

ResolveNames: 600 queries per minute, per project.
ResolveMapsUrls: 600 queries per minute, per project.
Batch size: Up to 20 queries or URLs per request.

Each request counts as one query, regardless of how many items it contains.

Pricing

Requests to ResolveNames and ResolveMapsUrls are billed at no charge ($0) under the Places API Text Search Essentials (IDs Only) SKU. As with the rest of Maps Grounding Lite, your project must have a billing account.

Request validation and constraints

To prevent excessive load and ensure fast response times, batch requests are strictly validated:

Batch size limit: Both methods allow a maximum of 20 items per request.
ResolveNames requirements:
- Each item in queries must specify a non-empty text parameter.
- Queries must represent a specific place name or address (for example, "Googleplex, Mountain View, CA" or "Eiffel Tower, Paris").
- General categorical searches (for example, "restaurants in New York") or generic chain names without a location (for example, "Starbucks") are not supported and might fail to resolve.
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/...
- General query-based Maps URLs (for example, https://maps.google.com/?q=restaurant) and URLs that don't point to a single unique place are not supported.

Save resolved places to Google Maps

If at least one item in a batch resolves, the response includes a saveToMapsUrl field. This is a single Google Maps link that contains all of the successfully resolved places in the batch. Present this link to users who want to save, share, or open the resolved places as a list in Google Maps.

Always use the link returned by the API. Don't construct the link yourself. If no items in the batch resolve, the response doesn't include saveToMapsUrl.

Handle partial errors

Both methods are batch processors. If some items in a batch fail to resolve, the overall request doesn't fail with a top-level error. Instead, the API returns a partial success response, and you must check the response for per-item failures.

Interpret the response

Guaranteed 1:1 alignment: The returned results list (for ResolveNames) or entities list (for ResolveMapsUrls) maps 1:1 with the input list, by index.
Empty elements for failures: If the item at index i failed to resolve, the result list contains an empty object {} at index i.
failedRequests map: The response contains a failedRequests map.
- The key is the 0-based index of the failed item (represented as a string in JSON).
- The value is a google.rpc.Status object containing the error code and a message explaining why the item failed.
saveToMapsUrl covers only successes: The saveToMapsUrl link includes only the items that resolved. Failed items aren't included.

Don't assume that the entire batch failed because one item failed. Always check failedRequests to find out which items, if any, couldn't be resolved.

Per-item errors

The following table lists the per-item errors that you might see in failedRequests:

Method	Cause	Code	Message
`ResolveNames`	The name or address can't be resolved to a place.	`5` (`NOT_FOUND`)	`Place not found.`
`ResolveMapsUrls`	The URL can't be resolved to a place.	`3` (`INVALID_ARGUMENT`)	`Failed to resolve Maps URL to a place.`
Both methods	An internal error occurred while resolving the item.	`13` (`INTERNAL`)	`Internal server error. Please retry. If the problem persists, please open a support case. https://goo.gle/maps-platform-support`

Retry only the items that failed with INTERNAL.

Top-level failures

The API returns a top-level error instead of a partial response in the following cases:

Invalid request (400 INVALID_ARGUMENT): The request contains more than 20 items, a ResolveNames request has no queries or has a query with an empty text value, or a ResolveMapsUrls request has a URL that's empty or isn't a syntactically valid URL. One invalid item causes the entire request to fail.
Authentication, permission, or quota errors: For example, the API key is missing or invalid, or the request exceeds the usage limits.
Server errors (500 INTERNAL): Retry the request.

Use the Resolution API with MCP

The Maps Grounding Lite MCP server at https://mapstools.googleapis.com/mcp exposes the Resolution API as two tools:

resolve_names: Resolves a batch of location names or addresses to Place IDs.
resolve_maps_urls: Resolves a batch of Google Maps URLs to Place IDs.

When you configure your LLM to use the Maps Grounding Lite MCP server, these tools are available alongside the other Maps Grounding Lite tools. The tools accept the same inputs, enforce the same constraints, and return the same partial-failure response as the REST methods.

The tool responses include the save_to_maps_url field. The tool descriptions instruct the LLM to present this link when the user wants to save, share, or open the resolved places as a list in Google Maps, instead of constructing a link itself.

The following example uses curl to call the resolve_names tool directly:

curl --location 'https://mapstools.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--header 'X-Goog-Api-Key: API_KEY' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "resolve_names",
    "arguments": {
      "queries": [
        { "text": "Googleplex, Mountain View, CA" },
        { "text": "Eiffel Tower, Paris" }
      ]
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

To call resolve_maps_urls, set name to resolve_maps_urls and pass a urls array in arguments.

REST API specification and curl examples

ResolveNames

Method: POST

https://mapstools.googleapis.com/v1:resolveNames

Request body format

{
  "queries": [
    { "text": "string" }
  ],
  "locationBias": {
    "viewport": {
      "low": { "latitude": number, "longitude": number },
      "high": { "latitude": number, "longitude": number }
    }
  },
  "regionCode": "string"
}

queries (Required): Repeated list of queries to resolve (maximum 20).
locationBias (Optional): Viewport bounding box to bias results towards a local region.
regionCode (Optional): CLDR country code (for example, "US" or "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/v1:resolveNames?key=API_KEY"

JSON response

{
  "results": [
    {
      "entity": {
        "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
      },
      "confidence": "HIGH"
    },
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw,ChIJLU7jZClu5kcR4PcOOO6p3I0"
}

Curl example: Mixed results (partial failure)

In this example, the first item is text that can't be resolved, 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/v1:resolveNames?key=API_KEY"

JSON response

{
  "results": [
    {},
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "failedRequests": {
    "0": {
      "code": 5,
      "message": "Place not found."
    }
  },
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJLU7jZClu5kcR4PcOOO6p3I0"
}

ResolveMapsUrls

Method: POST

https://mapstools.googleapis.com/v1:resolveMapsUrls

Request body format

{
  "urls": [
    "string"
  ]
}

urls (Required): Repeated list of Google Maps URL strings to resolve (maximum 20).

Curl example: Successful resolution

The following example resolves a standard Google Maps place 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!1s0x808fba02425dad8f:0x6c296c66619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6"
]
}' \
"https://mapstools.googleapis.com/v1:resolveMapsUrls?key=API_KEY"

JSON response

{
  "entities": [
    {
      "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
    }
  ],
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw"
}

Curl example: Mixed results (partial failure)

The following example resolves one valid place URL and one URL that can't be resolved to a place:

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!1s0x808fba02425dad8f:0x6c296c66619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6",
    "https://www.google.com/not-a-place"
  ]
}' \
"https://mapstools.googleapis.com/v1:resolveMapsUrls?key=API_KEY"

JSON response

{
  "entities": [
    {
      "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
    },
    {}
  ],
  "failedRequests": {
    "1": {
      "code": 3,
      "message": "Failed to resolve Maps URL to a place."
    }
  },
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw"
}

Curl example: Validation failure

The following example passes 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/v1:resolveMapsUrls?key=API_KEY"

JSON response

{
  "error": {
    "code": 400,
    "message": "Request contains more than 20 URLs.",
    "status": "INVALID_ARGUMENT"
  }
}

Send feedback

To report an issue or share feedback about the Resolution API, use the Maps Grounding Lite public issue tracker component:

Maps Tools Resolution API Stay organized with collections Save and categorize content based on your preferences.

Before you begin

API access and authentication

API key

OAuth 2.0 scopes

Usage limits

Pricing

Request validation and constraints

Save resolved places to Google Maps

Handle partial errors

Interpret the response

Per-item errors

Top-level failures

Use the Resolution API with MCP

REST API specification and curl examples

ResolveNames

Method: POST

Request body format

Curl example: Successful resolution

JSON response

Curl example: Mixed results (partial failure)

JSON response

ResolveMapsUrls

Method: POST

Request body format

Curl example: Successful resolution

JSON response

Curl example: Mixed results (partial failure)

JSON response

Curl example: Validation failure

JSON response

Send feedback

Maps Tools Resolution API