MCP Tools Reference: mapstools.googleapis.com

Outil : search_along_route

Appelez cet outil lorsque l'utilisateur souhaite trouver des lieux, des établissements ou des points d'intérêt sur un itinéraire (par exemple, "stations-service sur mon trajet vers Tahoe", "cafés entre SF et San Jose"). L'appel de cet outil entraîne un coût plus élevé que search_places. Utilisez donc plutôt search_places lorsque vous effectuez une recherche à proximité d'un seul lieu plutôt que le long d'un itinéraire.

Exigences d'entrée (CRITIQUE) :

  1. text_query (chaîne, OBLIGATOIRE) : description en langage naturel de ce qu'il faut rechercher le long de l'itinéraire.

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

  2. Spécification de l'itinéraire (OBLIGATOIRE : fournissez exactement UNE des options suivantes) :

    • retrieval_token (chaîne) : retrieval_token renvoyé par un appel compute_routes précédent pour une route DRIVE. Privilégiez cette option lorsque l'itinéraire a déjà été calculé. Le jeton est valide pendant 10 minutes.
    • route_endpoints (objet) : origin et destination de l'itinéraire. Chacun doit être fourni à l'aide de address, lat_lng ou place_id.
      • Exemple : {"route_endpoints": {"origin": {"address": "San Francisco, CA"}, "destination": {"address": "Lake Tahoe, CA"}}}
    • encoded_polyline (chaîne) : polyligne encodée représentant un itinéraire DRIVE.

  3. travel_mode (énumération - FACULTATIF) : DRIVE (par défaut), WALK ou BICYCLE. WALK et BICYCLE ne sont compatibles qu'avec route_endpoints. TRANSIT n'est pas compatible.

  4. routing_preference (enum - FACULTATIF) :

    • ROUTING_PREFERENCE_TRAFFIC_UNAWARE (par défaut) : calcule l'itinéraire et les détours sans tenir compte du trafic en temps réel. Latence la plus faible.
    • ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL : utilise les conditions de circulation en temps réel lorsqu'elles sont disponibles. Non compatible avec WALK ou BICYCLE. Définissez cette option UNIQUEMENT lorsque l'utilisateur pose des questions sur le trafic, les embouteillages ou les temps de détour ajustés en fonction du trafic. Elle entraîne une latence plus élevée.

  5. include_extended_details (booléen, FACULTATIF) : définissez cette option sur true uniquement lorsque la requête nécessite des insights d'avis qualitatifs, des plats ou des offres spécifiques, l'ambiance, des conseils ou l'affluence des visiteurs, la disponibilité des bornes pour véhicules électriques, les prix du carburant ou d'autres détails qualitatifs enrichis. La valeur par défaut est false. L'activer peut augmenter la latence.

  6. language_code (chaîne, FACULTATIF) : langue du résumé des résultats et des détails du lieu, par exemple en, ja, en-US. La valeur par défaut est en-US.

  7. region_code (chaîne, FACULTATIF) : code de région CLDR Unicode de l'utilisateur, par exemple US, CA.

Instructions pour l'appel d'outil :

  • Chaque résultat inclut un detour_summary (si disponible) décrivant la distance supplémentaire (localized_detour_distance) et, sauf si l'itinéraire a été indiqué comme encoded_polyline, le temps supplémentaire (detour_duration) nécessaire pour s'arrêter à cet endroit. Utilisez-le pour comparer les options.
  • La réponse summary peut contenir des citations basées sur zéro (par exemple, "[0]") faisant référence à des entrées dans results.
  • La sortie ancrée doit être attribuée à la source à l'aide du champ attribution de chaque results[].place, lorsqu'il est disponible.

L'exemple de code suivant montre comment utiliser curl pour appeler l'outil MCP search_along_route.

Requête 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
}'

Schéma d'entrée

Message de requête pour SearchAlongRoute.

SearchAlongRouteRequest

Représentation 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.
}
Champs
textQuery

string

Obligatoire. Requête de recherche en langage naturel (par exemple, "bornes pour véhicules électriques", "café").
languageCode

string

Facultatif. Langue du résumé et des détails du lieu. La valeur par défaut est "en-US".
regionCode

string

Facultatif. Code pays/région (CLDR) de l'emplacement (par exemple, "US").
routingPreference

enum (RoutingPreference)

Facultatif. Préférence de routage facultative spécifiant comment les données de trafic sont utilisées. La valeur par défaut est TRAFFIC_UNAWARE.
includeExtendedDetails

boolean

Facultatif. Inclut des détails étendus sur le lieu dans la réponse.

Définissez ce champ sur true lorsque la requête de l'utilisateur nécessite des insights qualitatifs enrichis, une dynamique en temps réel ou des attributs d'entité spécialisés : avis qualitatifs, sentiment des clients et commentaires. - Offres spécifiques telles que des éléments de menu, des plats, des spécialités culinaires, des boissons ou des points forts de l'établissement. - Atmosphère, décoration intérieure, esthétique, ambiance ou humeur qualitative. - Données en temps réel et spécifications des établissements spécialisés, règles/conseils pour les visiteurs, temps d'attente.

Laissez false (par défaut) pour les recherches standards (par exemple, cuisines, types de magasins), les recherches de lieux/adresses, les coordonnées, les horaires d'ouverture et les métadonnées/services standards.

L'activation de ce champ peut entraîner une latence plus élevée.
travelMode

enum (RouteTravelMode)

Facultatif. Spécifie le mode de transport utilisé pour calculer l'itinéraire et les détours. La valeur par défaut est DRIVE. WALK et BICYCLE ne sont compatibles qu'avec route_endpoints. TRANSIT n'est pas compatible.
Champ d'union route_spec. Spécification de l'itinéraire : un itinéraire existant, un jeton d'itinéraire ou des points de terminaison de départ/destination. route_spec ne peut être qu'un des éléments suivants :
encodedPolyline

string

Chaîne de polyligne encodée représentant l'itinéraire. Consultez https://developers.google.com/maps/documentation/utilities/polylinealgorithm.
retrievalToken

string

Jeton de récupération renvoyé par un appel ComputeRoutes précédent représentant l'itinéraire.
routeEndpoints

object (RouteEndpoints)

Points de terminaison d'itinéraire explicites (point de départ et destination).

RouteEndpoints

Représentation JSON 
{
  "origin": {
    object (Waypoint)
  },
  "destination": {
    object (Waypoint)
  }
}
Champs
origin

object (Waypoint)

Obligatoire. Point de départ (adresse, ID de lieu ou coordonnées géographiques).
destination

object (Waypoint)

Obligatoire. Point de destination (adresse, ID de lieu ou coordonnées géographiques).

Repère

Représentation 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.
}
Champs
Champ d'union location_type. Différentes manières de représenter un lieu. location_type ne peut être qu'un des éléments suivants :
latLng

object (LatLng)

Point spécifié à l'aide de coordonnées géographiques.
placeId

string

ID de lieu associé au point de cheminement.
address

string

Adresse lisible ou Plus Code. Pour en savoir plus, consultez https://plus.codes.

LatLng

Représentation JSON 
{
  "latitude": number,
  "longitude": number
}
Champs
latitude

number

Latitude en degrés. Elle doit être comprise dans la plage [-90.0, +90.0].
longitude

number

Longitude en degrés. Elle doit être comprise dans la plage [-180.0, +180.0].

RoutingPreference

Ensemble de valeurs qui spécifient les facteurs à prendre en compte lors du calcul de l'itinéraire.

Enums
ROUTING_PREFERENCE_UNSPECIFIED Aucune préférence de routage spécifiée. La valeur par défaut est ROUTING_PREFERENCE_TRAFFIC_UNAWARE.
ROUTING_PREFERENCE_TRAFFIC_UNAWARE Calcule les itinéraires sans tenir compte des conditions de circulation en temps réel. Cette option est adaptée lorsque les conditions de circulation n'ont pas d'importance ou ne s'appliquent pas. L'utilisation de cette valeur permet d'obtenir la latence la plus faible.
ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL

Calcule les itinéraires en tenant compte des conditions de circulation en temps réel, lorsque les données de trafic sont disponibles. Pour TRANSIT, utilise les données de transports en commun en temps réel, telles que les retards et les annulations, lorsqu'elles sont disponibles.

Cette valeur déclenchera le niveau Pro, et entraînera des coûts de facturation et une latence plus élevés.

RouteTravelMode

Ensemble de valeurs utilisées pour spécifier le mode de transport.

Enums
ROUTE_TRAVEL_MODE_UNSPECIFIED Aucun mode de transport spécifié. La valeur par défaut est DRIVE.
DRIVE Trajet en voiture de particulier.
WALK Se déplacer à pied. REMARQUE : Les itinéraires WALK sont en version bêta et peuvent parfois ne pas inclure de trottoirs ou de voies piétonnes clairs. Vous devez afficher cet avertissement à l'utilisateur pour tous les itinéraires à pied que vous affichez dans votre application.
BICYCLE Se déplacer à vélo.
TRANSIT Trajet en transports en commun.

Schéma de sortie

Message de réponse pour SearchAlongRoute.

SearchAlongRouteResponse

Représentation JSON 
{
  "results": [
    {
      object (Result)
    }
  ],
  "summary": string,
  "contentToken": string
}
Champs
results[]

object (Result)

Uniquement en sortie. Liste classée des résultats de recherche trouvés le long de l'itinéraire.
summary

string

Uniquement en sortie. Résumé en langage naturel des résultats de recherche et des compromis liés aux détours. Peut contenir des citations commençant par zéro (par exemple, "[0]", "[1]") faisant référence aux entrées correspondantes dans la liste results.
contentToken

string

Uniquement en sortie. Jeton chiffré qui encapsule le contexte de recherche et peut être transmis aux services de rendu visuel Google Maps, aux SDK ou au Maps Agentic UI Toolkit (A2UI) pour afficher des composants d'interface utilisateur interactifs pour les résultats de recherche renvoyés.

Résultat

Représentation JSON 
{
  "place": {
    object (PlaceView)
  },
  "detourSummary": {
    object (DetourSummary)
  }
}
Champs
place

object (PlaceView)

Uniquement en sortie. Détails sur le lieu trouvé le long de l'itinéraire.
detourSummary

object (DetourSummary)

Uniquement en sortie. Métriques de détour générées par l'ajout de ce lieu en tant qu'arrêt intermédiaire sur l'itinéraire. Omis ou vide si les métriques de détour n'ont pas pu être calculées.

PlaceView

Représentation 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.
}
Champs
place

string

Nom de ressource du lieu sous-jacent, au format "places/{id}".
id

string

ID de lieu du lieu sous-jacent.
googleMapsLinks

object (GoogleMapsLinks)

Liens permettant de déclencher différentes actions Google Maps.
attribution

object (Attribution)

Attribution requise à afficher avec le lieu.

Champ d'union _location.

_location ne peut être qu'un des éléments suivants :
location

object (LatLng)

Position de ce lieu.

LatLng

Représentation JSON 
{
  "latitude": number,
  "longitude": number
}
Champs
latitude

number

Latitude en degrés. Elle doit être comprise dans la plage [-90.0, +90.0].
longitude

number

Longitude en degrés. Elle doit être comprise dans la plage [-180.0, +180.0].
Représentation JSON 
{
  "directionsUrl": string,
  "placeUrl": string,
  "writeAReviewUrl": string,
  "reviewsUrl": string,
  "photosUrl": string
}
Champs
directionsUrl

string

Lien permettant d'afficher l'itinéraire vers le lieu. Le lien ne renseigne que le lieu de destination et utilise le mode de transport par défaut DRIVE.
placeUrl

string

Lien pour afficher ce lieu.
writeAReviewUrl

string

Un lien permettant de rédiger un avis sur ce lieu dans Google Maps.
reviewsUrl

string

Lien permettant d'afficher les avis sur cet établissement dans Google Maps.
photosUrl

string

Lien permettant d'afficher des photos de ce lieu sur Google Maps.

Attribution

Représentation JSON 
{
  "title": string,
  "url": string
}
Champs
title

string

Titre à afficher pour l'attribution.
url

string

URL vers laquelle rediriger l'utilisateur pour l'attribution.

DetourSummary

Représentation JSON 
{
  "detourDuration": string,
  "localizedDetourDistance": string
}
Champs
detourDuration

string (Duration format)

Temps de trajet supplémentaire nécessaire pour faire un détour par ce lieu depuis l'itinéraire principal. Cette valeur n'est pas définie si la route est spécifiée par encoded_polyline.

Durée en secondes avec neuf chiffres au maximum après la virgule et se terminant par "s". Exemple : "3.5s"
localizedDetourDistance

string

Distance supplémentaire requise pour faire un détour par ce lieu depuis l'itinéraire principal, formatée pour l'affichage dans la langue de la requête (par exemple, "1,2 mi" ou "1,9 km").

Durée

Représentation JSON 
{
  "seconds": string,
  "nanos": integer
}
Champs
seconds

string (int64 format)

Secondes signées de l'intervalle de temps. Doit être compris entre -315 576 000 000 et +315 576 000 000 (inclus). Remarque : Ces limites sont calculées à partir de : 60 s/min * 60 min/h * 24 h/jour * 365,25 jours/an * 10 000 ans.
nanos

integer

Fractions de seconde signées à une résolution de l'ordre de la nanoseconde de l'intervalle de temps. Les durées inférieures à une seconde sont représentées par un champ seconds de valeur 0 et un champ nanos positif ou négatif. Pour les durées d'une seconde ou plus, une valeur non nulle pour le champ nanos doit avoir le même signe que le champ seconds. La valeur doit être comprise entre -999 999 999 et +999 999 999 inclus.

Annotations d'outils

Les annotations d'outil sont envoyées aux clients MCP pour décrire le risque de base d'un outil donné. La plupart des clients considèrent ces indications comme non fiables, mais elles peuvent être utilisées pour décider quand envoyer une invite de confirmation à un utilisateur.

En plus de la chaîne de titre, les indications booléennes suivantes sont définies comme suit :

  • readOnlyHint : si la valeur est "true", l'outil ne modifie pas son environnement. Valeur par défaut : "false".
  • destructiveHint : si la valeur est "true", l'outil peut effectuer des actions destructrices. Si la valeur est "false", l'outil ne peut effectuer que des actions d'ajout. Valeur par défaut : "true".
  • idempotentHint : si la valeur est "true", l'appel répété de l'outil avec les mêmes arguments n'aura aucun effet supplémentaire sur son environnement. Valeur par défaut : "false".
  • openWorldHint : si la valeur est "true", l'outil peut interagir avec un "monde ouvert" d'entités externes. Si la valeur est "false", l'outil ne peut interagir qu'avec des entités internes. Par exemple, un outil de recherche sur le Web serait en monde ouvert, tandis qu'un outil de mémoire ne le serait pas.

Destructive Hint: ❌ | Idempotent Hint: ❌ | Read Only Hint: ✅ | Open World Hint: ❌