Maps Tools Resolution API (experimentell)

Die Maps Tools Resolution API bietet Batchverarbeitungs-Endpunkte, mit denen Ortsnamen und URLs in Google Maps-Orts-IDs aufgelöst werden können.

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 X-Goog-Api-Key-Header 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 ‑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 APIs sind maximal 20 Elemente pro Anfrage zulässig.
  • Anforderungen an ResolveNames:
    • Für jedes „queries“-Element muss ein nicht leerer Textparameter angegeben werden.
    • Anfragen müssen einen bestimmten Ortsnamen oder eine bestimmte Adresse enthalten, z.B. „Googleplex, Mountain View, CA“ oder „Eiffelturm, Paris“.
    • Allgemeine kategoriale Suchanfragen (z.B. „Restaurants in New York“) oder allgemeine Kettennamen ohne Standort (z.B. „Starbucks“) werden nicht unterstützt und können zu einem Fehler bei der Auflösung führen.
  • 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 abfragebasierte Google Maps-URLs (z.B. https://maps.google.com/?q=restaurant) und URLs, die nicht auf einen einzelnen eindeutigen Ort verweisen, werden nicht unterstützt.

Teilfehler beheben

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 Teilerfolg-Antwort zurück.

Antwort interpretieren

  1. Garantierte 1:1-Übereinstimmung: Die zurückgegebenen Ergebnislisten (für ResolveNames) oder Entitätslisten (für ResolveMapsUrls) stimmen 1:1 mit der Eingabeliste überein.
  2. Leere Elemente bei Fehlern: Wenn ein Element am Index i nicht aufgelöst werden konnte, enthält die Ergebnisliste ein leeres Objekt {} am Index i.
  3. failedRequests-Map: Die Antwort enthält eine failedRequests-Map.
    • Der key ist der nullbasierte Index des fehlgeschlagenen Elements (als String in JSON dargestellt).
    • Der Wert ist ein google.rpc.Status-Objekt, das den spezifischen Fehlercode (aus Standard-gRPC-/HTTP-Status) und eine detaillierte Meldung mit einer Erklärung für den Fehler enthält.

Fehler der obersten Ebene

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

API-Spezifikation und Curl-Beispiele

1. ResolveNames API

Methode: POST

https://mapstools.googleapis.com/v1alpha: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 (max. 20).
  • locationBias (Optional): Begrenzungsrahmen des Darstellungsbereichs, um Ergebnisse auf eine lokale Region auszurichten.
  • regionCode (Optional): CLDR-Ländercode (z.B. „US“, „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/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)

Im 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 Anfragetexts

{
  "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 Standard-Ortslinks in Google Maps

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)

Eine gültige Orts-URL und eine fehlerhafte/nicht unterstützte URL werden 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!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

Sie versuchen, 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"
  }
}