Buscar en la ruta

La herramienta search_along_route permite que un LLM encuentre lugares a lo largo de una ruta de viaje a partir de una consulta en lenguaje natural, como estaciones de carga de VE en el camino al lago Tahoe o cafeterías entre San Francisco y San José. La herramienta devuelve un resumen generado por IA de los lugares que coinciden y las compensaciones de desvío. Para cada lugar citado en el resumen, la respuesta también incluye el ID de lugar, las coordenadas de latitud y longitud, los vínculos de Google Maps, la atribución obligatoria y las métricas de desvío.

Cada solicitud de search_along_route es una opción Pro y se factura con el SKU de Maps Grounding Pro.

Puedes llamar a search_along_route a través del servidor de MCP o como el método REST searchAlongRoute. En esta página, se describen las opciones de solicitud, cómo especificar una ruta, qué contiene la respuesta y cómo se facturan las solicitudes. Para obtener los esquemas completos, consulta la referencia de MCP de search_along_route y la referencia de REST de searchAlongRoute.

Opciones de solicitud

El LLM establece estas opciones cuando llama a la herramienta, según la solicitud del usuario y la descripción de la herramienta. Puedes influir en las opciones que usa el modelo con tus propias instrucciones. Consulta Controla el uso de Pro.

En la siguiente tabla, se describen las opciones de solicitud para search_along_route:

Opción Descripción
text_query Obligatorio. Es la búsqueda en lenguaje natural de lugares a lo largo de la ruta, por ejemplo, ev chargers, coffee o vegetarian restaurants.
retrieval_token, route_endpoints o encoded_polyline Obligatorio. Es la ruta a lo largo de la cual se realizará la búsqueda. Especifica uno de estos tres campos en cada solicitud. Consulta Especifica una ruta.
travel_mode Opcional. Es el medio de transporte que se usa para calcular la ruta y los desvíos: DRIVE (predeterminado), WALK o BICYCLE. WALK y BICYCLE solo se admiten con route_endpoints. No se admite TRANSIT. Las rutas de WALK están en versión beta y, a veces, es posible que no incluyan aceras o rutas peatonales claras. Debes mostrar esta advertencia al usuario para todas las rutas a pie que muestres en tu app.
routing_preference Opcional. Cómo se usan los datos de tráfico para calcular la ruta y los tiempos de desvío: ROUTING_PREFERENCE_TRAFFIC_UNAWARE (predeterminado) o ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL. ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL usa las condiciones de tráfico en tiempo real cuando están disponibles y no es compatible con WALK ni BICYCLE.
include_extended_details Opcional. Cuando es true, el resumen incluye detalles extendidos del lugar, como información de opiniones, elementos del menú, ambiente, sugerencias de visitantes, disponibilidad de cargadores de VE o precios de la gasolina. La configuración predeterminada es false.
language_code Opcional. Es el código de idioma BCP-47 para el resumen y la distancia de desvío localizada, por ejemplo, en-US o ja. La configuración predeterminada es en-US.
region_code Opcional. Es el código de región CLDR de dos letras del usuario, por ejemplo, US o CA. Afecta los nombres de lugares específicos de la región y puede afectar los resultados según la ley aplicable.

Especifica una ruta

Cada solicitud search_along_route debe especificar la ruta con uno de los tres campos mutuamente excluyentes. Si configuras más de un campo de ruta o si omites los tres, se muestra un error INVALID_ARGUMENT.

En la siguiente tabla, se comparan las tres formas de especificar una ruta:

Opción de ruta Formato de entrada Medios de transporte admitidos Se muestra detourDuration Cuándo se utiliza
retrieval_token La cadena retrievalToken de una respuesta compute_routes anterior (válida durante 10 minutos) DRIVE Sí El agente ya llamó a compute_routes para obtener una ruta de conducción, incluidas las rutas con paradas intermedias, y el usuario solicita lugares a lo largo de esa ruta.
route_endpoints Un objeto con puntos de referencia origin y destination (address, place_id o lat_lng) DRIVE, WALK, BICYCLE Sí El usuario solicita encontrar lugares entre dos ubicaciones en un solo paso sin llamar primero a compute_routes, o la ruta usa las opciones para caminar o andar en bicicleta.
encoded_polyline Una cadena de polilínea codificada que representa una ruta en automóvil DRIVE No (solo devuelve localizedDetourDistance) Tu aplicación ya tiene una polilínea de ruta de otra fuente, como la API de Routes.

Cadena compute_routes y search_along_route

Cuando una solicitud compute_routes usa el medio de transporte DRIVE, cada ruta de la respuesta incluye un campo retrievalToken. Este token es válido durante 10 minutos y codifica la ruta calculada, incluidas las paradas intermedias. Cuando el usuario continúa con la conversación y pregunta por lugares a lo largo de esa ruta, el LLM puede pasar el valor de retrievalToken como retrieval_token en search_along_route.

Detalles extendidos del lugar

Establece include_extended_details en true cuando la solicitud del usuario necesite información cualitativa, condiciones en tiempo real o atributos especializados a lo largo de la ruta, como los siguientes:

  • Qué dicen los usuarios: estadísticas basadas en opiniones, opiniones de los clientes y comentarios.
  • Ofertas específicas: elementos del menú, platos, especialidades de comida, bebidas o aspectos destacados de la empresa.
  • Atmósfera: decoración interior, estética, ambiente o estado de ánimo
  • Sugerencias prácticas para los visitantes y datos en tiempo real: si se debe reservar con anticipación, tiempos de espera, qué tan concurrido está el lugar, disponibilidad de cargadores de VE, precios de la gasolina, estacionamiento e instalaciones.

Deja include_extended_details configurado como false (el valor predeterminado) para las búsquedas estándar a lo largo de una ruta, como encontrar gasolineras, paradas de descanso o cafeterías por ubicación, horario de atención y tiempo de desvío. Las solicitudes con detalles extendidos tardan más en completarse, pero no agregan cargos adicionales porque cada solicitud de search_along_route ya se factura con el SKU Pro.

Ejemplos

La siguiente solicitud de MCP busca estaciones de carga de VE entre San Francisco y Lake Tahoe con route_endpoints y enrutamiento con reconocimiento del tráfico:

{
  "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
}

En el siguiente ejemplo, se usa un retrieval_token de una respuesta 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
}

Reemplaza RETRIEVAL_TOKEN por la cadena retrievalToken que devuelve compute_routes.

En el siguiente ejemplo, se envía la primera solicitud al 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"

Reemplaza API_KEY por tu clave de API.

Respuesta

La respuesta contiene los siguientes campos:

  • summary: Es un resumen en lenguaje natural de los resultados de la búsqueda y las compensaciones de los desvíos. Puede contener citas basadas en cero, como [0], que se asignan a entradas en results.
  • results[]: Es la lista clasificada de lugares que se mencionan en el resumen. Cada entrada incluye lo siguiente:
    • place: Detalles sobre el lugar:
      • place: Es el nombre del recurso del lugar, en el formato places/{id}.
      • id: Es el ID de lugar. Puedes usarlo con otras APIs de Google Maps Platform, por ejemplo, para mostrar el lugar en un mapa.
      • location: Son las coordenadas de latitud y longitud del lugar.
      • googleMapsLinks: Son vínculos de Google Maps para el lugar (placeUrl), instrucciones sobre cómo llegar (directionsUrl), opiniones (reviewsUrl), fotos (photosUrl) y la opción para escribir una opinión (writeAReviewUrl).
      • attribution: Es la atribución que debes mostrar con el lugar. Consulta los requisitos de atribución.
    • detourSummary: Es la duración del viaje y la distancia adicionales que se requieren para detenerse en este lugar de la ruta:
      • localizedDetourDistance: Es la distancia adicional con el formato del idioma de la solicitud, como "1.2 mi" o "1.9 km".
      • detourDuration: Es la duración del viaje adicional como una cadena de duración, como "180s". Este campo no se establece cuando la ruta se especifica con encoded_polyline.
  • contentToken: Es un token de visualización de datos de agentes (versión preliminar) que te permite mostrar los lugares de la respuesta con el kit de IU de Places sin costo adicional. Se devuelve cuando la respuesta incluye al menos un lugar.

Para obtener detalles completos de los campos, consulta la referencia de search_along_route.

Facturación y cuotas

Cada solicitud de search_along_route es un evento facturable según el SKU de Maps Grounding Pro. Establecer include_extended_details en true o routing_preference en ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL no agrega cargos adicionales. Si tu agente llama primero a compute_routes y, luego, pasa retrieval_token a search_along_route, cada llamada a la herramienta se factura como una solicitud independiente.

Si muestras los lugares de una respuesta de search_along_route con el kit de IU de Places, puedes usar el token de visualización de datos de agentes (versión preliminar) para que no se facturen esas solicitudes del kit de IU de Places.

La cuota de search_along_route es de 300 consultas por minuto para cada proyecto. Para conocer los precios, consulta la tabla de precios principal y la tabla de precios de India.