MCP Tools Reference: mapstools.googleapis.com

Herramienta: search_along_route

Llama a esta herramienta cuando el usuario quiera encontrar lugares, empresas o puntos de interés a lo largo de una ruta de viaje (p.ej., "estaciones de servicio en mi camino a Tahoe", "cafeterías entre SF y San José"). Llamar a esta herramienta genera un costo más alto que search_places, por lo que debes usar search_places cuando busques cerca de una sola ubicación en lugar de a lo largo de una ruta.

Requisitos de entrada (CRÍTICOS):

  1. text_query (cadena, OBLIGATORIO): Es una descripción en lenguaje natural de lo que se debe buscar en la ruta.

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

  2. Especificación de la ruta (OBLIGATORIO: Proporciona exactamente UNO de los siguientes elementos):

    • retrieval_token (cadena): Es el retrieval_token que devuelve una llamada anterior a compute_routes para una ruta DRIVE. Prefiere esta opción cuando ya se haya calculado la ruta. El token es válido durante 10 minutos.
    • route_endpoints (objeto): Es el origin y la destination de la ruta. Cada uno se debe proporcionar con address, lat_lng o place_id.
      • Ejemplo: {"route_endpoints": {"origin": {"address": "San Francisco, CA"}, "destination": {"address": "Lake Tahoe, CA"}}}.
    • encoded_polyline (cadena): Es una polilínea codificada que representa una ruta de DRIVE.

  3. travel_mode (enum, OPCIONAL): DRIVE (predeterminado), WALK o BICYCLE. WALK y BICYCLE solo son compatibles con route_endpoints. No se admite TRANSIT.

  4. routing_preference (enum - OPCIONAL):

    • ROUTING_PREFERENCE_TRAFFIC_UNAWARE (predeterminado): Calcula la ruta y los desvíos sin tráfico en tiempo real. Latencia más baja.
    • ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL: Usa las condiciones de tráfico en tiempo real cuando están disponibles. No se admite para WALK ni BICYCLE. Establece este valor SOLO cuando el usuario pregunte sobre el tráfico, la congestión o los tiempos de desvío ajustados según el tráfico. Genera una latencia más alta.

  5. include_extended_details (booleano, OPCIONAL): Se establece en true solo cuando la solicitud requiere estadísticas de opiniones cualitativas, elementos o productos específicos del menú, ambiente, sugerencias o nivel de actividad de los visitantes, disponibilidad de cargadores de VE, precios de la gasolina o cualquier otro detalle cualitativo enriquecido. La configuración predeterminada es false. Si la habilitas, es posible que aumente la latencia.

  6. language_code (cadena, OPCIONAL): Es el idioma del resumen de los resultados y los detalles del lugar, p.ej., en, ja, en-US. La configuración predeterminada es en-US.

  7. region_code (cadena, OPCIONAL): Es el código de región CLDR de Unicode del usuario, p.ej., US, CA.

Instrucciones para la llamada a la herramienta:

  • Cada resultado incluye un objeto detour_summary (cuando está disponible) que describe la distancia adicional (localized_detour_distance) y, a menos que la ruta se haya proporcionado como encoded_polyline, el tiempo adicional (detour_duration) que se genera por detenerse en ese lugar. Úsala para comparar opciones.
  • La respuesta summary puede contener citas basadas en cero (p.ej., "[0]") que hagan referencia a entradas en results.
  • El resultado fundamentado se debe atribuir a la fuente con el campo attribution de cada results[].place cuando esté disponible.

En la siguiente muestra de código, se indica cómo usar curl para llamar a la herramienta de MCP search_along_route.

Solicitud de 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

Es el mensaje de solicitud para SearchAlongRoute.

SearchAlongRouteRequest

Representación 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

Obligatorio. Es la búsqueda en lenguaje natural (p.ej., "cargadores de VE", "café").
languageCode

string

Opcional. Es el idioma del resumen y los detalles del lugar. La configuración predeterminada es "en-US".
regionCode

string

Opcional. Es el código de país o región (CLDR) de la ubicación (p.ej., "US").
routingPreference

enum (RoutingPreference)

Opcional. Es la preferencia de ruta opcional que especifica cómo se usan los datos de tráfico. La configuración predeterminada es TRAFFIC_UNAWARE.
includeExtendedDetails

boolean

Opcional. Incluye detalles extendidos del lugar en la respuesta.

Establece este campo en true cuando la solicitud del usuario requiera estadísticas cualitativas enriquecidas, dinámicas en tiempo real o atributos de entidad especializados: - Opiniones cualitativas, opiniones de los clientes y comentarios. - Ofertas específicas, como 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 cualitativos. - Datos en tiempo real y especificaciones de instalaciones especializadas, políticas/sugerencias para visitantes, tiempos de espera.

Deja false (predeterminado) para las búsquedas de descubrimiento estándar (p.ej., tipos de cocina, tipos de tienda), las búsquedas de ubicación o dirección, la información de contacto, el horario de atención y los metadatos o las comodidades estándar.

Si habilitas este campo, es posible que se genere una latencia más alta.
travelMode

enum (RouteTravelMode)

Opcional. Especifica el medio de transporte que se usa para calcular la ruta y los desvíos. La configuración predeterminada es DRIVE. WALK y BICYCLE solo son compatibles con route_endpoints. No se admite TRANSIT.
Campo de unión route_spec. Especificación de la ruta: una ruta existente, un token de ruta o endpoints de origen y destino. route_spec puede ser solo uno de los parámetros siguientes:
encodedPolyline

string

Es una cadena de polilínea codificada que representa la ruta. Consulta https://developers.google.com/maps/documentation/utilities/polylinealgorithm
retrievalToken

string

Es un token de recuperación que se devuelve de una llamada anterior a ComputeRoutes y que representa la ruta.
routeEndpoints

object (RouteEndpoints)

Extremos de ruta explícitos (origen y destino)

RouteEndpoints

Representación JSON 
{
  "origin": {
    object (Waypoint)
  },
  "destination": {
    object (Waypoint)
  }
}
Campos
origin

object (Waypoint)

Obligatorio. Punto de partida (dirección, ID de lugar o coordenadas geográficas)
destination

object (Waypoint)

Obligatorio. Punto de destino (dirección, ID de lugar o coordenadas geográficas)

Punto de referencia

Representación 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ón location_type. Diferentes formas de representar una ubicación location_type puede ser solo uno de los parámetros siguientes:
latLng

object (LatLng)

Es un punto especificado con coordenadas geográficas.
placeId

string

Es el ID de lugar asociado con el punto de referencia.
address

string

Es la dirección legible por humanos o un Plus Code. Visita https://plus.codes para obtener más información.

LatLng

Representación JSON 
{
  "latitude": number,
  "longitude": number
}
Campos
latitude

number

La latitud expresada en grados. Debe pertenecer al rango [-90.0, +90.0].
longitude

number

La longitud expresada en grados. Debe pertenecer al rango [-180.0, +180.0].

RoutingPreference

Es un conjunto de valores que especifican los factores que se deben tener en cuenta cuando se calcula la ruta.

Enums
ROUTING_PREFERENCE_UNSPECIFIED No se especificó ninguna preferencia de enrutamiento. La configuración predeterminada es ROUTING_PREFERENCE_TRAFFIC_UNAWARE.
ROUTING_PREFERENCE_TRAFFIC_UNAWARE Calcula las rutas sin tener en cuenta las condiciones de tráfico en tiempo real. Es adecuado cuando las condiciones de tráfico no importan o no se aplican. El uso de este valor produce la latencia más baja.
ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL

Calcula rutas teniendo en cuenta las condiciones de tráfico en tiempo real, cuando hay datos de tráfico disponibles. En el caso de TRANSIT, usa datos de transporte público en tiempo real, como retrasos y cancelaciones, cuando estén disponibles.

Este valor activará el nivel Pro y generará un costo facturado y una latencia más altos.

RouteTravelMode

Es un conjunto de valores que se usan para especificar el medio de transporte.

Enums
ROUTE_TRAVEL_MODE_UNSPECIFIED No se especificó ningún medio de transporte. La configuración predeterminada es DRIVE.
DRIVE Viaje en vehículo de pasajeros
WALK Viaja caminando. NOTA: 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.
BICYCLE Viajar en bicicleta
TRANSIT Viajar en transporte público

Esquema de salida

Mensaje de respuesta para SearchAlongRoute.

SearchAlongRouteResponse

Representación JSON 
{
  "results": [
    {
      object (Result)
    }
  ],
  "summary": string,
  "contentToken": string
}
Campos
results[]

object (Result)

Solo salida. Es la lista clasificada de los resultados de la búsqueda que se encontraron a lo largo de la ruta.
summary

string

Solo salida. Resumen en lenguaje natural de los resultados de la búsqueda y las compensaciones de los desvíos Puede contener citas basadas en cero (p.ej., "[0]", "[1]") que hagan referencia a las entradas correspondientes en la lista results.
contentToken

string

Solo salida. Es un token encriptado que encapsula el contexto de la búsqueda y se puede pasar a los servicios de renderización visual de Google Maps, los SDKs o el Maps Agentic UI Toolkit (A2UI) para mostrar componentes interactivos de la IU para los resultados de la búsqueda devueltos.

Resultado

Representación JSON 
{
  "place": {
    object (PlaceView)
  },
  "detourSummary": {
    object (DetourSummary)
  }
}
Campos
place

object (PlaceView)

Solo salida. Son los detalles sobre el lugar que se encontró en la ruta.
detourSummary

object (DetourSummary)

Solo salida. Son las métricas de desvío que se generan cuando se agrega este lugar como una parada intermedia en la ruta. Se omite o se deja vacío si no se pudieron calcular las métricas de desvío.

PlaceView

Representación 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

Es el nombre del recurso del lugar subyacente, con el formato "places/{id}".
id

string

Es el ID de lugar del lugar subyacente.
googleMapsLinks

object (GoogleMapsLinks)

Vínculos para activar diferentes acciones de Google Maps
attribution

object (Attribution)

Es la atribución obligatoria que se debe mostrar con el lugar.

Campo de unión _location.

_location puede ser una de las siguientes opciones:
location

object (LatLng)

Es la posición de este lugar.

LatLng

Representación JSON 
{
  "latitude": number,
  "longitude": number
}
Campos
latitude

number

La latitud expresada en grados. Debe pertenecer al rango [-90.0, +90.0].
longitude

number

La longitud expresada en grados. Debe pertenecer al rango [-180.0, +180.0].
Representación JSON 
{
  "directionsUrl": string,
  "placeUrl": string,
  "writeAReviewUrl": string,
  "reviewsUrl": string,
  "photosUrl": string
}
Campos
directionsUrl

string

Un vínculo para mostrar las instrucciones sobre cómo llegar al lugar El vínculo solo propaga la ubicación de destino y usa el modo de viaje predeterminado DRIVE.
placeUrl

string

Un vínculo para mostrar este lugar.
writeAReviewUrl

string

Un vínculo para escribir una opinión sobre este lugar en Google Maps.
reviewsUrl

string

Es un vínculo para mostrar las opiniones sobre este lugar en Google Maps.
photosUrl

string

Un vínculo para mostrar fotos de este lugar en Google Maps

Atribución

Representación JSON 
{
  "title": string,
  "url": string
}
Campos
title

string

Es el título que se mostrará para la atribución.
url

string

Es la URL a la que se vinculará la atribución.

DetourSummary

Representación JSON 
{
  "detourDuration": string,
  "localizedDetourDistance": string
}
Campos
detourDuration

string (Duration format)

Es el tiempo de viaje adicional que se requiere para desviarse a este lugar desde la ruta principal. Este valor no se establece si la ruta se especifica con encoded_polyline.

Una duración en segundos con hasta nueve dígitos decimales, que terminan en “s”. Ejemplo: "3.5s".
localizedDetourDistance

string

Es la distancia adicional necesaria para desviarse a este lugar desde la ruta principal, con el formato para mostrarse en el idioma de la solicitud (p. ej., "1.2 mi" o "1.9 km").

Duración

Representación JSON 
{
  "seconds": string,
  "nanos": integer
}
Campos
seconds

string (int64 format)

Son los segundos firmados del intervalo de tiempo. Debe ser un valor entre -315,576,000,000 y +315,576,000,000 inclusive. Nota: Estos límites se calculan de la siguiente manera: 60 s/min * 60 min/h * 24 h/día * 365.25 días/año * 10,000 años
nanos

integer

Fracciones con signo de un segundo con una resolución de nanosegundos del intervalo de tiempo. Las duraciones de menos de un segundo se representan con un campo seconds de 0 y un campo nanos positivo o negativo. En el caso de las duraciones de un segundo o más, un valor distinto de cero para el campo nanos debe tener el mismo signo que el campo seconds. Deben ser valores de -999,999,999 a +999,999,999 inclusive.

Anotaciones de herramientas

Las anotaciones de herramientas se envían a los clientes de MCP para describir el riesgo básico de una herramienta determinada. La mayoría de los clientes tratan estas sugerencias como no confiables, pero se pueden usar para decidir cuándo se puede enviar un mensaje de confirmación a un usuario.

Junto con la cadena de título, las siguientes sugerencias booleanas se definen de la siguiente manera:

  • readOnlyHint: Si es verdadero, la herramienta no modifica su entorno. Valor predeterminado: false.
  • destructiveHint: Si es verdadero, la herramienta puede realizar acciones destructivas. Si es falso, la herramienta solo puede realizar acciones aditivas. Valor predeterminado: true.
  • idempotentHint: Si es verdadero, llamar a la herramienta de forma repetida con los mismos argumentos no tendrá ningún efecto adicional en su entorno. Valor predeterminado: false.
  • openWorldHint: Si es verdadero, la herramienta puede interactuar con un "mundo abierto" de entidades externas. Si es falso, la herramienta solo puede interactuar con entidades internas. Por ejemplo, una herramienta de búsqueda web sería de mundo abierto, mientras que una herramienta de memoria no lo sería.

Sugerencia destructiva: ❌ | Sugerencia idempotente: ❌ | Sugerencia de solo lectura: ✅ | Sugerencia de mundo abierto: ❌