Maps Tools Resolution API (experimentell)

Die Maps Tools Resolution API bietet Endpunkte für die Batchverarbeitung, um Ortsnamen und URLs in Google Maps-Orts-IDs aufzulösen.

API-Zugriff und ‑Authentifizierung

Authentifizierungsmethoden

Die APIs unterstützen sowohl API-Schlüssel als auch OAuth 2.0-Anmeldedaten:

1. API-Schlüssel

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

https://mapstools.googleapis.com/v1alpha:resolveNames?key=YOUR_API_KEY

2. OAuth 2.0-Bereiche

Bei Verwendung der OAuth-Autorisierung werden die folgenden Bereiche unterstützt:

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

Anfragevalidierung und ‑Beschränkungen

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

  • Limit für Batchgröße: Beide APIs lassen maximal 20 Elemente pro Anfrage zu.
  • Anforderungen für ResolveNames:
    • Jedes Element von „queries“ muss einen nicht leeren Textparameter angeben.
    • Anfragen müssen einen bestimmten Ortsnamen oder eine bestimmte Adresse darstellen (z.B. „Googleplex, Mountain View, CA“, „Eiffelturm, Paris“).
    • Allgemeine kategoriale Suchanfragen (z.B. „Restaurants in New York“) oder generische Kettennamen ohne Standort (z.B. „Starbucks“) werden nicht unterstützt und können 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-Orts-URL: 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.

Umgang mit teilweisen Fehlern

Beide APIs sind als Batchprozessoren konzipiert. 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 vom Typ Teilerfolg zurück.

Antwort interpretieren

  1. Garantierte 1:1-Zuordnung: Die zurückgegebenen Ergebnislisten (für ResolveNames) oder Entitätenlisten (für ResolveMapsUrls) sind 1:1 der Eingabeliste zugeordnet.
  2. Leere Elemente bei Fehlern: Wenn ein Element mit dem Index i nicht aufgelöst werden konnte, enthält die Ergebnisliste ein leeres Objekt {} mit dem Index i.
  3. Zuordnung „failedRequests“: Die Antwort enthält eine failedRequests Zuordnung.
    • Der Schlüssel ist der nullbasierte Index des Elements, bei dem ein Fehler aufgetreten ist (als String in JSON dargestellt).
    • Der Wert ist ein google.rpc.Status-Objekt, das den spezifischen Fehlercode (aus den Standard-gRPC-/HTTP-Statuscodes) und eine detaillierte Meldung enthält, in der der Grund für den Fehler erläutert wird.

Fehler auf oberster Ebene

Ein HTTP-Fehler auf oberster Ebene (z.B. 400 Bad Request) wird nur zurückgegeben, wenn die Anfrage die Validierung nicht besteht (z.B. wenn mehr als 20 Elemente übergeben werden oder erforderliche Felder fehlen).

API-Spezifikation und Curl-Beispiele

1. ResolveNames API

Methode: POST

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

Format des Anfragetextes

{
  "queries": [
    { "text": "string" }
  ],
  "locationBias": {
    "viewport": {
      "low": { "latitude": number, "longitude": number },
      "high": { "latitude": number, "longitude": number }
    }
  },
  "regionCode": "string"
}
  • queries (erforderlich): Wiederholte Liste der aufzulösenden Anfragen (maximal 20).
  • locationBias (optional): Begrenzungsrahmen des Darstellungsbereichs, um die Ergebnisse auf eine lokale Region auszurichten.
  • regionCode (optional): CLDR-Ländercode (z.B. „US“, „FR“), um die Ergebnisse auszurichten.

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/v1alpha:resolveNames?key=KEY"
JSON-Antwort
{
  "results": [
    {
      "entity": {
        "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
      },
      "confidence": "HIGH"
    },
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ]
}

Curl-Beispiel: Gemischte Ergebnisse (teilweiser Fehler)

In diesem Beispiel ist das erste Element nicht auflösbarer Mülltext 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/v1alpha:resolveNames?key=KEY"
JSON-Antwort
{
  "results": [
    {},
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "failedRequests": {
    "0": {
      "code": 5,
      "message": "Place not found."
    }
  }
}

2. ResolveMapsUrls API

Methode: POST

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

Format des Anfragetextes

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

Curl-Beispiel: Erfolgreiche Auflösung

Auflösen eines Standardlinks zu einem Google Maps-Ort.

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-Antwort
{
  "entities": [
    {
      "place": "places/ChIJj61VQgK6j4AR4GeTYWZmomw"
    }
  ]
}

Curl-Beispiel: Gemischte Ergebnisse (teilweiser Fehler)

Auflösen einer gültigen Orts-URL und einer fehlerhaften/nicht unterstützten 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-Antwort
{
  "entities": [
    {
      "place": "places/ChIJj61VQgK6j4AR4GeTYWZmomw"
    },
    {}
  ],
  "failedRequests": {
    "1": {
      "code": 3,
      "message": "Invalid URL."
    }
  }
}

Curl-Beispiel: Validierungsfehler

Versuch, mehr als 20 URLs in einer einzelnen Anfrage zu ü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/v1alpha:resolveMapsUrls?key=KEY"
JSON-Antwort
{
  "error": {
    "code": 400,
    "message": "Request contains more than 20 URLs.",
    "status": "INVALID_ARGUMENT"
  }
}