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 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 interfejsu 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 (zalecany)

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 kategorii (np. „restauracje w Nowym Jorku”) lub ogólne nazwy sieci bez lokalizacji (np. „Starbucks”) nie są obsługiwane i mogą spowodować niepowodzenie rozpoznawania.
  • 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 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 rozpoznawanie niektórych elementów w partii się nie powiedzie, 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 rozpoznawanie elementu o indeksie i się nie powiedzie, 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) i 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 rozpoznania (maks. 20).
  • locationBias (opcjonalne): ramka ograniczająca widocznego obszaru, 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: udane rozpoznawanie

To zapytanie rozpoznaje „Googleplex” i „Wieżę 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 rozpoznania (maks. 20).

Przykład curl: udane rozpoznawanie

Rozpoznawanie 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)

Rozpoznawanie jednego prawidłowego adresu URL miejsca i jednego nieprawidłowego lub 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"
  }
}