Maps Tools Resolution API (experimental)

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 Key and OAuth 2.0 credentials:

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 items per 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 supported and 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/...
  • 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 fail with a top-level error. Instead, the API returns a Partial Success response.

How to Interpret the Response

1. Guaranteed 1:1 Alignment: The returned results (for ResolveNames) or entities (for ResolveMapsUrls) lists map 1:1 with the input list.
2. Empty Elements for Failures: If an item at index i failed to resolve, the result list will contain an empty object {} at index i.
3. 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 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": number, "longitude": number },
      "high": { "latitude": number, "longitude": number }
    }
  },
  "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"
  }
}