Maps Tools Resolution API (eksperymentalny)

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

Dostęp do interfejsu API i uwierzytelnianie

Metody uwierzytelniania

Interfejsy API obsługują zarówno klucz API, jak i dane uwierzytelniające OAuth 2.0:

1. Klucz interfejsu API

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

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)

Żądanie weryfikacji i ograniczeń

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

  • Limit rozmiaru grupy: oba interfejsy API umożliwiają przesyłanie maksymalnie 20 elementów w jednym żądaniu.
  • Wymagania dotyczące ResolveNames:
    • Każdy element zapytania musi określać niepusty parametr tekstowy.
    • Zapytania muszą zawierać konkretną nazwę miejsca lub adres (np. „Googleplex, Mountain View, CA”, „Wieża Eiffla, Paryż”).
    • Ogólne wyszukiwania 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ć prawidłowym adresem URL Map Google.
    • Obsługiwane formaty:
      • Standardowy adres URL miejsca: https://www.google.com/maps/place/...
      • Skrócony URL: https://maps.app.goo.gl/...
    • Ogólne adresy URL Map oparte na zapytaniach (np.https://maps.google.com/?q=restaurant) i adresy URL, które nie wskazują jednego, niepowtarzalnego miejsca, nie są obsługiwane.

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

Oba interfejsy API są zaprojektowane jako procesory wsadowe. Jeśli niektóre elementy w żądaniu zbiorczym nie zostaną rozwiązane, całe żądanie nie zakończy się niepowodzeniem z błędem najwyższego poziomu. Zamiast tego interfejs API zwraca odpowiedź Częściowe powodzenie.

Interpretowanie odpowiedzi

  1. Gwarantowane dopasowanie 1:1: zwrócone wyniki (w przypadku ResolveNames) lub listy podmiotów (w przypadku ResolveMapsUrls) są dopasowane do listy wejściowej w stosunku 1:1.
  2. Puste elementy w przypadku błędów: jeśli nie udało się rozpoznać elementu o indeksie i, lista wyników będzie zawierać pusty obiekt {} o indeksie i.
  3. failedRequests Map: odpowiedź zawiera mapę failedRequests.
    • Klucz to indeks nieudanego elementu liczony od zera (reprezentowany w JSON jako ciąg znaków).
    • Wartość to obiekt google.rpc.Status zawierający konkretny kod błędu (ze standardowych stanów gRPC/HTTP) i szczegółowy komunikat wyjaśniający, dlaczego operacja się nie powiodła.

Błędy najwyższego poziomu

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

Specyfikacja interfejsu API i przykłady poleceń 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): powtarzana lista zapytań do rozwiązania (maks. 20).
  • locationBias (Opcjonalnie): ramka ograniczająca widocznego obszaru, aby kierować wyniki na region lokalny.
  • regionCode (Opcjonalnie): kod kraju CLDR (np. „US”, „FR”), aby zawęzić wyniki.

Przykład polecenia curl: rozwiązanie problemu

To zapytanie rozwiązuje problemy z lokalizacjami „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 polecenia curl: wyniki mieszane (częściowa awaria)

W tym przykładzie pierwszy element to nieprawidłowy 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 (Wymagany): powtarzana lista ciągów URL Map Google do rozwiązania (maks. 20).

Przykład polecenia curl: rozwiązanie problemu

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 polecenia curl: wyniki mieszane (częściowa awaria)

Rozwiązywanie jednego prawidłowego adresu URL miejsca i jednego adresu URL o nieprawidłowym formacie lub nieobsługiwanego.

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 polecenia curl: nieudana weryfikacja

Próbujesz przekazać 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"
  }
}