MCP Tools Reference: mapstools.googleapis.com

Narzędzie: search_along_route

Wywołaj to narzędzie, gdy użytkownik chce znaleźć miejsca, firmy lub punkty orientacyjne na trasie podróży (np. „stacje benzynowe na trasie do Tahoe”, „kawiarnie między SF a San Jose”). Wywołanie tego narzędzia wiąże się z wyższymi kosztami niż w przypadku search_places, dlatego używaj search_places, gdy wyszukujesz miejsca w pobliżu jednej lokalizacji, a nie na trasie.

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

  1. text_query (ciąg znaków – WYMAGANY): opis w języku naturalnym tego, czego szukać na trasie.

    • Przykłady: 'ev chargers', 'coffee', 'vegetarian restaurants', 'rest stops'.

  2. Specyfikacja trasy (WYMAGANA – podaj dokładnie JEDNĄ z tych opcji):

    • retrieval_token (ciąg tekstowy): retrieval_token zwrócony przez poprzednie wywołanie compute_routes dla trasy DRIVE. Używaj tej opcji, gdy trasa została już obliczona. Token jest ważny przez 10 minut.
    • route_endpoints (obiekt): origin i destination trasy. Każdy z nich musi być podany za pomocą jednego z tych elementów: address, lat_lng lub place_id.
      • Przykład: {"route_endpoints": {"origin": {"address": "San Francisco, CA"}, "destination": {"address": "Lake Tahoe, CA"}}}
    • encoded_polyline (ciąg znaków): zakodowana linia łamana reprezentująca trasę DRIVE.

  3. travel_mode (typ wyliczeniowy – OPCJONALNY): DRIVE (domyślny), WALK lub BICYCLE. Atrybuty WALK i BICYCLE są obsługiwane tylko w przypadku route_endpoints. TRANSIT nie jest obsługiwany.

  4. routing_preference (typ wyliczeniowy – OPCJONALNY):

    • ROUTING_PREFERENCE_TRAFFIC_UNAWARE (domyślna): oblicza trasę i objazdy bez uwzględniania informacji o aktualnym natężeniu ruchu. 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 natężenie ruchu, korki lub czas objazdu dostosowany do natężenia ruchu. Powoduje dłuższy czas oczekiwania.

  5. include_extended_details (wartość logiczna – OPCJONALNA): ustaw wartość true tylko wtedy, gdy żądanie wymaga statystyk dotyczących opinii jakościowych, konkretnych pozycji menu lub ofert, atmosfery, wskazówek dla odwiedzających lub natężenia ruchu, dostępności ładowarek EV, cen paliwa lub innych szczegółowych informacji jakościowych. Domyślna wartość to false. Włączenie tej opcji może wydłużyć czas oczekiwania.

  6. language_code (ciąg znaków – OPCJONALNY): język podsumowania wyników i informacji o miejscu, np. en, ja, en-US. Domyślna wartość to en-US.

  7. region_code (ciąg znaków – OPCJONALNY): kod regionu Unicode CLDR użytkownika, np. US, CA.

Instrukcje dotyczące wywołania narzędzia:

  • Każdy wynik zawiera detour_summary (jeśli jest dostępny) opisujący dodatkową odległość (localized_detour_distance) i, o ile trasa nie została podana jako encoded_polyline, dodatkowy czas (detour_duration) związany z zatrzymaniem się w tym miejscu. Użyj go, aby porównać opcje.
  • Odpowiedź summary może zawierać cytaty indeksowane od zera (np. „[0]”) odwołujące się do wpisów w results.
  • Uziemione dane wyjściowe muszą być przypisane do źródła za pomocą pola attribution każdego elementu results[].place, jeśli jest dostępne.

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

Żą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": "search_along_route",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Schemat wejściowy

Wiadomość z żądaniem dla SearchAlongRoute.

SearchAlongRouteRequest

Zapis JSON 
{
  "textQuery": string,
  "languageCode": string,
  "regionCode": string,
  "routingPreference": enum (RoutingPreference),
  "includeExtendedDetails": boolean,
  "travelMode": enum (RouteTravelMode),

  // Union field route_spec can be only one of the following:
  "encodedPolyline": string,
  "retrievalToken": string,
  "routeEndpoints": {
    object (RouteEndpoints)
  }
  // End of list of possible types for union field route_spec.
}
Pola
textQuery

string

Wymagane. Zapytanie w języku naturalnym (np. „ładowarki EV”, „kawa”).
languageCode

string

Opcjonalnie. Język podsumowania i informacji o miejscu. Domyślna wartość to „en-US”.
regionCode

string

Opcjonalnie. Kod kraju/regionu (CLDR) lokalizacji (np. „US”).
routingPreference

enum (RoutingPreference)

Opcjonalnie. Opcjonalne ustawienie routingu określające sposób wykorzystania danych o ruchu. Domyślna wartość to TRAFFIC_UNAWARE.
includeExtendedDetails

boolean

Opcjonalnie. Zawiera w odpowiedzi rozszerzone informacje o miejscu.

Ustaw to pole na true, gdy prośba użytkownika wymaga szczegółowych informacji jakościowych, dynamicznych danych w czasie rzeczywistym lub specjalistycznych atrybutów podmiotu: – opinie jakościowe, nastroje klientów i opinie. - konkretne oferty, takie jak pozycje menu, dania, specjały, napoje lub najważniejsze informacje o firmie; – jakościowa atmosfera, wystrój wnętrza, estetyka, nastrój lub klimat; – Dane w czasie rzeczywistym i specjalistyczne informacje o placówkach, zasady i wskazówki dla odwiedzających, czasy oczekiwania.

Pozostaw wartość false (domyślną) w przypadku standardowych wyszukiwań (np. kuchni, typów sklepów), wyszukiwania lokalizacji/adresu, informacji kontaktowych, godzin otwarcia i standardowych metadanych/udogodnień.

Włączenie tego pola może spowodować większe opóźnienie.
travelMode

enum (RouteTravelMode)

Opcjonalnie. Określa środek transportu używany do obliczania trasy i objazdów. Domyślna wartość to DRIVE. Atrybuty WALK i BICYCLE są obsługiwane tylko w przypadku route_endpoints. TRANSIT nie jest obsługiwany.
Pole zbiorcze route_spec. Specyfikacja trasy: istniejąca trasa, token trasy lub punkty końcowe miejsca początkowego i docelowego. route_spec może mieć tylko jedną z tych wartości:
encodedPolyline

string

Zakodowany ciąg znaków linii łamanej reprezentujący trasę. Więcej informacji znajdziesz na stronie https://developers.google.com/maps/documentation/utilities/polylinealgorithm.
retrievalToken

string

Token pobierania zwrócony z poprzedniego wywołania ComputeRoutes reprezentującego trasę.
routeEndpoints

object (RouteEndpoints)

jawne punkty końcowe trasy (miejsce początkowe i docelowe);

RouteEndpoints

Zapis JSON 
{
  "origin": {
    object (Waypoint)
  },
  "destination": {
    object (Waypoint)
  }
}
Pola
origin

object (Waypoint)

Wymagane. Punkt początkowy (adres, identyfikator miejsca lub współrzędne geograficzne).
destination

object (Waypoint)

Wymagane. Punkt docelowy (adres, identyfikator miejsca lub współrzędne geograficzne).

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 pośrednim.
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].

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. Odpowiedni, gdy warunki na drodze nie mają znaczenia lub nie dotyczy. Użycie tej wartości zapewnia najniższe opóźnienie.
ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL

Oblicza trasy z uwzględnieniem aktualnych warunków 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 aktywację poziomu Pro i zwiększenie rozliczonych kosztów oraz czasu oczekiwania.

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 Spaceruj. UWAGA: trasy WALK są w wersji beta i czasami mogą nie uwzględniać chodników lub ścieżek dla pieszych. Musisz wyświetlać to ostrzeżenie użytkownikowi w przypadku wszystkich tras pieszych wyświetlanych w aplikacji.
BICYCLE Podróżuj rowerem.
TRANSIT Podróżuj transportem publicznym.

Schemat wyjściowy

Wiadomość z odpowiedzią dla SearchAlongRoute.

SearchAlongRouteResponse

Zapis JSON 
{
  "results": [
    {
      object (Result)
    }
  ],
  "summary": string,
  "contentToken": string
}
Pola
results[]

object (Result)

Tylko dane wyjściowe. Uporządkowana lista wyników wyszukiwania znalezionych na trasie.
summary

string

Tylko dane wyjściowe. Podsumowanie wyników wyszukiwania i objazdów w języku naturalnym. Może zawierać cytaty indeksowane od zera (np. „[0]”, „[1]”) odwołujące się do odpowiednich wpisów na liście results.
contentToken

string

Tylko dane wyjściowe. Zaszyfrowany token, który zawiera kontekst wyszukiwania i może być przekazywany do usług renderowania wizualnego Map Google, pakietów SDK lub zestawu agentowych narzędzi interfejsu Map (A2UI) w celu wyświetlania interaktywnych komponentów interfejsu dla zwróconych wyników wyszukiwania.

Wynik

Zapis JSON 
{
  "place": {
    object (PlaceView)
  },
  "detourSummary": {
    object (DetourSummary)
  }
}
Pola
place

object (PlaceView)

Tylko dane wyjściowe. Szczegółowe informacje o miejscu znalezionym na trasie.
detourSummary

object (DetourSummary)

Tylko dane wyjściowe. Wskaźniki objazdu, które zostały naliczone po dodaniu tego miejsca jako przystanku pośredniego na trasie. Pominięte lub puste, jeśli nie udało się obliczyć danych dotyczących objazdu.

PlaceView

Zapis JSON 
{
  "place": string,
  "id": string,
  "googleMapsLinks": {
    object (GoogleMapsLinks)
  },
  "attribution": {
    object (Attribution)
  },

  // Union field _location can be only one of the following:
  "location": {
    object (LatLng)
  }
  // End of list of possible types for union field _location.
}
Pola
place

string

Nazwa zasobu miejsca docelowego w formacie „places/{id}”.
id

string

Identyfikator miejsca, w którym znajduje się dany punkt.
googleMapsLinks

object (GoogleMapsLinks)

Linki do wywoływania różnych działań w Mapach Google.
attribution

object (Attribution)

Wymagana atrybucja, która ma się wyświetlać z miejscem.

Pole zbiorcze _location.

Pole _location może mieć tylko jedną z tych wartości:
location

object (LatLng)

Pozycja tego miejsca.

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].
Zapis JSON 
{
  "directionsUrl": string,
  "placeUrl": string,
  "writeAReviewUrl": string,
  "reviewsUrl": string,
  "photosUrl": string
}
Pola
directionsUrl

string

Link do wskazówek dojazdu do miejsca. Link zawiera tylko lokalizację docelową i używa domyślnego środka transportu DRIVE.
placeUrl

string

link do tego miejsca,
writeAReviewUrl

string

link do napisania opinii o tym miejscu w Mapach Google.
reviewsUrl

string

Link do opinii o tym miejscu w Mapach Google.
photosUrl

string

Link do zdjęć tego miejsca w Mapach Google.

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.

DetourSummary

Zapis JSON 
{
  "detourDuration": string,
  "localizedDetourDistance": string
}
Pola
detourDuration

string (Duration format)

Dodatkowy czas podróży wymagany do dotarcia do tego miejsca z głównej trasy. Ta wartość nie jest ustawiana, jeśli trasa jest określona przez encoded_polyline.

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

string

Dodatkowa odległość, jaką trzeba pokonać, aby dotrzeć do tego miejsca z głównej trasy, sformatowana do wyświetlenia w języku żądania (np. „1.2 mi” lub „1,9 km”).

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 nanosekundowej rozdzielczości 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 pole seconds. Wartość musi mieścić się w zakresie od -999 999 999 do +999 999 999 włącznie.

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” podmiotó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, a narzędzie do zapamiętywania – nie.

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