Cerca lungo il percorso

Lo strumento search_along_route consente a un LLM di trovare luoghi lungo un percorso di viaggio da una query in linguaggio naturale, ad esempio stazioni di ricarica EV sulla strada per Lake Tahoe o bar tra San Francisco e San Jose. Lo strumento restituisce un riepilogo generato dall'AI dei luoghi corrispondenti e dei relativi compromessi in termini di deviazione. Per ogni luogo citato nel riepilogo, la risposta include anche l'ID luogo, le coordinate di latitudine/longitudine, i link a Google Maps, l'attribuzione richiesta e le metriche di deviazione.

Ogni richiesta search_along_route è un'opzione Pro e viene fatturata in base allo SKU Maps Grounding Pro.

Puoi chiamare search_along_route tramite il server MCP o come metodo REST searchAlongRoute. Questa pagina descrive le opzioni di richiesta, come specificare un percorso, cosa contiene la risposta e come vengono fatturate le richieste. Per gli schemi completi, consulta il riferimento MCP di search_along_route e il riferimento REST di searchAlongRoute.

Opzioni di richiesta

L'LLM imposta queste opzioni quando chiama lo strumento, in base alla richiesta dell'utente e alla descrizione dello strumento. Puoi influenzare le opzioni utilizzate dal modello con le tue istruzioni. Consulta Controlla l'utilizzo di Pro.

La tabella seguente descrive le opzioni di richiesta per search_along_route:

Opzione Descrizione
text_query Obbligatorio. La query di ricerca in linguaggio naturale per i luoghi lungo il percorso, ad esempio ev chargers, coffee o vegetarian restaurants.
retrieval_token, route_endpoints o encoded_polyline Obbligatorio. Il percorso lungo il quale eseguire la ricerca. Specifica uno di questi tre campi in ogni richiesta. Consulta Specifica una route.
travel_mode Facoltativo. La modalità di trasporto utilizzata per calcolare il percorso e le deviazioni: DRIVE (predefinita), WALK o BICYCLE. WALK e BICYCLE sono supportati solo con route_endpoints. TRANSIT non è supportato. I percorsi WALK sono in versione beta e a volte potrebbero non avere marciapiedi o percorsi pedonali chiari. Devi mostrare questo avviso all'utente per tutti i percorsi a piedi che mostri nella tua app.
routing_preference Facoltativo. Come vengono utilizzati i dati sul traffico per calcolare i tempi del percorso e della deviazione: ROUTING_PREFERENCE_TRAFFIC_UNAWARE (predefinito) o ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL. ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL utilizza le condizioni del traffico in tempo reale, se disponibili, e non è supportato per WALK o BICYCLE.
include_extended_details Facoltativo. Quando true, il riepilogo include Place Details estesi, come approfondimenti dalle recensioni, voci di menu, atmosfera, suggerimenti per i visitatori, disponibilità di caricabatterie EV o prezzi del carburante. Il valore predefinito è false.
language_code Facoltativo. Il codice lingua BCP-47 per il riepilogo e la distanza della deviazione localizzata, ad esempio en-US o ja. Il valore predefinito è en-US.
region_code Facoltativo. Il codice regione CLDR di due lettere dell'utente, ad esempio US o CA. Influisce sui nomi dei luoghi specifici della regione e può influire sui risultati in base alla legge vigente.

Specifica un percorso

Ogni richiesta search_along_route deve specificare il percorso utilizzando uno dei tre campi che si escludono a vicenda. Se imposti più di un campo di route o li ometti tutti e tre, viene restituito un errore INVALID_ARGUMENT.

La tabella seguente mette a confronto i tre modi per specificare un percorso:

Opzione percorso Formato di input Modalità di viaggio supportate Restituisce detourDuration Quando utilizzarla
retrieval_token La stringa retrievalToken di una risposta compute_routes precedente (valida per 10 minuti) DRIVE Sì L'agente ha già chiamato compute_routes per un percorso in auto, inclusi i percorsi con fermate intermedie, e l'utente chiede informazioni sui luoghi lungo il percorso.
route_endpoints Un oggetto con waypoint origin e destination (address, place_id o lat_lng) DRIVE, WALK e BICYCLE Sì L'utente chiede di trovare luoghi tra due località in un unico passaggio senza prima chiamare compute_routes oppure il percorso utilizza la modalità a piedi o in bicicletta.
encoded_polyline Una stringa di polilinea codificata che rappresenta un percorso in auto DRIVE No (restituisce solo localizedDetourDistance) La tua applicazione ha già una polilinea del percorso proveniente da un'altra origine, ad esempio l'API Routes.

Catena compute_routes e search_along_route

Quando una richiesta compute_routes utilizza la modalità di viaggio DRIVE, ogni percorso nella risposta include un campo retrievalToken. Questo token è valido per 10 minuti e codifica il percorso calcolato, incluse eventuali tappe intermedie. Quando l'utente prosegue chiedendo luoghi lungo quel percorso, l'LLM può passare il valore retrievalToken come retrieval_token in search_along_route.

Extended Place Details

Imposta include_extended_details su true quando la richiesta dell'utente richiede insight qualitativi, condizioni in tempo reale o attributi specializzati lungo il percorso, ad esempio:

  • Cosa dicono i recensori: approfondimenti basati sulle recensioni, sentiment dei clienti e feedback.
  • Offerte specifiche: voci di menu, piatti, specialità gastronomiche, bevande o caratteristiche dell'attività.
  • Atmosfera: arredamento, estetica, ambiente o atmosfera.
  • Suggerimenti pratici per i visitatori e dati in tempo reale: se prenotare in anticipo, tempi di attesa, affollamento del luogo, disponibilità di caricabatterie EV, prezzi del carburante, parcheggio e servizi.

Lascia include_extended_details impostato su false (valore predefinito) per le ricerche standard lungo un percorso, ad esempio per trovare stazioni di servizio, aree di sosta o bar in base alla località, all'orario di apertura e al tempo di deviazione. Le richieste con dettagli estesi richiedono più tempo per essere completate, ma non comportano costi aggiuntivi perché ogni richiesta search_along_route viene già fatturata con lo SKU Pro.

Esempi

La seguente richiesta MCP cerca le stazioni di ricarica EV tra San Francisco e Lake Tahoe utilizzando route_endpoints e il routing basato sul traffico:

{
  "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'esempio seguente utilizza un retrieval_token di una risposta compute_routes precedente:

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

Sostituisci RETRIEVAL_TOKEN con la stringa retrievalToken restituita da compute_routes.

L'esempio seguente invia la prima richiesta al metodo 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"

Sostituisci API_KEY con la tua chiave API.

Risposta

La risposta contiene i seguenti campi:

  • summary: un riepilogo in linguaggio naturale dei risultati di ricerca e dei compromessi della deviazione. Potrebbe contenere citazioni basate su zero, come [0], che rimandano a voci in results.
  • results[]: l'elenco classificato dei luoghi menzionati nel riepilogo. Ogni voce include:
    • place: dettagli sul luogo:
      • place: il nome della risorsa del luogo, nel formato places/{id}.
      • id: l'ID luogo. Puoi utilizzarlo con altre API di Google Maps Platform, ad esempio per mostrare il luogo su una mappa.
      • location: le coordinate di latitudine/longitudine del luogo.
      • googleMapsLinks: link di Google Maps per il luogo (placeUrl), le indicazioni stradali (directionsUrl), le recensioni (reviewsUrl), le foto (photosUrl) e la scrittura di una recensione (writeAReviewUrl).
      • attribution: l'attribuzione che devi mostrare con il luogo. Consulta i requisiti di attribuzione.
    • detourSummary: il tempo di percorrenza e la distanza aggiuntivi necessari per fermarsi in questo luogo lungo il percorso:
      • localizedDetourDistance: la distanza aggiuntiva formattata nella lingua della richiesta, ad esempio "1.2 mi" o "1.9 km".
      • detourDuration: il tempo di percorrenza aggiuntivo sotto forma di stringa di durata, ad esempio "180s". Questo campo non viene impostato quando il percorso viene specificato con encoded_polyline.
  • contentToken: un token di visualizzazione dei dati agentico (anteprima) che ti consente di visualizzare i luoghi nella risposta con Places UI Kit senza costi aggiuntivi. Viene restituito quando la risposta include almeno un luogo.

Per i dettagli completi dei campi, consulta il riferimento search_along_route.

Fatturazione e quote

Ogni richiesta search_along_route è un evento fatturabile nell'ambito dello SKU Maps Grounding Pro. L'impostazione di include_extended_details su true o di routing_preference su ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL non comporta costi aggiuntivi. Se l'agente effettua una chiamata agentica compute_routes e poi passa retrieval_token a search_along_route, ogni chiamata allo strumento viene fatturata come richiesta separata.

Se mostri i luoghi di una risposta search_along_route con Places UI Kit, puoi utilizzare il token di visualizzazione dei dati agentica (anteprima) in modo che le richieste di Places UI Kit non vengano fatturate.

La quota search_along_route è di 300 query al minuto per ogni progetto. Per i prezzi, consulta la tabella dei prezzi principale e la tabella dei prezzi per l'India.