Google używa technologii AI do tłumaczenia treści na Twój preferowany język. Tłumaczenia wygenerowane przez AI mogą zawierać błędy.

Maps Tools Resolution API

Interfejs Maps Tools Resolution API jest częścią usługi Maps Grounding Lite. Udostępnia punkty końcowe przetwarzania wsadowego, które przekształcają nazwy lokalizacji i adresy URL Map Google w identyfikatory miejsc w Mapach Google. Zwrócone identyfikatory miejsc możesz wykorzystać w innych interfejsach API Google Maps Platform. Każda odpowiedź zawiera też link, który zapisuje rozwiązane miejsca jako listę w Mapach Google.

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

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

Zanim zaczniesz

Aby korzystać z interfejsu Resolution API, musisz mieć projekt w chmurze Google Cloud z włączonymi płatnościami i włączoną usługą interfejsu 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 klucze 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 X-Goog-Api-Keynagłówku 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 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.
Wielkość wsadu: maksymalnie 20 zapytań lub adresów URL na żądanie.

Każde żądanie liczy się jako 1 zapytanie, niezależnie od liczby elementów, które zawiera.

Ceny

Żądania wysyłane do interfejsów ResolveNames i ResolveMapsUrls są rozliczane bezpłatnie (0 USD) w ramach kodu SKU Places API Text Search Essentials (tylko identyfikatory). Podobnie jak w przypadku pozostałych funkcji Grounding Lite w Mapach Google, 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 wielkości wsadu: obie metody pozwalają na przesłanie maksymalnie 20 elementów w jednej prośbie.
Wymagania dotyczące ResolveNames:
- Każdy element w queries musi określać 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ć rozwiązane.
Wymagania dotyczące ResolveMapsUrls:
- Każdy adres URL musi być prawidłowym adresem URL Map Google.
- Obsługiwane formaty to:
  - 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.

Zapisywanie rozwiązanych 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 w partii, które udało się rozpoznać. Wyświetl ten link użytkownikom, którzy chcą zapisać, udostępnić lub otworzyć rozwiązane miejsca jako listę w Mapach Google.

Zawsze używaj linku zwróconego przez interfejs API. Nie twórz linku samodzielnie. Jeśli żadne elementy w partii nie zostaną rozwiązane, odpowiedź nie będzie zawierać elementu 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ę niepowodzeniem z błędem najwyższego poziomu. Zamiast tego interfejs API zwraca odpowiedź o częściowym powodzeniu, a Ty musisz sprawdzić, czy w odpowiedzi nie ma błędów dotyczących poszczególnych elementów.

Interpretowanie odpowiedzi

Gwarantowane dopasowanie 1:1: zwrócona lista results (w przypadku ResolveNames) lub lista entities (w przypadku ResolveMapsUrls) jest dopasowana do listy wejściowej w stosunku 1:1 według indeksu.
Puste elementy w przypadku błędów: jeśli nie udało się rozpoznać elementu na pozycji i, lista wyników zawiera pusty obiekt {} na pozycji i.
failedRequests mapa: odpowiedź zawiera failedRequests mapę.
- Kluczem jest indeks nieudanego elementu liczony od zera (reprezentowany jako ciąg znaków w formacie JSON).
- Wartość jest obiektem google.rpc.Status zawierającym kod błędu i komunikat wyjaśniający, dlaczego element nie został przetworzony.
saveToMapsUrl obejmuje tylko sukcesy: link saveToMapsUrl zawiera tylko elementy, które zostały rozwiązane. Nieudane elementy nie są uwzględniane.

Nie zakładaj, że cała partia się nie powiodła, ponieważ jeden element się nie powiódł. Zawsze sprawdzaj failedRequests, aby dowiedzieć się, które elementy nie zostały rozwiązane.

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

W tabeli poniżej znajdziesz listę błędów dotyczących poszczególnych produktów, które możesz zobaczyć w failedRequests:

Metoda	Przyczyna	Kod	Wiadomość
`ResolveNames`	Nie można przypisać nazwy ani adresu do miejsca.	`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, w których przypadku wystąpił błąd 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, a żądanie ResolveMapsUrls zawiera pusty adres URL lub adres URL, który nie jest syntaktycznie prawidłowy. Jeden nieprawidłowy element powoduje, że całe żądanie kończy się niepowodzeniem.
Błędy uwierzytelniania, uprawnień lub limitów: np. brak klucza interfejsu API lub jest on nieprawidłowy albo żądanie przekracza limity wykorzystania.
Błędy serwera (500 INTERNAL): ponów żądanie.

Korzystanie z interfejsu Resolution API z platformą MCP

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

resolve_names: Rozwiązuje partię nazw lokalizacji lub adresów na identyfikatory miejsc.
resolve_maps_urls: Rozwiązuje partię adresów URL Map Google na identyfikatory miejsc.

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

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

W tym przykładzie używamy curl, aby bezpośrednio wywołać narzędzie 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 zadzwonić pod numer resolve_maps_urls, ustaw name na resolve_maps_urls i przekaż tablicę urls w arguments.

Specyfikacja interfejsu REST API 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 widocznego obszaru, aby ukierunkować wyniki na region lokalny.
regionCode (Opcjonalnie): kod kraju CLDR (np. „US” lub „FR”), aby wpływać na wyniki.

Przykład polecenia curl: udane rozwiązanie

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/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ęściowa awaria)

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): powtarzana lista ciągów adresów URL Map Google do rozwiązania (maksymalnie 20).

Przykład polecenia curl: udane rozwiązanie

Poniższy przykład rozwiązuje 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ęściowa awaria)

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

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, skorzystaj z publicznego narzędzia do rejestrowania problemów Maps Grounding Lite:

Maps Tools Resolution API Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Zanim zaczniesz

Dostęp do interfejsu API i uwierzytelnianie

Klucz interfejsu API

Zakresy OAuth 2.0

Limity wykorzystania

Ceny

Weryfikacja żądań i ograniczenia

Zapisywanie rozwiązanych miejsc w Mapach Google

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

Interpretowanie odpowiedzi

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

Błędy najwyższego poziomu

Korzystanie z interfejsu Resolution API z platformą MCP

Specyfikacja interfejsu REST API i przykłady poleceń curl

ResolveNames

Metoda: POST

Format treści żądania

Przykład polecenia curl: udane rozwiązanie

Odpowiedź JSON

Przykład polecenia curl: wyniki mieszane (częściowa awaria)

Odpowiedź JSON

ResolveMapsUrls

Metoda: POST

Format treści żądania

Przykład polecenia curl: udane rozwiązanie

Odpowiedź JSON

Przykład polecenia curl: wyniki mieszane (częściowa awaria)

Odpowiedź JSON

Przykład Curl: nieudana weryfikacja

Odpowiedź JSON

Prześlij opinię

Maps Tools Resolution API