Rechercher sur le trajet

L'outil search_along_route permet à un LLM de trouver des lieux le long d'un itinéraire de voyage à partir d'une requête en langage naturel, comme des bornes de recharge VE sur la route du lac Tahoe ou des cafés entre San Francisco et San Jose. L'outil renvoie un résumé généré par IA des lieux correspondants et des détours qu'ils impliquent. Pour chaque lieu cité dans le résumé, la réponse inclut également l'ID de lieu, les coordonnées de latitude/longitude, les liens Google Maps, l'attribution requise et les métriques de détour.

Chaque requête search_along_route est une option Pro et est facturée sous le SKU Maps Grounding Pro.

Vous pouvez appeler search_along_route via le serveur MCP ou en tant que méthode REST searchAlongRoute. Cette page décrit les options de requête, comment spécifier un itinéraire, ce que contient la réponse et comment les requêtes sont facturées. Pour obtenir les schémas complets, consultez la documentation de référence sur le MCP search_along_route et la documentation de référence sur REST searchAlongRoute.

Options de requête

Le LLM définit ces options lorsqu'il appelle l'outil, en fonction de la requête de l'utilisateur et de la description de l'outil. Vous pouvez influencer les options utilisées par le modèle avec vos propres instructions. Consultez Contrôler l'utilisation de Pro.

Le tableau suivant décrit les options de requête pour search_along_route :

Option Description
text_query Obligatoire. Requête de recherche en langage naturel pour les lieux situés le long de l'itinéraire, par exemple ev chargers, coffee ou vegetarian restaurants.
retrieval_token, route_endpoints ou encoded_polyline Obligatoire. Itinéraire le long duquel effectuer la recherche. Spécifiez l'un de ces trois champs dans chaque requête. Consultez Spécifier un itinéraire.
travel_mode Facultatif. Mode de transport utilisé pour calculer l'itinéraire et les détours : DRIVE (par défaut), WALK ou BICYCLE. WALK et BICYCLE ne sont compatibles qu'avec route_endpoints. TRANSIT n'est pas compatible. Les itinéraires WALK sont en version bêta et peuvent parfois ne pas comporter de trottoirs ou de chemins piétons clairement identifiés. Vous devez afficher cet avertissement pour tous les itinéraires piétons que vous affichez dans votre application.
routing_preference Facultatif. Comment les données de trafic sont utilisées pour calculer les temps d'itinéraire et de détour : ROUTING_PREFERENCE_TRAFFIC_UNAWARE (par défaut) ou ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL. ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL utilise les conditions de circulation en temps réel lorsqu'elles sont disponibles. Il n'est pas compatible avec WALK ou BICYCLE.
include_extended_details Facultatif. Lorsque true, le résumé inclut des informations détaillées sur le lieu, telles que des insights issus des avis, des éléments du menu, l'ambiance, des conseils de visiteurs, la disponibilité des bornes pour véhicules électriques ou les prix du carburant. La valeur par défaut est false.
language_code Facultatif. Code de langue BCP-47 pour le résumé et la distance de détour localisée (par exemple, en-US ou ja). La valeur par défaut est en-US.
region_code Facultatif. Code de région CLDR à deux lettres de l'utilisateur (par exemple, US ou CA). Cela affecte les noms de lieux spécifiques à une région et peut avoir un impact sur les résultats en fonction de la législation applicable.

Spécifier une route

Chaque requête search_along_route doit spécifier la route à l'aide de l'un des trois champs mutuellement exclusifs. Si vous définissez plusieurs champs de route ou si vous omettez les trois, une erreur INVALID_ARGUMENT est renvoyée.

Le tableau suivant compare les trois façons de spécifier une route :

Option d'itinéraire Format d'entrée Modes de transport compatibles Renvoie detourDuration Quand l'utiliser ?
retrieval_token La chaîne retrievalToken d'une réponse compute_routes précédente (valide pendant 10 minutes) DRIVE Oui L'agent a déjà appelé compute_routes pour un itinéraire en voiture, y compris des itinéraires avec des arrêts intermédiaires, et l'utilisateur demande des lieux le long de cet itinéraire.
route_endpoints Un objet avec des points de cheminement origin et destination (address, place_id ou lat_lng) DRIVE, WALK, BICYCLE Oui L'utilisateur demande à trouver des lieux entre deux emplacements en une seule étape sans appeler d'abord compute_routes, ou l'itinéraire utilise la marche ou le vélo.
encoded_polyline Une chaîne de polyligne encodée représentant un itinéraire en voiture DRIVE Non (renvoie uniquement localizedDetourDistance) Votre application dispose déjà d'une polyligne d'itinéraire provenant d'une autre source, telle que l'API Routes.

Chaîne compute_routes et search_along_route

Lorsqu'une requête compute_routes utilise le mode de transport DRIVE, chaque itinéraire de la réponse inclut un champ retrievalToken. Ce jeton est valide pendant 10 minutes et encode l'itinéraire calculé, y compris les arrêts intermédiaires. Lorsque l'utilisateur demande ensuite des lieux le long de cet itinéraire, le LLM peut transmettre la valeur retrievalToken en tant que retrieval_token dans search_along_route.

Place Details (Advanced)

Définissez include_extended_details sur true lorsque la requête de l'utilisateur nécessite des insights qualitatifs, des conditions en temps réel ou des attributs spécialisés le long de l'itinéraire, par exemple :

  • Avis des utilisateurs : insights basés sur les avis, sentiment des clients et commentaires.
  • Offres spécifiques : éléments de menu, plats, spécialités culinaires, boissons ou points forts de l'établissement.
  • Atmosphère : décoration intérieure, esthétique, ambiance ou humeur.
  • Conseils pratiques pour les visiteurs et données en temps réel : réservation à l'avance, temps d'attente, affluence, disponibilité des bornes de recharge pour véhicules électriques, prix du carburant, parking et installations.

Laissez include_extended_details défini sur false (valeur par défaut) pour les recherches standards le long d'un itinéraire, par exemple pour trouver des stations-service, des aires de repos ou des cafés en fonction de l'emplacement, des horaires d'ouverture et du temps de détour. Les requêtes avec des détails étendus prennent plus de temps, mais elles n'entraînent pas de frais supplémentaires, car chaque requête search_along_route est déjà facturée sous le SKU Pro.

Exemples

La requête MCP suivante recherche des bornes de recharge VE entre San Francisco et Lake Tahoe à l'aide de route_endpoints et d'un itinéraire tenant compte du trafic :

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

L'exemple suivant utilise un retrieval_token d'une réponse compute_routes précédente :

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

Remplacez RETRIEVAL_TOKEN par la chaîne retrievalToken renvoyée par compute_routes.

L'exemple suivant envoie la première requête à la méthode 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"

Remplacez API_KEY par votre clé API.

Réponse

La réponse contient les champs suivants :

  • summary : résumé en langage naturel des résultats de recherche et des compromis liés au détour. Il peut contenir des citations basées sur zéro, telles que [0], qui correspondent à des entrées dans results.
  • results[] : liste classée des lieux mentionnés dans le résumé. Chaque entrée inclut les éléments suivants :
    • place : détails sur le lieu :
      • place : nom de ressource du lieu, au format places/{id}.
      • id : ID de lieu. Vous pouvez l'utiliser avec d'autres API Google Maps Platform, par exemple pour afficher le lieu sur une carte.
      • location : coordonnées de latitude/longitude du lieu.
      • googleMapsLinks : liens Google Maps vers le lieu (placeUrl), l'itinéraire (directionsUrl), les avis (reviewsUrl), les photos (photosUrl) et la rédaction d'un avis (writeAReviewUrl).
      • attribution : attribution que vous devez afficher avec le lieu. Consultez Exigences d'attribution.
    • detourSummary : temps de trajet et distance supplémentaires nécessaires pour s'arrêter à cet endroit sur l'itinéraire :
      • localizedDetourDistance : distance supplémentaire formatée dans la langue de la requête, par exemple "1.2 mi" ou "1.9 km".
      • detourDuration : temps de trajet supplémentaire sous forme de chaîne de durée, par exemple "180s". Ce champ n'est pas défini lorsque la route est spécifiée avec encoded_polyline.
  • contentToken : jeton de visualisation des données agentique (preview) qui vous permet d'afficher les lieux de la réponse avec le kit UI pour Places sans frais supplémentaires. Renvoyé lorsque la réponse inclut au moins un lieu.

Pour en savoir plus sur les champs, consultez la documentation de référence sur search_along_route.

Facturation et quotas

Chaque requête search_along_route correspond à un événement facturable sous le SKU Maps Grounding Pro. La définition de include_extended_details sur true ou de routing_preference sur ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL n'entraîne pas de frais supplémentaires. Si votre agent appelle d'abord compute_routes, puis transmet retrieval_token à search_along_route, chaque appel d'outil est facturé comme une requête distincte.

Si vous affichez les lieux d'une réponse search_along_route avec le Kit UI pour Places, vous pouvez utiliser le jeton de visualisation des données agentique (preview) pour que ces requêtes du Kit UI pour Places ne soient pas facturées.

Le quota search_along_route est de 300 requêtes par minute pour chaque projet. Pour connaître les tarifs, consultez la grille tarifaire principale et la grille tarifaire pour l'Inde.