MCP Tools Reference: mapstools.googleapis.com

Narzędzie: compute_routes

Oblicza trasy podróży między miejscem początkowym a docelowym, opcjonalnie z przystankami pośrednimi. Zwraca odległość i czas trwania każdej trasy.

Wymagania dotyczące danych wejściowych (KRYTYCZNE):

  1. origin i destination (obiekty – WYMAGANE): każdy z nich musi być podany za pomocą dokładnie jednej z tych opcji:

    • address (ciąg znaków, np. 'Eiffel Tower, Paris'). Nazwane miejsca, punkty orientacyjne i firmy są rozpoznawane bezpośrednio, więc NIE wywołuj najpierw search_places tylko po to, aby uzyskać kod geograficzny punktu na trasie. Uwzględnij miasto, region lub kraj, o którym wspomniał użytkownik.
    • lat_lng (obiekt, {"latitude": number, "longitude": number}).
    • place_id (ciąg znaków, np. 'ChIJOwE_Id1w5EAR4Q27FkL6T_0'), na przykład z search_places.

  2. intermediate_waypoints (tablica obiektów – OPCJONALNIE): maksymalnie 10 przystanków, przez które należy przejechać, w kolejności między miejscem początkowym a docelowym. Taki sam format jak w polu origin. Nieobsługiwane w przypadku TRANSIT. Uwzględniaj tylko przystanki, o które prosi użytkownik.

  3. travel_mode (typ wyliczeniowy – OPCJONALNY): DRIVE (domyślny), WALK, BICYCLE lub TRANSIT.

  4. Czas (OPCJONALNIE – ustaw maksymalnie JEDNĄ wartość): sygnatury czasowe RFC 3339 z przesunięciem UTC, np. '2026-09-19T08:00:00-07:00'. Domyślnie jest to odjazd teraz. W przypadku TRANSIT czas może wynosić do 7 dni w przeszłości lub do 100 dni w przyszłości. W przypadku innych trybów czas może wynosić do 365 dni w przyszłości i nie może być w przeszłości.

    • departure_time: użyj, gdy użytkownik podaje, kiedy wyjeżdża (np. „jutro o 8:00”).
    • arrival_time: używaj, gdy użytkownik określa, kiedy musi dotrzeć na miejsce (np. „bądź tam o 9:00”).

  5. routing_preference (typ wyliczeniowy – OPCJONALNY):

    • ROUTING_PREFERENCE_TRAFFIC_UNAWARE (domyślna): ignoruje aktualne informacje o natężeniu ruchu, zdarzeniach drogowych i zamkniętych drogach. Najkrótszy czas oczekiwania.
    • ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL: korzysta z informacji o warunkach na drodze w czasie rzeczywistym, jeśli są dostępne. Nieobsługiwane w przypadku WALK i BICYCLE. Ustaw tę opcję TYLKO wtedy, gdy użytkownik pyta o ruch, korki lub szacowany czas dotarcia na miejsce dostosowany do natężenia ruchu. Powoduje to wyższe koszty i dłuższy czas oczekiwania.

  6. location_bias (obiekt – OPCJONALNY): {"latitude": number, "longitude": number} używany do uściślania nazw miejsc w adresach punktów orientacyjnych. Jeśli nazwa jest niejednoznaczna (np. „Springfield”), a użytkownik nie podał regionu, zachowaj nazwę podaną w polu address i ustaw pole location_bias na obszar docelowy, zamiast zgadywać region.

  7. compute_alternative_routes (wartość logiczna – OPCJONALNA): ustaw na true tylko wtedy, gdy użytkownik prosi o opcje lub alternatywne trasy. Domyślna wartość to false, co powoduje zwrócenie tylko zalecanej trasy.

  8. include_polyline (wartość logiczna – OPCJONALNA): ustaw wartość true tylko wtedy, gdy potrzebna jest geometria trasy (encoded_polyline). Domyślna wartość to false.

Instrukcje dotyczące wywołania narzędzia:

  • Jeśli brakuje miejsca wylotu lub przylotu, przed wywołaniem narzędzia MUSISZ poprosić użytkownika o wyjaśnienie.
  • W przypadku pytań typu „Jak daleko jest z A do B?” użyj B jako origin i A jako destination.

Przykładowe wywołanie narzędzia: {"origin":{"address":"Eiffel Tower"},"destination":{"place_id":"ChIJt_5xIthw5EARoJ71mGq7t74"},"intermediate_waypoints":[{"address":"Louvre Museum"}],"travel_mode":"DRIVE","departure_time":"2026-09-19T08:00:00+02:00"}

Instrukcje dotyczące odpowiedzi:

  • Gdy wysyłane jest żądanie tras alternatywnych, trasy są uporządkowane od najbardziej do najmniej zalecanych.
  • Jeśli routes jest puste, poinformuj użytkownika, że nie znaleziono trasy. Nie zgaduj trasy.
  • Podawaj tylko fakty zwrócone przez narzędzie. NIE wymyślaj szczegółowych wskazówek dojazdu, linii transportu publicznego, stacji, peronów ani przesiadek.
  • Uziemione dane wyjściowe muszą być przypisane do źródła za pomocą pola attribution każdej trasy, jeśli jest dostępne.

Poniższy przykładowy kod pokazuje, jak używać curl do wywoływania narzędzia MCP compute_routes.

Żądanie Curl 
curl --location 'https://mapstools.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "compute_routes",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Schemat wejściowy

ComputeRoutesRequest.

ComputeRoutesRequest

Zapis JSON 
{
  "origin": {
    object (Waypoint)
  },
  "destination": {
    object (Waypoint)
  },
  "travelMode": enum (RouteTravelMode),
  "intermediateWaypoints": [
    {
      object (Waypoint)
    }
  ],
  "routingPreference": enum (RoutingPreference),
  "locationBias": {
    object (LatLng)
  },
  "includePolyline": boolean,
  "computeAlternativeRoutes": boolean,

  // Union field timing can be only one of the following:
  "departureTime": string,
  "arrivalTime": string
  // End of list of possible types for union field timing.
}
Pola
origin

object (Waypoint)

Wymagane. Punkt orientacyjny punktu początkowego.
destination

object (Waypoint)

Wymagane. Punkt na trasie miejsca docelowego.
travelMode

enum (RouteTravelMode)

Opcjonalnie: Określa środek transportu.
intermediateWaypoints[]

object (Waypoint)

Opcjonalnie: Przystanki pośrednie między miejscem początkowym a docelowym, przez które należy przejechać w odpowiedniej kolejności. Obsługiwanych jest maksymalnie 10 pośrednich punktów orientacyjnych. Punkty pośrednie nie są obsługiwane, gdy parametr travel_mode ma wartość TRANSIT.
routingPreference

enum (RoutingPreference)

Opcjonalnie: Określa, jak dane o natężeniu ruchu są używane do obliczania trasy. ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL nie jest obsługiwany, gdy travel_mode ma wartość WALK lub BICYCLE. W przypadku TRANSIT umożliwia to wyświetlanie danych o transporcie publicznym w czasie rzeczywistym, takich jak opóźnienia i odwołania.
locationBias

object (LatLng)

Opcjonalnie: Lokalizacja, która ma być preferowana w wynikach wyszukiwania, np. w celu uściślenia zapytań tekstowych dotyczących punktów pośrednich.
includePolyline

boolean

Opcjonalnie: Określa, czy w trasach odpowiedzi ma być uwzględniona zakodowana linia łamana. Domyślna wartość to false. Jeśli ustawisz wartość true, zwracana jest wartość Route.encoded_polyline.
computeAlternativeRoutes

boolean

Opcjonalnie: Określa, czy oprócz zalecanej trasy mają być obliczane trasy alternatywne. Wartość domyślna to false, co oznacza, że zwracana jest tylko zalecana trasa. Jeśli ustawiona jest wartość prawda, zwracane są wszystkie dostępne trasy, ale alternatywne trasy mogą nie być dostępne w przypadku każdego żądania.
Pole zbiorcze timing. Określa, kiedy należy wyruszyć z miejsca początkowego lub dotrzeć do ostatniego punktu na trasie. Jeśli nie zostanie podany, domyślnie przyjmuje się bieżący czas odjazdu. W przypadku TRANSIT czas musi przypadać maksymalnie 7 dni w przeszłości i maksymalnie 100 dni w przyszłości. W przypadku innych środków transportu czas nie może być w przeszłości i może wynosić maksymalnie 365 dni w przyszłości. timing może mieć tylko jedną z tych wartości:
departureTime

string (Timestamp format)

Opcjonalnie: Wskazuje, że trasa powinna być obliczana na podstawie czasu wyjazdu.

Korzysta ze standardu RFC 3339, w którym wygenerowane dane wyjściowe są zawsze znormalizowane do formatu Z i zawierają 0, 3, 6 lub 9 cyfr po przecinku. Akceptowane są też przesunięcia inne niż „Z”. Przykłady: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" lub "2014-10-02T15:01:23+05:30".
arrivalTime

string (Timestamp format)

Opcjonalnie: Wskazuje, że trasa powinna być obliczana na podstawie czasu przybycia.

Korzysta ze standardu RFC 3339, w którym wygenerowane dane wyjściowe są zawsze znormalizowane do formatu Z i zawierają 0, 3, 6 lub 9 cyfr po przecinku. Akceptowane są też przesunięcia inne niż „Z”. Przykłady: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" lub "2014-10-02T15:01:23+05:30".

Sygnatura czasowa

Zapis JSON 
{
  "seconds": string,
  "nanos": integer
}
Pola
seconds

string (int64 format)

Reprezentuje sekundy czasu UTC od epoki uniksowej 1970-01-01T00:00:00Z. Musi mieścić się w zakresie od -62135596800 do 253402300799 włącznie (co odpowiada zakresowi od 0001-01-01T00:00:00Z do 9999-12-31T23:59:59Z).
nanos

integer

Nieujemne ułamki sekundy w rozdzielczości nanosekundowej. To pole zawiera nanosekundy, a nie sekundy. Ujemne wartości sekund z ułamkami muszą mieć nieujemne wartości nanosekund, które są liczone do przodu. Musi mieścić się w zakresie od 0 do 999 999 999 włącznie.

Punkt pośredni

Zapis JSON 
{

  // Union field location_type can be only one of the following:
  "latLng": {
    object (LatLng)
  },
  "placeId": string,
  "address": string
  // End of list of possible types for union field location_type.
}
Pola
Pole zbiorcze location_type. Różne sposoby przedstawiania lokalizacji. location_type może mieć tylko jedną z tych wartości:
latLng

object (LatLng)

Punkt określony za pomocą współrzędnych geograficznych.
placeId

string

Identyfikator miejsca powiązany z punktem na trasie.
address

string

Adres zrozumiały dla człowieka lub Plus Code. Więcej informacji znajdziesz na stronie https://plus.codes.

LatLng

Zapis JSON 
{
  "latitude": number,
  "longitude": number
}
Pola
latitude

number

Szerokość geograficzna w stopniach. Musi mieścić się w zakresie [-90,0, +90,0].
longitude

number

Długość geograficzna w stopniach. Musi mieścić się w zakresie [-180,0, +180,0].

RouteTravelMode

Zestaw wartości używanych do określania środka transportu.

Wartości w polu enum
ROUTE_TRAVEL_MODE_UNSPECIFIED Nie określono środka transportu. Domyślna wartość to DRIVE.
DRIVE Podróż samochodem osobowym.
WALK Podróżuj pieszo. UWAGA: trasy WALK są w wersji beta i czasami mogą nie zawierać wyraźnych chodników lub ścieżek dla pieszych. Musisz wyświetlać to ostrzeżenie użytkownikowi w przypadku wszystkich tras pieszych, które wyświetlasz w aplikacji.
BICYCLE Podróżuj rowerem.
TRANSIT Podróż transportem publicznym.

RoutingPreference

Zbiór wartości określających czynniki, które należy wziąć pod uwagę podczas obliczania trasy.

Wartości w polu enum
ROUTING_PREFERENCE_UNSPECIFIED Nie określono preferencji routingu. Domyślna wartość to ROUTING_PREFERENCE_TRAFFIC_UNAWARE.
ROUTING_PREFERENCE_TRAFFIC_UNAWARE Oblicza trasy bez uwzględniania aktualnych warunków na drodze. Odpowiednie, gdy warunki na drodze nie mają znaczenia lub nie mają zastosowania. Użycie tej wartości zapewnia najniższe opóźnienie.
ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL

Oblicza trasy, biorąc pod uwagę aktualne warunki na drodze, jeśli dane o ruchu są dostępne. W przypadku TRANSIT korzysta z danych o transporcie publicznym w czasie rzeczywistym, takich jak opóźnienia i odwołania, jeśli są dostępne.

Ta wartość spowoduje aktywowanie poziomu Pro i wyższe rozliczone koszty oraz dłuższy czas oczekiwania. Ta funkcja jest dostępna tylko dla klientów z listy dozwolonych. Jeśli nie znajduje się na liście dozwolonych, żądanie zostanie przekierowane do ROUTING_PREFERENCE_TRAFFIC_UNAWARE.

Schemat wyjściowy

ComputeRoutesResponse.

ComputeRoutesResponse

Zapis JSON 
{
  "routes": [
    {
      object (Route)
    }
  ]
}
Pola
routes[]

object (Route)

Zawiera trasy między żądanym miejscem początkowym a docelowym, uporządkowane od najbardziej do najmniej zalecanych. Zwracana jest tylko jedna trasa, chyba że parametr ComputeRoutesRequest.compute_alternative_routes ma wartość „true”.

Trasa

Zapis JSON 
{
  "distanceMeters": integer,
  "duration": string,
  "attribution": {
    object (Attribution)
  },
  "encodedPolyline": string,
  "retrievalToken": string
}
Pola
distanceMeters

integer

Odległość do pokonania na trasie w metrach.
duration

string (Duration format)

czas potrzebny na pokonanie trasy.

Czas trwania w sekundach z maksymalnie 9 miejscami po przecinku, zakończony literą „s”. Przykład: "3.5s".
attribution

object (Attribution)

Wymagane informacje o autorze, które mają być wyświetlane wraz z trasą.
encodedPolyline

string

zakodowaną linię łamaną trasy, Zobacz https://developers.google.com/maps/documentation/utilities/polylinealgorithm.
retrievalToken

string

Token, którego można użyć do pobrania tej konkretnej trasy w narzędziach podrzędnych, takich jak SearchAlongRoute. Jest ważny przez 10 minut.

Czas trwania

Zapis JSON 
{
  "seconds": string,
  "nanos": integer
}
Pola
seconds

string (int64 format)

Sekundy ze znakiem w przedziale czasu. Musi mieścić się w zakresie od -315 576 000 000 do +315 576 000 000 włącznie. Uwaga: te granice są obliczane na podstawie: 60 s/min * 60 min/godz. * 24 godz./dzień * 365,25 dnia/rok * 10 000 lat
nanos

integer

Ułamki sekundy ze znakiem w rozdzielczości nanosekundowej przedziału czasu. Czas trwania krótszy niż 1 sekunda jest reprezentowany przez pole seconds o wartości 0 oraz dodatnie lub ujemne pole nanos. W przypadku czasu trwania wynoszącego co najmniej 1 sekundę wartość pola nanos różna od zera musi mieć taki sam znak jak wartość pola seconds. Wartość musi mieścić się w zakresie od -999 999 999 do +999 999 999 włącznie.

Atrybucja

Zapis JSON 
{
  "title": string,
  "url": string
}
Pola
title

string

Tytuł, który ma być wyświetlany w atrybucji.
url

string

Adres URL, do którego ma prowadzić link w atrybucji.

Adnotacje dotyczące narzędzi

Adnotacje narzędzi są wysyłane do klientów MCP, aby opisać podstawowe ryzyko związane z danym narzędziem. Większość klientów traktuje te wskazówki jako niezaufane, ale można ich użyć do określenia, kiedy wysłać użytkownikowi prośbę o potwierdzenie.

Oprócz ciągu tytułu zdefiniowane są te wskazówki logiczne:

  • readOnlyHint: jeśli ma wartość „true”, narzędzie nie modyfikuje swojego środowiska. Wartość domyślna: false.
  • destructiveHint: jeśli ma wartość „true”, narzędzie może wykonywać działania destrukcyjne. Jeśli ma wartość false, narzędzie może wykonywać tylko działania dodawania. Wartość domyślna: true.
  • idempotentHint: jeśli ma wartość „true”, wielokrotne wywoływanie narzędzia z tymi samymi argumentami nie będzie miało dodatkowego wpływu na jego środowisko. Wartość domyślna: false.
  • openWorldHint: jeśli ma wartość true, narzędzie może wchodzić w interakcje z „otwartym światem” elementów zewnętrznych. Jeśli ma wartość false, narzędzie może wchodzić w interakcje tylko z elementami wewnętrznymi. Na przykład narzędzie do wyszukiwania w internecie jest narzędziem typu Otwarty świat, ale narzędzie do zapamiętywania już nie.

Wskazówka dotycząca destrukcyjności: ❌ | Wskazówka dotycząca idempotencji: ❌ | Wskazówka dotycząca tylko do odczytu: ✅ | Wskazówka dotycząca otwartego świata: ❌