Pesquisar no trajeto

A ferramenta search_along_route permite que um LLM encontre lugares ao longo de um trajeto de viagem com base em uma consulta em linguagem natural, como eletropostos no caminho para o Lago Tahoe ou cafeterias entre São Francisco e San Jose. A ferramenta retorna um resumo gerado com IA dos lugares correspondentes e as vantagens e desvantagens do desvio. Para cada lugar citado no resumo, a resposta também inclui o ID de lugar, as coordenadas de latitude/longitude, os links do Google Maps, a atribuição obrigatória e as métricas de desvio.

Cada solicitação de search_along_route é uma opção Pro e é faturada na SKU Maps Grounding Pro.

É possível chamar search_along_route pelo servidor MCP ou como o método REST searchAlongRoute. Nesta página, descrevemos as opções de solicitação, como especificar um trajeto, o que a resposta contém e como as solicitações são faturadas. Para os esquemas completos, consulte a referência do MCP do search_along_route e a referência do REST do searchAlongRoute.

Opções de solicitação

O LLM define essas opções ao chamar a ferramenta, com base na solicitação do usuário e na descrição da ferramenta. É possível influenciar as opções que o modelo usa com suas próprias instruções. Consulte Controlar o uso do Pro.

A tabela a seguir descreve as opções de solicitação para search_along_route:

Opção Descrição
text_query Obrigatório. A consulta de pesquisa com linguagem natural para lugares ao longo do trajeto, por exemplo, ev chargers, coffee ou vegetarian restaurants.
retrieval_token, route_endpoints ou encoded_polyline Obrigatório. O trajeto em que a pesquisa será feita. Especifique um desses três campos em cada solicitação. Consulte Especificar uma rota.
travel_mode Opcional. O meio de transporte usado para calcular o trajeto e os desvios: DRIVE (padrão), WALK ou BICYCLE. WALK e BICYCLE são compatíveis apenas com route_endpoints. TRANSIT não é compatível. As rotas de WALK estão na versão Beta e, às vezes, podem não ter calçadas ou caminhos para pedestres claros. Esse aviso precisa ser mostrado ao usuário em todos os trajetos a pé exibidos no app.
routing_preference Opcional. Como os dados de trânsito são usados para calcular os tempos de rota e desvio: ROUTING_PREFERENCE_TRAFFIC_UNAWARE (padrão) ou ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL. O ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL usa as condições de trânsito em tempo real quando disponíveis e não é compatível com WALK ou BICYCLE.
include_extended_details Opcional. Quando true, o resumo inclui detalhes estendidos do lugar, como insights de avaliações, itens do cardápio, atmosfera, dicas de visitantes, disponibilidade de carregadores de VE ou preços de combustível. O valor padrão é false.
language_code Opcional. O código de idioma BCP-47 para o resumo e a distância do desvio localizada, por exemplo, en-US ou ja. O valor padrão é en-US.
region_code Opcional. O código de região CLDR de duas letras do usuário, por exemplo, US ou CA. Afeta nomes de lugares específicos de uma região e pode afetar os resultados com base na legislação aplicável.

Especificar uma rota

Cada solicitação search_along_route precisa especificar a rota usando um dos três campos mutuamente exclusivos. Definir mais de um campo de rota ou omitir os três retorna um erro INVALID_ARGUMENT.

A tabela a seguir compara as três maneiras de especificar uma rota:

Opção de trajeto Formato de entrada Meios de transporte aceitos Retorna detourDuration Quando usar
retrieval_token A string retrievalToken de uma resposta compute_routes anterior (válida por 10 minutos) DRIVE Sim O agente já chamou compute_routes para um trajeto de carro, incluindo trajetos com paradas intermediárias, e o usuário pede lugares ao longo desse trajeto.
route_endpoints Um objeto com waypoints origin e destination (address, place_id ou lat_lng) DRIVE, WALK, BICYCLE Sim O usuário pede para encontrar lugares entre dois locais em uma única etapa sem chamar compute_routes primeiro, ou o trajeto usa caminhada ou bicicleta.
encoded_polyline Uma string de polilinha codificada que representa um trajeto de carro. DRIVE Não (retorna apenas localizedDetourDistance) Seu aplicativo já tem uma polilinha de trajeto de outra fonte, como a API Routes.

Rede compute_routes e search_along_route

Quando uma solicitação compute_routes usa o modo de transporte DRIVE, cada trajeto na resposta inclui um campo retrievalToken. Esse token é válido por 10 minutos e codifica o trajeto calculado, incluindo as paradas intermediárias. Quando o usuário perguntar sobre lugares ao longo desse trajeto, o LLM poderá transmitir o valor de retrievalToken como retrieval_token em search_along_route.

Detalhes estendidos do lugar

Defina include_extended_details como true quando a solicitação do usuário precisar de insights qualitativos, condições em tempo real ou atributos especializados ao longo do trajeto, como:

  • O que os avaliadores dizem: insights baseados em avaliações, sentimento do cliente e feedback.
  • Ofertas específicas: itens do cardápio, pratos, especialidades, bebidas ou destaques da empresa.
  • Atmosfera: decoração interior, estética, ambiente ou clima.
  • Dicas práticas para visitantes e dados em tempo real: se é preciso reservar com antecedência, tempos de espera, quão movimentado o lugar está, disponibilidade de carregadores de VE, preços de combustível, estacionamento e instalações.

Deixe include_extended_details definido como false (o padrão) para pesquisas padrão ao longo de um trajeto, como encontrar postos de gasolina, paradas de descanso ou cafeterias por local, horário de funcionamento e tempo de desvio. As solicitações com detalhes estendidos levam mais tempo para serem concluídas, mas não adicionam cobranças extras porque cada solicitação de search_along_route já é faturada na SKU Pro.

Exemplos

A solicitação do MCP a seguir pesquisa eletropostos entre San Francisco e Lake Tahoe usando route_endpoints e rotas que consideram o trânsito:

{
  "method": "tools/call",
  "params": {
    "name": "search_along_route",
    "arguments": {
      "text_query": "fast EV chargers with a coffee shop nearby",
      "route_endpoints": {
        "origin": {"address": "San Francisco, CA"},
        "destination": {"address": "Lake Tahoe, CA"}
      },
      "travel_mode": "DRIVE",
      "routing_preference": "ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL",
      "include_extended_details": true
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}

O exemplo a seguir usa um retrieval_token de uma resposta compute_routes anterior:

{
  "method": "tools/call",
  "params": {
    "name": "search_along_route",
    "arguments": {
      "text_query": "coffee shops",
      "retrieval_token": "RETRIEVAL_TOKEN"
    }
  },
  "jsonrpc": "2.0",
  "id": 2
}

Substitua RETRIEVAL_TOKEN pela string retrievalToken retornada por compute_routes.

O exemplo a seguir envia a primeira solicitação para o método REST searchAlongRoute:

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
  "textQuery": "fast EV chargers with a coffee shop nearby",
  "routeEndpoints": {
    "origin": {"address": "San Francisco, CA"},
    "destination": {"address": "Lake Tahoe, CA"}
  },
  "travelMode": "DRIVE",
  "routingPreference": "ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL",
  "includeExtendedDetails": true
}' \
"https://mapstools.googleapis.com/v1:searchAlongRoute"

Substitua API_KEY pela sua chave de API.

Resposta

A resposta contém os seguintes campos:

  • summary: um resumo em linguagem natural dos resultados da pesquisa e das vantagens e desvantagens do desvio. Ele pode conter citações baseadas em zero, como [0], que são mapeadas para entradas em results.
  • results[]: a lista classificada de lugares mencionados no resumo. Cada entrada inclui:
    • place: detalhes sobre o lugar:
      • place: o nome do recurso do lugar, no formato places/{id}.
      • id: o ID de lugar. Você pode usá-lo com outras APIs da Plataforma Google Maps, como para mostrar o lugar em um mapa.
      • location: as coordenadas de latitude/longitude do lugar.
      • googleMapsLinks: links do Google Maps para o lugar (placeUrl), rotas (directionsUrl), avaliações (reviewsUrl), fotos (photosUrl) e para escrever uma avaliação (writeAReviewUrl).
      • attribution: a atribuição que você precisa mostrar com o lugar. Consulte os requisitos de atribuição.
    • detourSummary: o tempo de viagem e a distância adicionais necessários para parar neste lugar ao longo do trajeto:
      • localizedDetourDistance: a distância extra formatada no idioma da solicitação, como "1.2 mi" ou "1.9 km".
      • detourDuration: o tempo de viagem extra como uma string de duração, como "180s". Esse campo não é definido quando a rota é especificada com encoded_polyline.
  • contentToken: um token de visualização de dados de agente (pré-lançamento) que permite mostrar os lugares na resposta com o Kit de Interface do Places sem custo financeiro adicional. Retornado quando a resposta inclui pelo menos um lugar.

Para detalhes completos do campo, consulte a referência de search_along_route.

Faturamento e cotas

Cada solicitação search_along_route é um evento faturável na SKU do Maps Grounding Pro. Definir include_extended_details como true ou routing_preference como ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL não gera cobranças extras. Se o agente chamar compute_routes primeiro e depois transmitir retrieval_token para search_along_route, cada chamada de ferramenta será faturada como uma solicitação separada.

Se você mostrar os lugares de uma resposta search_along_route com o Kit de Interface do Places, poderá usar o token de visualização de dados agêntica (pré-lançamento) para que essas solicitações do Kit de Interface do Places não sejam faturadas.

A cota de search_along_route é de 300 consultas por minuto para cada projeto. Para preços, consulte a tabela de preços principal e a tabela de preços da Índia.