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ą zarówno klucz interfejsu API , jak i dane logowania 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ą 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ą wejściową.
2. Puste elementy w przypadku błędów: 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) 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. Interfejs 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 (wymagany): powtarzająca się lista zapytań do rozwiązania (maks. 20).
• locationBias (opcjonalny): ramka ograniczająca widocznego obszaru, która ma wpływać na wyniki w regionie lokalnym.
• regionCode (opcjonalny): kod kraju CLDR (np. „US”, „FR”), który ma wpływać na wyniki.

Przykład curl: pomyślne rozwiązanie

To zapytanie rozwiązuje „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, którego nie można rozpoznać, a drugi element 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. Interfejs ResolveMapsUrls API

Metoda: POST

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

Format treści żądania

{
  "urls": [
    "string"
  ]
}

• urls (wymagany): 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 1 prawidłowego adresu URL miejsca i 1 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"
  }
}