Maps Tools Resolution API (eksperymentalny)

Interfejs Maps Tools Resolution API udostępnia punkty końcowe przetwarzania zbiorczego, które umożliwiają przekształcanie nazw lokalizacji i adresów URL na identyfikatory miejsc w Mapach Google.

Dostęp do interfejsu API i uwierzytelnianie

Metody uwierzytelniania

Interfejsy API obsługują dane logowania klucza interfejsu API i OAuth 2.0:

1. Klucz API

Żądania możesz uwierzytelniać, dołączając prawidłowy klucz interfejsu API Google Maps Platform do adresu URL żądania lub w nagłówku X-Goog-Api-Key:

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

2. Zakresy OAuth 2.0

Jeśli używasz autoryzacji OAuth, obsługiwane są te zakresy:

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

Weryfikacja żądań i ograniczenia

Aby zapobiec nadmiernemu obciążeniu i zapewnić szybki czas odpowiedzi, żądania zbiorcze są ściśle weryfikowane:

  • Limit rozmiaru partii: oba interfejsy API dopuszczają maksymalnie 20 elementów na żądanie.
  • Wymagania dotyczące ResolveNames:
    • Każdy element queries musi zawierać niepusty parametr text.
    • Zapytania muszą reprezentować konkretną nazwę miejsca lub adres (np. „Googleplex, Mountain View, CA”, „Wieża Eiffla, Paryż”).
    • Ogólne wyszukiwania według kategorii (np. „restauracje w Nowym Jorku”) lub ogólne nazwy sieci bez lokalizacji (np. „Starbucks”) nie są obsługiwane i mogą nie zostać rozpoznane.
  • Wymagania dotyczące ResolveMapsUrls:
    • Każdy adres URL musi być strukturalnie prawidłowym adresem URL Map Google.
    • Obsługiwane formaty:
      • Standardowy adres URL miejsca: https://www.google.com/maps/place/...
      • Skrócony adres URL: https://maps.app.goo.gl/...
    • Ogólne adresy URL Map Google oparte na zapytaniach (np. https://maps.google.com/?q=restaurant) i adresy URL, które nie wskazują jednego unikalnego miejsca, nie są obsługiwane.

Obsługa błędów częściowych

Oba interfejsy API są zaprojektowane jako procesory zbiorcze. Jeśli nie uda się rozpoznać niektórych elementów w partii, całe żądanie nie zakończy się niepowodzeniem z błędem najwyższego poziomu. Zamiast tego interfejs API zwraca odpowiedź Partial Success (Częściowe powodzenie).

Jak interpretować odpowiedź

  1. Gwarantowane dopasowanie 1:1: zwracane wyniki (w przypadku ResolveNames) lub encje (w przypadku ResolveMapsUrls) są mapowane 1:1 z listą danych wejściowych.
  2. Puste elementy w przypadku niepowodzeń: jeśli nie uda się rozpoznać elementu o indeksie i, lista wyników będzie zawierać pusty obiekt {} o indeksie i.
  3. Mapa failedRequests: odpowiedź zawiera failedRequests mapę.
    • Kluczem jest indeks nieudanego elementu (liczony od 0), reprezentowany jako ciąg znaków w formacie JSON.
    • Wartością jest obiekt google.rpc.Status zawierający konkretny kod błędu (ze standardowych stanów gRPC/HTTP) oraz szczegółowy komunikat wyjaśniający przyczynę niepowodzenia.

Błędy najwyższego poziomu

Błąd HTTP najwyższego poziomu (np. 400 Bad Request) jest zwracany tylko wtedy, gdy żądanie nie przejdzie weryfikacji (np. gdy przekazujesz więcej niż 20 elementów lub brakuje wymaganych pól).

Specyfikacja interfejsu API i przykłady curl

1. ResolveNames API

Metoda: POST

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

Format treści żądania

{
  "queries": [
    { "text": "string" }
  ],
  "locationBias": {
    "viewport": {
      "low": { "latitude": number, "longitude": number },
      "high": { "latitude": number, "longitude": number }
    }
  },
  "regionCode": "string"
}
  • queries (wymagane): powtarzająca się lista zapytań do rozwiązania (maks. 20).
  • locationBias (opcjonalne): pole ograniczające widok, aby wyniki były bardziej dopasowane do regionu lokalnego.
  • regionCode (opcjonalne): kod kraju CLDR (np. „US”, „FR”), aby wyniki były bardziej dopasowane.

Przykład curl: pomyślne rozwiązanie

To zapytanie rozwiązuje „Googleplex” i „Wieża Eiffla”.

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"
Odpowiedź JSON
{
  "results": [
    {
      "entity": {
        "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
      },
      "confidence": "HIGH"
    },
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ]
}

Przykład curl: wyniki mieszane (częściowe niepowodzenie)

W tym przykładzie pierwszy element to nieczytelny tekst, a drugi to prawidłowe miejsce.

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"
Odpowiedź JSON
{
  "results": [
    {},
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "failedRequests": {
    "0": {
      "code": 5,
      "message": "Place not found."
    }
  }
}

2. ResolveMapsUrls API

Metoda: POST

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

Format treści żądania

{
  "urls": [
    "string"
  ]
}
  • urls (wymagane): powtarzająca się lista ciągów adresów URL Map Google do rozwiązania (maks. 20).

Przykład curl: pomyślne rozwiązanie

Rozwiązywanie standardowego linku do miejsca w Mapach Google.

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

Przykład curl: wyniki mieszane (częściowe niepowodzenie)

Rozwiązywanie jednego prawidłowego adresu URL miejsca i jednego nieprawidłowego/nieobsługiwanego adresu 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"
Odpowiedź JSON
{
  "entities": [
    {
      "place": "places/ChIJj61VQgK6j4AR4GeTYWZmomw"
    },
    {}
  ],
  "failedRequests": {
    "1": {
      "code": 3,
      "message": "Invalid URL."
    }
  }
}

Przykład curl: nieudana weryfikacja

Próba przekazania więcej niż 20 adresów URL w jednym żądaniu.

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"
Odpowiedź JSON
{
  "error": {
    "code": 400,
    "message": "Request contains more than 20 URLs.",
    "status": "INVALID_ARGUMENT"
  }
}