MCP Tools Reference: mapstools.googleapis.com

Ferramenta: search_along_route

Chame essa ferramenta quando o usuário quiser encontrar lugares, empresas ou pontos de interesse ao longo de um trajeto de viagem (por exemplo, "postos de gasolina no meu caminho para Tahoe", "cafeterias entre SF e San Jose"). Chamar essa ferramenta gera um custo maior do que search_places. Portanto, use search_places ao pesquisar perto de um único local, em vez de ao longo de um trajeto.

Requisitos de entrada (CRÍTICOS):

1. text_query (string - OBRIGATÓRIO): uma descrição em linguagem natural do que pesquisar ao longo do trajeto.

   • Exemplos: 'ev chargers', 'coffee', 'vegetarian restaurants', 'rest stops'.

2. Especificação de rota (OBRIGATÓRIO: forneça exatamente UMA das seguintes opções):

   • retrieval_token (string): o retrieval_token retornado por uma chamada compute_routes anterior para um trajeto DRIVE. Prefira essa opção sempre que o trajeto já tiver sido calculado. O token é válido por 10 minutos.
   • route_endpoints (objeto): o origin e o destination da rota. Cada um precisa ser fornecido usando address, lat_lng ou place_id.
     • Exemplo: {"route_endpoints": {"origin": {"address": "San Francisco, CA"}, "destination": {"address": "Lake Tahoe, CA"}}}.
   • encoded_polyline (string): uma polilinha codificada que representa um trajeto DRIVE.

3. travel_mode (tipo enumerado - OPCIONAL): DRIVE (padrão), WALK ou BICYCLE. WALK e BICYCLE só são compatíveis com route_endpoints. TRANSIT não é compatível.

4. routing_preference (tipo enumerado - OPCIONAL):

   • ROUTING_PREFERENCE_TRAFFIC_UNAWARE (padrão): calcula o trajeto e os desvios sem trânsito em tempo real. Latência mais baixa.
   • ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL: usa as condições de trânsito em tempo real quando disponíveis. Não há suporte para WALK ou BICYCLE. Defina isso APENAS quando o usuário perguntar sobre trânsito, congestionamento ou tempos de desvio ajustados ao trânsito. A latência é maior.

5. include_extended_details (booleano - OPCIONAL): defina como true somente quando a solicitação exigir insights de avaliações qualitativas, itens de menu ou ofertas específicas, atmosfera, dicas ou movimentação de visitantes, disponibilidade de carregador de VE, preços de combustível ou outros detalhes qualitativos avançados. O padrão é false. Ativar essa opção pode aumentar a latência.

6. language_code (string - OPCIONAL): o idioma do resumo dos resultados e dos Place Details, por exemplo, en, ja, en-US. O valor padrão é en-US.

7. region_code (string - OPCIONAL): o código regional CLDR Unicode do usuário, por exemplo, US, CA.

Instruções para chamada de ferramenta:

• Cada resultado inclui um detour_summary (quando disponível) que descreve a distância extra (localized_detour_distance) e, a menos que o trajeto tenha sido fornecido como encoded_polyline, o tempo extra (detour_duration) incorrido ao parar nesse local. Use-a para comparar opções.
• A resposta summary pode conter citações baseadas em zero (por exemplo, "[0]") que fazem referência a entradas em results.
• A saída embasada precisa ser atribuída à fonte usando o campo attribution de cada results[].place, quando disponível.

O exemplo de código a seguir mostra como usar curl para chamar a ferramenta MCP search_along_route.

Solicitação 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 }'

Esquema de entrada

Mensagem de solicitação para SearchAlongRoute.

SearchAlongRouteRequest

Representação 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. }

Campos
textQuery	string Obrigatório. Consulta de pesquisa com linguagem natural (por exemplo, "carregadores de VE", "café").
languageCode	string Opcional. O idioma do resumo e dos Place Details. O padrão é "en-US".
regionCode	string Opcional. Código do país/região (CLDR) do local (por exemplo, "US").
routingPreference	enum (RoutingPreference) Opcional. Preferência de roteamento opcional que especifica como os dados de trânsito são usados. O padrão é TRAFFIC_UNAWARE.
includeExtendedDetails	boolean Opcional. Inclui detalhes estendidos do lugar na resposta. Defina esse campo como true quando a solicitação do usuário exigir insights qualitativos detalhados, dinâmicas em tempo real ou atributos de entidade especializados: - Avaliações qualitativas, sentimento do cliente e feedback. - Ofertas específicas, como itens do cardápio, pratos, especialidades, bebidas ou destaques da empresa. - Atmosfera qualitativa, decoração de interiores, estética, ambiente ou clima. - Dados em tempo real e especificações de instalações especializadas, políticas/dicas para visitantes, tempos de espera. Deixe false (padrão) para pesquisas de descoberta padrão (por exemplo, culinárias, tipos de loja), pesquisas de local/endereço, dados de contato, horário de funcionamento e metadados/comodidades padrão. Ativar esse campo pode aumentar a latência.
travelMode	enum (RouteTravelMode) Opcional. Especifica o meio de transporte usado para calcular o trajeto e os desvios. O valor padrão é DRIVE. WALK e BICYCLE só são compatíveis com route_endpoints. TRANSIT não é compatível.
Campo de união route_spec. Especificação do trajeto: um trajeto atual, um token de trajeto ou endpoints de origem/destino. route_spec pode ser apenas de um dos tipos a seguir:
encodedPolyline	string Uma string de polilinha codificada que representa o trajeto. Consulte https://developers.google.com/maps/documentation/utilities/polylinealgorithm
retrievalToken	string Um token de recuperação retornado de uma chamada ComputeRoutes anterior que representa o trajeto.
routeEndpoints	object (RouteEndpoints) Endpoints de rota explícitos (origem e destino).

RouteEndpoints

Representação JSON
{ "origin": { object (Waypoint) }, "destination": { object (Waypoint) } }

Campos
origin	object (Waypoint) Obrigatório. Ponto de partida (endereço, ID de lugar ou coordenadas geográficas).
destination	object (Waypoint) Obrigatório. Ponto de destino (endereço, ID de lugar ou coordenadas geográficas).

Ponto de referência

Representação 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. }

Campos
Campo de união location_type. Diferentes maneiras de representar um local. location_type pode ser apenas de um dos tipos a seguir:
latLng	object (LatLng) Um ponto especificado usando coordenadas geográficas.
placeId	string O ID de lugar associado ao waypoint.
address	string Endereço legível por humanos ou um Plus Code. Para mais detalhes, consulte https://plus.codes.

LatLng

Representação JSON
{ "latitude": number, "longitude": number }

Campos
latitude	number A latitude em graus. Precisa estar no intervalo [-90,0, +90,0].
longitude	number A longitude em graus. Precisa estar no intervalo [-180,0, +180,0].

RoutingPreference

Um conjunto de valores que especificam fatores a serem considerados ao calcular o trajeto.

Tipos enumerados
ROUTING_PREFERENCE_UNSPECIFIED	Nenhuma preferência de roteamento especificada. O valor padrão é ROUTING_PREFERENCE_TRAFFIC_UNAWARE.
ROUTING_PREFERENCE_TRAFFIC_UNAWARE	Calcula rotas sem considerar as condições de trânsito em tempo real. Adequado quando as condições de trânsito não importam ou não são relevantes. O uso desse valor produz a menor latência.
ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL	Calcula rotas considerando as condições de trânsito em tempo real, quando os dados de trânsito estão disponíveis. Para TRANSIT, usa dados de transporte público em tempo real, como atrasos e cancelamentos, quando disponíveis. Esse valor vai acionar o nível Pro e gerar um custo faturado e uma latência maiores.

RouteTravelMode

Um conjunto de valores usado para especificar o meio de transporte.

Tipos enumerados
ROUTE_TRAVEL_MODE_UNSPECIFIED	Nenhum meio de transporte especificado. O valor padrão é DRIVE.
DRIVE	Viajar de carro de passeio.
WALK	Viaje a pé. OBSERVAÇÃO: as rotas de WALK estão na versão Beta e, às vezes, podem não ter calçadas ou caminhos para pedestres claros. Você precisa mostrar esse aviso ao usuário em todas as caminhadas exibidas no seu app.
BICYCLE	Viajar de bicicleta.
TRANSIT	Viajar usando o transporte público.

Esquema de saída

Mensagem de resposta para SearchAlongRoute.

SearchAlongRouteResponse

Representação JSON
{ "results": [ { object (Result) } ], "summary": string, "contentToken": string }

Campos
results[]	object (Result) Apenas saída. A lista classificada de resultados da pesquisa encontrados ao longo do trajeto.
summary	string Apenas saída. Resumo em linguagem natural dos resultados da pesquisa e das vantagens e desvantagens dos desvios. Pode conter citações baseadas em zero (por exemplo, "[0]", "[1]") que fazem referência às entradas correspondentes na lista results.
contentToken	string Apenas saída. Um token criptografado que encapsula o contexto da pesquisa e pode ser transmitido para serviços de renderização visual do Google Maps, SDKs ou o Maps Agentic UI Toolkit (A2UI) para mostrar componentes interativos da interface para os resultados da pesquisa retornados.

Resultado

Representação JSON
{ "place": { object (PlaceView) }, "detourSummary": { object (DetourSummary) } }

Campos
place	object (PlaceView) Apenas saída. Detalhes sobre o lugar encontrado ao longo do trajeto.
detourSummary	object (DetourSummary) Apenas saída. Métricas de desvio geradas ao adicionar esse lugar como uma parada intermediária no trajeto. Omitido ou vazio se não for possível calcular as métricas de desvio.

PlaceView

Representação 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. }

Campos
place	string O nome do recurso do lugar, no formato "places/{id}".
id	string O ID de lugar do lugar subjacente.
googleMapsLinks	object (GoogleMapsLinks) Links para acionar diferentes ações do Google Maps.
attribution	object (Attribution) Atribuição obrigatória para mostrar com o lugar.
Campo de união _location. _location pode ser apenas de um dos tipos a seguir:
location	object (LatLng) A posição desse lugar.

LatLng

Representação JSON
{ "latitude": number, "longitude": number }

Campos
latitude	number A latitude em graus. Precisa estar no intervalo [-90,0, +90,0].
longitude	number A longitude em graus. Precisa estar no intervalo [-180,0, +180,0].

GoogleMapsLinks

Representação JSON
{ "directionsUrl": string, "placeUrl": string, "writeAReviewUrl": string, "reviewsUrl": string, "photosUrl": string }

Campos
directionsUrl	string Um link para mostrar as rotas até o lugar. O link preenche apenas o local de destino e usa o modo de viagem padrão DRIVE.
placeUrl	string Um link para mostrar esse lugar.
writeAReviewUrl	string Um link para escrever uma avaliação sobre esse lugar no Google Maps.
reviewsUrl	string Um link para mostrar as avaliações desse lugar no Google Maps.
photosUrl	string Um link para mostrar fotos desse lugar no Google Maps.

Atribuição

Representação JSON
{ "title": string, "url": string }

Campos
title	string O título a ser exibido para a atribuição.
url	string O URL para vincular à atribuição.

DetourSummary

Representação JSON
{ "detourDuration": string, "localizedDetourDistance": string }

Campos
detourDuration	string (Duration format) O tempo de viagem adicional necessário para desviar para esse lugar do trajeto principal. Esse valor não será definido se a rota for especificada por encoded_polyline. Duração em segundos com até nove dígitos fracionários, terminando em "s". Exemplo: "3.5s".
localizedDetourDistance	string A distância adicional necessária para desviar para esse lugar do trajeto principal, formatada para exibição no idioma da solicitação (por exemplo, "1,2 mi" ou "1,9 km").

Duração

Representação JSON
{ "seconds": string, "nanos": integer }

Campos
seconds	string (int64 format) Segundos assinados do período. Precisa ser de -315.576.000.000 a +315.576.000.000, inclusive. Observação: esses limites são calculados da seguinte forma: 60 s/min * 60 min/h * 24 h/dia * 365,25 dias/ano * 10.000 anos
nanos	integer Frações assinadas de um segundo com resolução de nanossegundos do período. As durações menores que um segundo são representadas com um campo seconds de 0 e um campo nanos positivo ou negativo. Para durações de um segundo ou mais, um valor diferente de zero para o campo nanos precisa ter o mesmo sinal que o campo seconds. O valor precisa ser de -999.999.999 a +999.999.999.

Anotações de ferramentas

As anotações de ferramentas são enviadas aos clientes do MCP para descrever o risco básico de uma determinada ferramenta. A maioria dos clientes trata essas dicas como não confiáveis, mas elas podem ser usadas para decidir quando uma solicitação de confirmação pode ser enviada a um usuário.

Além da string de título, as seguintes dicas booleanas são definidas:

• readOnlyHint: se for verdadeiro, a ferramenta não vai modificar o ambiente. (Padrão: falso).
• destructiveHint: se for verdadeiro, a ferramenta poderá realizar ações destrutivas. Se for falso, a ferramenta só poderá realizar ações aditivas. Padrão: verdadeiro.
• idempotentHint: se for verdadeiro, chamar a ferramenta repetidamente com os mesmos argumentos não terá efeito adicional no ambiente. (Padrão: falso).
• openWorldHint: se for verdadeiro, a ferramenta poderá interagir com um "mundo aberto" de entidades externas. Se for falso, a ferramenta só poderá interagir com entidades internas. Por exemplo, uma ferramenta de pesquisa na Web seria de mundo aberto, enquanto uma ferramenta de memória não seria.

Dica destrutiva: ❌ | Dica idempotente: ❌ | Dica somente leitura: ✅ | Dica de jogos de mundo aberto: ❌