Maps Tools Resolution API

Interfejs Maps Tools Resolution API jest częścią Maps Grounding Lite. Udostępnia on punkty końcowe zbiorcze, które rozpoznają nazwy lokalizacji i adresy URL Map Google jako identyfikatory miejsc w Mapach Google. Zwróconych identyfikatorów miejsc możesz używać z innymi interfejsami API Google Maps Platform. Każda odpowiedź zawiera też link, który zapisuje znalezione miejsca jako listę w Mapach Google.

Interfejs Resolution API jest dostępny zarówno jako metody REST, jak i narzędzia na serwerze Maps Grounding Lite MCP:

Możliwości Metoda REST Narzędzie MCP
rozpoznawanie nazw lub adresów lokalizacji jako miejsc; resolveNames resolve_names
Rozpoznawanie adresów URL Map Google jako miejsc resolveMapsUrls resolve_maps_urls

Zanim zaczniesz

Aby korzystać z interfejsu Resolution API, musisz mieć projekt Google Cloud z włączonymi płatnościami i włączoną usługą interfejsu API Maps Grounding Lite. Instrukcje znajdziesz w artykule Włączanie usługi Maps Grounding Lite w projekcie Google Cloud.

Dostęp do interfejsu API i uwierzytelnianie

Interfejs Resolution API obsługuje zarówno klucz interfejsu API, jak i dane logowania OAuth 2.0.

Klucz interfejsu API

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

https://mapstools.googleapis.com/v1:resolveNames?key=API_KEY

W przykładach na tej stronie zastąp API_KEY swoim kluczem interfejsu API.

Zakresy OAuth 2.0

Jeśli używasz autoryzacji OAuth, obsługiwany jest ten zakres:

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

Limity wykorzystania

W przypadku interfejsu Resolution API obowiązują te domyślne limity:

  • ResolveNames: 600 zapytań na minutę na projekt.
  • ResolveMapsUrls: 600 zapytań na minutę na projekt.
  • Rozmiar wsadu: do 20 zapytań lub adresów URL na żądanie.

Każde żądanie jest liczone jako jedno zapytanie, niezależnie od tego, ile elementów zawiera.

Ceny

Żądania do ResolveNames i ResolveMapsUrls są rozliczane bezpłatnie (0 USD) w ramach kodu SKU Places API Wyszukaj tekst Essentials (IDs Only). Podobnie jak w przypadku pozostałych funkcji Grounding Lite w Mapach, Twój projekt musi mieć konto rozliczeniowe.

Weryfikacja żądań i ograniczenia

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

  • Limit rozmiaru wsadu: obie metody umożliwiają przesłanie maksymalnie 20 elementów na żądanie.
  • Wymagania dotyczące ResolveNames:
    • Każdy element w parametrze queries musi mieć określony niepusty parametr text.
    • Zapytania muszą zawierać konkretną nazwę miejsca lub adres (np. „Googleplex, Mountain View, CA” lub „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 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 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.

Zapisywanie rozpoznanych miejsc w Mapach Google

Jeśli co najmniej 1 element w partii zostanie rozwiązany, odpowiedź będzie zawierać pole saveToMapsUrl. Jest to pojedynczy link do Map Google, który zawiera wszystkie miejsca z partii, które udało się rozpoznać. Przedstaw ten link użytkownikom, którzy chcą zapisać, udostępnić lub otworzyć znalezione miejsca jako listę w Mapach Google.

Zawsze używaj linku zwróconego przez interfejs API. Nie twórz linku samodzielnie. Jeśli nie uda się rozpoznać żadnego elementu w partii, odpowiedź nie będzie zawierać pola saveToMapsUrl.

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

Obie metody są procesorami wsadowymi. Jeśli nie uda się rozwiązać niektórych elementów w partii, całe żądanie nie zakończy się błędem najwyższego poziomu. Zamiast tego interfejs API zwraca odpowiedź o częściowym powodzeniu, a Ty musisz sprawdzić, czy nie wystąpiły błędy dotyczące poszczególnych elementów.

Interpretowanie odpowiedzi

  1. Gwarantowane dopasowanie 1:1: zwrócona lista results (w przypadku ResolveNames) lub entities (w przypadku ResolveMapsUrls) jest mapowana 1:1 z listą wejściową według indeksu.
  2. Puste elementy w przypadku niepowodzeń: jeśli nie udało się rozpoznać elementu o indeksie i, lista wyników zawiera pusty obiekt {} o indeksie i.
  3. Mapa failedRequests: odpowiedź zawiera mapę failedRequests.
    • Klucz to indeks elementu, który się nie powiódł, liczony od 0 (reprezentowany jako ciąg znaków w formacie JSON).
    • Wartość to obiekt google.rpc.Status zawierający kod błędu i komunikat wyjaśniający, dlaczego nie udało się przetworzyć elementu.
  4. saveToMapsUrl covers only successes (obejmuje tylko sukcesy): link saveToMapsUrl zawiera tylko elementy, które zostały rozwiązane. Elementy, których nie udało się przenieść, nie są uwzględniane.

Nie zakładaj, że cały wsad się nie powiódł, ponieważ jeden element się nie powiódł. Zawsze sprawdzaj failedRequests, aby dowiedzieć się, których elementów nie udało się rozwiązać.

Błędy dotyczące poszczególnych elementów

W tabeli poniżej znajdziesz listę błędów dotyczących poszczególnych elementów, które mogą się pojawić w failedRequests:

Metoda Przyczyna Kod Wiadomość
ResolveNames Nie można znaleźć miejsca o podanej nazwie lub adresie. 5 (NOT_FOUND) Place not found.
ResolveMapsUrls Nie można powiązać adresu URL z miejscem. 3 (INVALID_ARGUMENT) Failed to resolve Maps URL to a place.
Obie metody Podczas rozwiązywania problemu z elementem wystąpił błąd wewnętrzny. 13 (INTERNAL) Internal server error. Please retry. If the problem persists, please open a support case. https://goo.gle/maps-platform-support

Ponów próbę tylko w przypadku elementów, które nie powiodły się z powodu błędu INTERNAL.

Błędy najwyższego poziomu

W tych przypadkach interfejs API zwraca błąd najwyższego poziomu zamiast odpowiedzi częściowej:

  • Nieprawidłowe żądanie (400 INVALID_ARGUMENT): żądanie zawiera więcej niż 20 elementów, żądanie ResolveNames nie zawiera zapytań lub zawiera zapytanie z pustą wartością text albo żądanie ResolveMapsUrls zawiera adres URL, który jest pusty lub nie jest prawidłowy pod względem składni. Jeden nieprawidłowy element powoduje niepowodzenie całego żądania.
  • Błędy uwierzytelniania, uprawnień lub limitów: na przykład brak klucza interfejsu API lub jego nieprawidłowość albo żądanie przekraczające limity wykorzystania.
  • Błędy serwera (500 INTERNAL): ponów żądanie.

Korzystanie z interfejsu Resolution API z MCP

Serwer MCP Maps Grounding Lite pod adresem https://mapstools.googleapis.com/mcp udostępnia interfejs Resolution API jako 2 narzędzia:

  • resolve_names: rozpoznaje grupę nazw lokalizacji lub adresów i przypisuje im identyfikatory miejsc.
  • resolve_maps_urls: rozpoznaje grupę adresów URL Map Google jako identyfikatory miejsc.

Gdy skonfigurujesz LLM do korzystania z serwera MCP Maps Grounding Lite, te narzędzia będą dostępne wraz z innymi narzędziami Maps Grounding Lite. Narzędzia akceptują te same dane wejściowe, wymuszają te same ograniczenia i zwracają tę samą odpowiedź o częściowym niepowodzeniu co metody REST.

Odpowiedzi narzędzia zawierają pole save_to_maps_url. Opisy narzędzi instruują LLM, aby wyświetlał ten link, gdy użytkownik chce zapisać, udostępnić lub otworzyć znalezione miejsca jako listę w Mapach Google, zamiast samodzielnie tworzyć link.

W tym przykładzie używamy curl do bezpośredniego wywołania narzędzia resolve_names:

curl --location 'https://mapstools.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--header 'X-Goog-Api-Key: API_KEY' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "resolve_names",
    "arguments": {
      "queries": [
        { "text": "Googleplex, Mountain View, CA" },
        { "text": "Eiffel Tower, Paris" }
      ]
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Aby wywołać resolve_maps_urls, ustaw name na resolve_maps_urls i przekaż tablicę urls w arguments.

Specyfikacja interfejsu API typu REST i przykłady poleceń curl

ResolveNames

Metoda: POST

https://mapstools.googleapis.com/v1: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 (maksymalnie 20).
  • locationBias (opcjonalnie): ramka ograniczająca widoczny obszar, która pozwala faworyzować wyniki z regionu lokalnego.
  • regionCode (opcjonalnie): kod kraju CLDR (np. „US” lub „FR”) do faworyzowania wyników.

Przykład polecenia curl: udane rozwiązanie

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/v1:resolveNames?key=API_KEY"
Odpowiedź JSON
{
  "results": [
    {
      "entity": {
        "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
      },
      "confidence": "HIGH"
    },
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw,ChIJLU7jZClu5kcR4PcOOO6p3I0"
}

Przykład polecenia curl: wyniki mieszane (częściowy błąd)

W tym przykładzie pierwszy element to tekst, którego nie można rozpoznać, 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/v1:resolveNames?key=API_KEY"
Odpowiedź JSON
{
  "results": [
    {},
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "failedRequests": {
    "0": {
      "code": 5,
      "message": "Place not found."
    }
  },
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJLU7jZClu5kcR4PcOOO6p3I0"
}

ResolveMapsUrls

Metoda: POST

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

Format treści żądania

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

Przykład polecenia curl: udane rozwiązanie

Poniższy przykład rozpoznaje standardowy adres URL 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!1s0x808fba02425dad8f:0x6c296c66619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6"
]
}' \
"https://mapstools.googleapis.com/v1:resolveMapsUrls?key=API_KEY"
Odpowiedź JSON
{
  "entities": [
    {
      "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
    }
  ],
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw"
}

Przykład polecenia curl: wyniki mieszane (częściowy błąd)

Poniższy przykład rozpoznaje 1 prawidłowy adres URL miejsca i 1 adres URL, którego nie można rozpoznać jako miejsca:

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!1s0x808fba02425dad8f:0x6c296c66619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6",
    "https://www.google.com/not-a-place"
  ]
}' \
"https://mapstools.googleapis.com/v1:resolveMapsUrls?key=API_KEY"
Odpowiedź JSON
{
  "entities": [
    {
      "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
    },
    {}
  ],
  "failedRequests": {
    "1": {
      "code": 3,
      "message": "Failed to resolve Maps URL to a place."
    }
  },
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw"
}

Przykład Curl: niepowodzenie weryfikacji

W tym przykładzie w jednym żądaniu przekazywanych jest ponad 20 adresów URL:

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

Prześlij opinię

Aby zgłosić problem lub podzielić się opinią na temat interfejsu Resolution API, użyj komponentu publicznego narzędzia do śledzenia problemów Maps Grounding Lite: