Maps Tools Resolution API

Die Maps Tools Resolution API ist Teil von Maps Grounding Lite. Sie bietet Batch-Endpunkte, mit denen Ortsnamen und Google Maps-URLs in Google Maps-Orts-IDs aufgelöst werden. Sie können die zurückgegebenen Orts-IDs mit anderen Google Maps Platform APIs verwenden. Jede Antwort enthält auch einen Link, mit dem die aufgelösten Orte als Liste in Google Maps gespeichert werden.

Die Resolution API ist sowohl als REST-Methoden als auch als Tools auf dem Maps Grounding Lite MCP-Server verfügbar:

Hinweis

Wenn Sie die Resolution API verwenden möchten, benötigen Sie ein Google Cloud-Projekt mit aktivierter Abrechnung und aktiviertem API-Dienst Maps Grounding Lite. Eine Anleitung finden Sie unter Maps Grounding Lite-Dienst in Ihrem Google Cloud-Projekt aktivieren.

API-Zugriff und ‑Authentifizierung

Die Resolution API unterstützt sowohl API-Schlüssel als auch OAuth 2.0-Anmeldedaten.

API-Schlüssel

Sie können Anfragen authentifizieren, indem Sie einen gültigen Google Maps Platform-API-Schlüssel im X-Goog-Api-Key-Header übergeben oder an die Anfrage-URL anhängen:

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

Ersetzen Sie in den Beispielen auf dieser Seite API_KEY durch Ihren API-Schlüssel.

OAuth-2.0-Bereiche

Wenn Sie die OAuth-Autorisierung verwenden, wird der folgende Bereich unterstützt:

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

Nutzungslimits

Für die Resolution API gelten die folgenden Standardkontingente:

• ResolveNames: 600 Abfragen pro Minute und Projekt.
• ResolveMapsUrls: 600 Abfragen pro Minute und Projekt.
• Batchgröße: Bis zu 20 Suchanfragen oder URLs pro Anfrage.

Jede Anfrage zählt als eine Abfrage, unabhängig davon, wie viele Elemente sie enthält.

Preise

Anfragen an ResolveNames und ResolveMapsUrls werden unter der SKU Places API Text Search Grundlagen der Google Suche (IDs Only) mit 0 $ in Rechnung gestellt. Wie bei den anderen Funktionen von Maps Grounding Lite muss Ihrem Projekt ein Rechnungskonto zugewiesen sein.

Anfragevalidierung und Einschränkungen

Um eine übermäßige Belastung zu vermeiden und schnelle Reaktionszeiten zu gewährleisten, werden Batchanfragen streng validiert:

• Beschränkung der Batchgröße: Bei beiden Methoden sind maximal 20 Elemente pro Anfrage zulässig.
• Anforderungen für ResolveNames:
  • Für jedes Element in queries muss ein nicht leerer text-Parameter angegeben werden.
  • Anfragen müssen einen bestimmten Ortsnamen oder eine bestimmte Adresse enthalten, z. B. „Googleplex, Mountain View, CA“ oder „Eiffelturm, Paris“.
  • Allgemeine kategorische Suchanfragen (z. B. „Restaurants in New York“) oder allgemeine Kettennamen ohne Standort (z. B. „Starbucks“) werden nicht unterstützt und können möglicherweise nicht aufgelöst werden.
• Anforderungen an ResolveMapsUrls:
  • Jede URL muss eine strukturell gültige Google Maps-URL sein.
  • Unterstützte Formate:
    • Standard-Orts-URL: https://www.google.com/maps/place/...
    • Gekürzte URL: https://maps.app.goo.gl/...
  • Allgemeine anfragebasierte Maps-URLs (z. B. https://maps.google.com/?q=restaurant) und URLs, die nicht auf einen einzelnen eindeutigen Ort verweisen, werden nicht unterstützt.

Gefundene Orte in Google Maps speichern

Wenn mindestens ein Element in einem Batch aufgelöst wird, enthält die Antwort ein saveToMapsUrl-Feld. Dies ist eine einzelne Google Maps-URL, die alle erfolgreich aufgelösten Orte im Batch enthält. Stellen Sie diesen Link Nutzern zur Verfügung, die die aufgelösten Orte als Liste in Google Maps speichern, teilen oder öffnen möchten.

Verwenden Sie immer den von der API zurückgegebenen Link. Erstellen Sie den Link nicht selbst. Wenn keine Elemente im Batch aufgelöst werden, enthält die Antwort saveToMapsUrl nicht.

Teilfehler beheben

Beide Methoden sind Batchprozessoren. Wenn einige Elemente in einem Batch nicht aufgelöst werden können, schlägt die Gesamtanfrage nicht mit einem Fehler auf oberster Ebene fehl. Stattdessen gibt die API eine teilweise Erfolgsantwort zurück und Sie müssen die Antwort auf Fehler pro Element prüfen.

Antwort interpretieren

1. Garantierte 1:1-Ausrichtung: Die zurückgegebene results-Liste (für ResolveNames) oder entities-Liste (für ResolveMapsUrls) wird indexbasiert 1:1 der Eingabeliste zugeordnet.
2. Leere Elemente für Fehler: Wenn das Element am Index i nicht aufgelöst werden konnte, enthält die Ergebnisliste ein leeres Objekt {} am Index i.
3. failedRequests-Karte: Die Antwort enthält eine failedRequests-Karte.
   • Der Schlüssel ist der 0-basierte Index des fehlgeschlagenen Elements (als String in JSON dargestellt).
   • Der Wert ist ein google.rpc.Status-Objekt, das den Fehlercode und eine Meldung mit einer Erklärung enthält, warum der Artikel fehlgeschlagen ist.
4. saveToMapsUrl umfasst nur Erfolge: Der Link saveToMapsUrl enthält nur die Elemente, die behoben wurden. Fehlerhafte Artikel sind nicht enthalten.

Gehen Sie nicht davon aus, dass der gesamte Batch fehlgeschlagen ist, nur weil ein Artikel fehlgeschlagen ist. Sehen Sie immer in failedRequests nach, welche Elemente gegebenenfalls nicht behoben werden konnten.

Fehler pro Artikel

In der folgenden Tabelle sind die Fehler aufgeführt, die für einzelne Artikel in failedRequests auftreten können:

Wiederholen Sie nur die Elemente, bei denen INTERNAL aufgetreten ist.

Fehler auf oberster Ebene

Die API gibt in den folgenden Fällen einen Fehler auf oberster Ebene anstelle einer Teilantwort zurück:

• Ungültige Anfrage (400 INVALID_ARGUMENT): Die Anfrage enthält mehr als 20 Elemente, eine ResolveNames-Anfrage enthält keine Suchanfragen oder eine Suchanfrage mit einem leeren text-Wert oder eine ResolveMapsUrls-Anfrage enthält eine URL, die leer ist oder keine syntaktisch gültige URL ist. Ein ungültiger Artikel führt dazu, dass die gesamte Anfrage fehlschlägt.
• Authentifizierungs-, Berechtigungs- oder Kontingentfehler: Der API-Schlüssel fehlt oder ist ungültig oder die Anfrage überschreitet die Nutzungslimits.
• Serverfehler (500 INTERNAL): Wiederholen Sie die Anfrage.

Resolution API mit MCP verwenden

Der Maps Grounding Lite-MCP-Server unter https://mapstools.googleapis.com/mcp stellt die Resolution API als zwei Tools bereit:

• resolve_names: Löst eine Reihe von Ortsnamen oder Adressen in Orts-IDs auf.
• resolve_maps_urls: Löst eine Reihe von Google Maps-URLs in Orts-IDs auf.

Wenn Sie Ihr LLM für die Verwendung des Maps Grounding Lite-MCP-Servers konfigurieren, sind diese Tools zusammen mit den anderen Maps Grounding Lite-Tools verfügbar. Die Tools akzeptieren dieselben Eingaben, erzwingen dieselben Einschränkungen und geben dieselbe Antwort für Teilausfälle wie die REST-Methoden zurück.

Die Tool-Antworten enthalten das Feld save_to_maps_url. Die Tool-Beschreibungen weisen das LLM an, diesen Link zu präsentieren, wenn der Nutzer die aufgelösten Orte als Liste in Google Maps speichern, teilen oder öffnen möchte, anstatt selbst einen Link zu erstellen.

Im folgenden Beispiel wird curl verwendet, um das Tool resolve_names direkt aufzurufen:

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
}'

Um resolve_maps_urls aufzurufen, setzen Sie name auf resolve_maps_urls und übergeben Sie ein urls-Array in arguments.

REST API-Spezifikation und curl-Beispiele

ResolveNames

Methode: POST

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

Format des Anfragetexts

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

• queries (erforderlich): Wiederholte Liste der zu lösenden Anfragen (maximal 20).
• locationBias (Optional): Begrenzungsrahmen des Darstellungsbereichs, um Ergebnisse auf eine lokale Region auszurichten.
• regionCode (Optional): CLDR-Ländercode (z. B. „US“ oder „FR“), um die Ergebnisse zu gewichten.

Curl-Beispiel: Erfolgreiche Auflösung

Diese Anfrage löst „Googleplex“ und „Eiffelturm“ auf.

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-Antwort

{
  "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-Beispiel: Gemischte Ergebnisse (teilweiser Fehler)

In diesem Beispiel ist das erste Element Text, der nicht aufgelöst werden kann, und das zweite Element ist ein gültiger Ort.

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-Antwort

{
  "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

Methode: POST

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

Format des Anfragetexts

{
  "urls": [
    "string"
  ]
}

• urls (erforderlich): Wiederholte Liste von Google Maps-URL-Strings, die aufgelöst werden sollen (maximal 20).

Curl-Beispiel: Erfolgreiche Auflösung

Im folgenden Beispiel wird eine Standard-Google Maps-Orts-URL aufgelöst:

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-Antwort

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

Curl-Beispiel: Gemischte Ergebnisse (teilweiser Fehler)

Im folgenden Beispiel wird eine gültige Orts-URL und eine URL aufgelöst, die nicht in einen Ort aufgelöst werden kann:

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-Antwort

{
  "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-Beispiel: Validierungsfehler

Im folgenden Beispiel werden mehr als 20 URLs in einer einzelnen Anfrage übergeben:

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-Antwort

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

Feedback geben

Wenn Sie ein Problem melden oder Feedback zur Resolution API geben möchten, verwenden Sie die öffentliche Issue Tracker-Komponente „Maps Grounding Lite“:

• Fehler melden
• Feature Request senden
• Feedback geben