Maps Tools Resolution API

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

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 Maps Grounding Lite-API-Dienst. 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 Header X-Goog-Api-Key übergeben oder an die Anfrage-URL anhängen:

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

Ersetzen Sie API_KEY in den Beispielen auf dieser Seite 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 Anfragen pro Minute und Projekt.
• Batchgröße: Bis zu 20 Abfragen 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 kostenlos (0 $) unter der SKU Places API Text Search Essentials (IDs Only) abgerechnet. Wie für den Rest von Maps Grounding Lite muss für Ihr Projekt ein Rechnungskonto vorhanden sein.

Anfragevalidierung und Einschränkungen

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

• Batchgrößenlimit: Beide Methoden erlauben maximal 20 Elemente pro Anfrage.
• Anforderungen für ResolveNames:
  • Für jedes Element in queries muss ein nicht leerer text-Parameter angegeben werden.
  • Suchanfragen müssen einen bestimmten Ortsnamen oder eine bestimmte Adresse enthalten, z. B. „Googleplex, Mountain View, CA“ oder „Eiffelturm, Paris“.
  • Allgemeine Kategoriesuchen (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 für „ResolveMapsUrls“:
  • Jede URL muss eine strukturell gültige Google Maps-URL sein.
  • Zu den unterstützten Formaten gehören:
    • Standard-URL des Orts: https://www.google.com/maps/place/...
    • Gekürzte URL: https://maps.app.goo.gl/...
  • Allgemeine abfragebasierte Maps-URLs (z. B. https://maps.google.com/?q=restaurant) und URLs, die nicht auf einen einzelnen eindeutigen Ort verweisen, werden nicht unterstützt.

Aufgelöste 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. Präsentieren Sie diesen Link Nutzern, 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 nicht saveToMapsUrl.

Teilfehler verarbeiten

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 Antwort mit Teilerfolg zurück und Sie müssen die Antwort auf Fehler pro Element prüfen.

Antwort interpretieren

1. Garantierte 1:1-Zuordnung: Die zurückgegebene results-Liste (für ResolveNames) oder entities-Liste (für ResolveMapsUrls) wird 1:1 mit der Eingabeliste nach Index 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 nullbasierte Index des fehlgeschlagenen Elements (als String in JSON dargestellt).
   • Der Wert ist ein google.rpc.Status-Objekt, das den Fehlercode und eine Meldung enthält, in der erklärt wird, warum das Element fehlgeschlagen ist.
4. saveToMapsUrl deckt nur Erfolge ab: Der Link saveToMapsUrl enthält nur die Elemente, die aufgelöst wurden. Fehlgeschlagene Elemente sind nicht enthalten.

Gehen Sie nicht davon aus, dass der gesamte Batch fehlgeschlagen ist, nur weil ein Element fehlgeschlagen ist. Prüfen Sie immer failedRequests, um herauszufinden, welche Elemente gegebenenfalls nicht aufgelöst werden konnten.

Fehler pro Element

In der folgenden Tabelle sind die Fehler pro Element aufgeführt, die in failedRequests auftreten können:

Wiederholen Sie nur die Elemente, die mit INTERNAL fehlgeschlagen sind.

Fehler auf oberster Ebene

In den folgenden Fällen gibt die API 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 Abfragen oder eine Abfrage mit einem leeren text-Wert oder eine ResolveMapsUrls-Anfrage enthält eine URL, die leer oder syntaktisch ungültig ist. Ein ungültiges Element führt dazu, dass die gesamte Anfrage fehlschlägt.
• Authentifizierungs-, Berechtigungs- oder Kontingentfehler: Beispielsweise fehlt der API-Schlüssel 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 einen Batch von Ortsnamen oder Adressen in Orts-IDs auf.
• resolve_maps_urls: Löst einen Batch 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 bei teilweisem Fehlschlagen zurück wie die REST-Methoden.

Die Toolantworten enthalten das Feld save_to_maps_url. Die Toolbeschreibungen 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 resolve_names-Tool 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
}'

Wenn Sie resolve_maps_urls aufrufen möchten, 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 aufzulösenden Abfragen (maximal 20).
• locationBias (optional): Begrenzungsrahmen des Darstellungsbereichs, um die Ergebnisse auf eine lokale Region auszurichten.
• regionCode (optional): CLDR-Ländercode (z. B. „US“ oder „FR“), um die Ergebnisse zu beeinflussen.

Curl-Beispiel: Erfolgreiche Auflösung

Diese Abfrage 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 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 für Maps Grounding Lite:

• Fehler melden
• Feature Request senden
• Feedback geben