MCP Tools Reference: mapstools.googleapis.com

Strumento: search_along_route

Chiama questo strumento quando l'utente vuole trovare luoghi, attività o punti di interesse lungo un percorso di viaggio (ad es. "stazioni di servizio sulla strada per Tahoe", "bar tra SF e San Jose"). La chiamata a questo strumento comporta un costo più elevato rispetto a search_places, quindi utilizza search_places quando esegui una ricerca vicino a una singola località anziché lungo un percorso.

Requisiti di input (FONDAMENTALI):

  1. text_query (stringa - OBBLIGATORIO): una descrizione in linguaggio naturale di cosa cercare lungo il percorso.

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

  2. Route specification (MANDATORY - provide exactly ONE of the following):

    • retrieval_token (stringa): il retrieval_token restituito da una chiamata compute_routes precedente per un percorso DRIVE. Preferisci questa opzione ogni volta che il percorso è già stato calcolato. Il token è valido per 10 minuti.
    • route_endpoints (oggetto): origin e destination del percorso. Ognuno deve essere fornito utilizzando address, lat_lng o place_id.
      • Esempio: {"route_endpoints": {"origin": {"address": "San Francisco, CA"}, "destination": {"address": "Lake Tahoe, CA"}}}
    • encoded_polyline (stringa): una polilinea codificata che rappresenta un percorso DRIVE.

  3. travel_mode (enum - FACOLTATIVO): DRIVE (predefinito), WALK o BICYCLE. WALK e BICYCLE sono supportati solo con route_endpoints. TRANSIT non è supportato.

  4. routing_preference (enum - FACOLTATIVO):

    • ROUTING_PREFERENCE_TRAFFIC_UNAWARE (valore predefinito): calcola il percorso e le deviazioni senza traffico in tempo reale. Latenza minima.
    • ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL: utilizza le condizioni del traffico in tempo reale, se disponibili. Non supportato per WALK o BICYCLE. Imposta questo valore SOLO quando l'utente chiede informazioni sul traffico, sulla congestione o sui tempi di deviazione in base al traffico. Comporta una latenza maggiore.

  5. include_extended_details (booleano - FACOLTATIVO): imposta su true solo quando la richiesta richiede approfondimenti qualitativi sulle recensioni, voci di menu o offerte specifiche, atmosfera, suggerimenti o affollamento dei visitatori, disponibilità di caricabatterie EV, prezzi del carburante o altri dettagli qualitativi avanzati. Il valore predefinito è false. L'attivazione di questa opzione potrebbe aumentare la latenza.

  6. language_code (stringa - FACOLTATIVO): la lingua per il riepilogo dei risultati e i dettagli del luogo, ad esempio en, ja, en-US. Il valore predefinito è en-US.

  7. region_code (stringa - FACOLTATIVA): il codice regione CLDR Unicode dell'utente, ad esempio US, CA.

Instructions for Tool Call:

  • Ogni risultato include un detour_summary (se disponibile) che descrive la distanza aggiuntiva (localized_detour_distance) e, a meno che il percorso non sia stato fornito come encoded_polyline, il tempo aggiuntivo (detour_duration) necessario per fermarsi in quel luogo. Utilizzalo per confrontare le opzioni.
  • La risposta summary può contenere citazioni basate su zero (ad es. "[0]") che fanno riferimento alle voci in results.
  • L'output basato su dati reali deve essere attribuito alla fonte utilizzando il campo attribution di ogni results[].place, se disponibile.

Il seguente esempio di codice mostra come utilizzare curl per chiamare lo strumento MCP search_along_route.

Richiesta 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
}'

Schema di input

Messaggio di richiesta per SearchAlongRoute.

SearchAlongRouteRequest

Rappresentazione 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.
}
Campi
textQuery

string

Obbligatorio. Query di ricerca in linguaggio naturale (ad es. "caricabatterie EV", "caffè").
languageCode

string

Facoltativo. La lingua per il riepilogo e i dettagli del luogo. Il valore predefinito è "en-US".
regionCode

string

Facoltativo. Codice paese/regione (CLDR) della località (ad es. "US").
routingPreference

enum (RoutingPreference)

Facoltativo. Preferenza di routing facoltativa che specifica come vengono utilizzati i dati sul traffico. Il valore predefinito è TRAFFIC_UNAWARE.
includeExtendedDetails

boolean

Facoltativo. Include i Place Details estesi nella risposta.

Imposta questo campo su true quando la richiesta dell'utente richiede insight qualitativi dettagliati, dinamiche in tempo reale o attributi di entità specializzati: - Recensioni qualitative, sentiment dei clienti e feedback. - Offerte specifiche come voci di menu, piatti, specialità gastronomiche, bevande o caratteristiche dell'attività. - Atmosfera, arredamento interno, estetica, ambiente o mood qualitativi. - Dati in tempo reale e specifiche delle strutture specializzate, norme/suggerimenti per i visitatori, tempi di attesa.

Lascia false (valore predefinito) per le ricerche di scoperta standard (ad es. tipi di cucina, tipi di negozio), ricerche di località/indirizzi, dati di contatto, orari di apertura e metadati/servizi standard.

L'attivazione di questo campo potrebbe comportare una latenza maggiore.
travelMode

enum (RouteTravelMode)

Facoltativo. Specifica la modalità di viaggio utilizzata per calcolare il percorso e le deviazioni. Il valore predefinito è DRIVE. WALK e BICYCLE sono supportati solo con route_endpoints. TRANSIT non è supportato.
Campo unione route_spec. Specifica del percorso: un percorso esistente, un token del percorso o gli endpoint di origine/destinazione. route_spec può essere solo uno dei seguenti tipi:
encodedPolyline

string

Una stringa di polilinea codificata che rappresenta il percorso. Consulta https://developers.google.com/maps/documentation/utilities/polylinealgorithm
retrievalToken

string

Un token di recupero restituito da una chiamata ComputeRoutes precedente che rappresenta il percorso.
routeEndpoints

object (RouteEndpoints)

Endpoint espliciti del percorso (origine e destinazione).

RouteEndpoints

Rappresentazione JSON 
{
  "origin": {
    object (Waypoint)
  },
  "destination": {
    object (Waypoint)
  }
}
Campi
origin

object (Waypoint)

Obbligatorio. Punto di partenza (indirizzo, ID luogo o coordinate geografiche).
destination

object (Waypoint)

Obbligatorio. Punto di destinazione (indirizzo, ID luogo o coordinate geografiche).

Waypoint

Rappresentazione 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.
}
Campi
Campo unione location_type. Diversi modi per rappresentare una località. location_type può essere solo uno dei seguenti tipi:
latLng

object (LatLng)

Un punto specificato utilizzando le coordinate geografiche.
placeId

string

L'ID luogo associato al waypoint.
address

string

Indirizzo leggibile o Plus Code. Per maggiori dettagli, visita la pagina https://plus.codes.

LatLng

Rappresentazione JSON 
{
  "latitude": number,
  "longitude": number
}
Campi
latitude

number

La latitudine in gradi. Deve essere compreso nell'intervallo [-90,0, +90,0].
longitude

number

La longitudine in gradi. Deve essere compreso nell'intervallo [-180,0, +180,0].

RoutingPreference

Un insieme di valori che specificano i fattori da prendere in considerazione durante il calcolo del percorso.

Enum
ROUTING_PREFERENCE_UNSPECIFIED Nessuna preferenza di routing specificata. Il valore predefinito è ROUTING_PREFERENCE_TRAFFIC_UNAWARE.
ROUTING_PREFERENCE_TRAFFIC_UNAWARE Calcola i percorsi senza tenere conto delle condizioni del traffico in tempo reale. Adatto quando le condizioni del traffico non sono importanti o non sono applicabili. L'utilizzo di questo valore produce la latenza più bassa.
ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL

Calcola i percorsi tenendo conto delle condizioni del traffico in tempo reale, se i dati sul traffico sono disponibili. Per TRANSIT, utilizza i dati sul trasporto pubblico in tempo reale, come ritardi e cancellazioni, se disponibili.

Questo valore attiverà il livello Pro e comporterà costi fatturati e latenza più elevati.

RouteTravelMode

Un insieme di valori utilizzati per specificare la modalità di viaggio.

Enum
ROUTE_TRAVEL_MODE_UNSPECIFIED Nessuna modalità di trasporto specificata. Il valore predefinito è DRIVE.
DRIVE Viaggia in auto.
WALK Spostati a piedi. NOTA: i percorsi di WALK sono in versione beta e a volte potrebbero non includere marciapiedi o percorsi pedonali chiari. Devi mostrare questo avviso all'utente per tutti i percorsi a piedi che mostri nella tua app.
BICYCLE Spostamenti in bicicletta.
TRANSIT Viaggia con i mezzi pubblici.

Schema di output

Messaggio di risposta per SearchAlongRoute.

SearchAlongRouteResponse

Rappresentazione JSON 
{
  "results": [
    {
      object (Result)
    }
  ],
  "summary": string,
  "contentToken": string
}
Campi
results[]

object (Result)

Solo output. L'elenco classificato dei risultati di ricerca trovati lungo il percorso.
summary

string

Solo output. Riepilogo in linguaggio naturale dei risultati di ricerca e dei compromessi delle deviazioni. Può contenere citazioni in base zero (ad es. "[0]", "[1]") che fanno riferimento alle voci corrispondenti nell'elenco results.
contentToken

string

Solo output. Un token criptato che incapsula il contesto di ricerca e può essere passato ai servizi di rendering visivo di Google Maps, agli SDK o al Maps Agentic UI Toolkit (A2UI) per visualizzare componenti UI interattivi per i risultati di ricerca restituiti.

Risultato

Rappresentazione JSON 
{
  "place": {
    object (PlaceView)
  },
  "detourSummary": {
    object (DetourSummary)
  }
}
Campi
place

object (PlaceView)

Solo output. Dettagli sul luogo trovato lungo il percorso.
detourSummary

object (DetourSummary)

Solo output. Metriche della deviazione generate dall'aggiunta di questo luogo come fermata intermedia lungo il percorso. Omesso o vuoto se non è stato possibile calcolare le metriche di deviazione.

PlaceView

Rappresentazione 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.
}
Campi
place

string

Il nome risorsa del luogo sottostante, nel formato "places/{id}".
id

string

L'ID luogo del luogo sottostante.
googleMapsLinks

object (GoogleMapsLinks)

Link per attivare diverse azioni di Google Maps.
attribution

object (Attribution)

Attribuzione obbligatoria da mostrare con il luogo.

Campo unione _location.

_location può essere solo uno dei seguenti tipi:
location

object (LatLng)

La posizione di questo luogo.

LatLng

Rappresentazione JSON 
{
  "latitude": number,
  "longitude": number
}
Campi
latitude

number

La latitudine in gradi. Deve essere compreso nell'intervallo [-90,0, +90,0].
longitude

number

La longitudine in gradi. Deve essere compreso nell'intervallo [-180,0, +180,0].
Rappresentazione JSON 
{
  "directionsUrl": string,
  "placeUrl": string,
  "writeAReviewUrl": string,
  "reviewsUrl": string,
  "photosUrl": string
}
Campi
directionsUrl

string

Un link per mostrare le indicazioni stradali per raggiungere il luogo. Il link compila solo la località di destinazione e utilizza la modalità di viaggio predefinita DRIVE.
placeUrl

string

Un link per mostrare questo luogo.
writeAReviewUrl

string

Un link per scrivere una recensione per questo luogo su Google Maps.
reviewsUrl

string

Un link per mostrare le recensioni di questo luogo su Google Maps.
photosUrl

string

Un link per mostrare le foto di questo luogo su Google Maps.

Attribuzione

Rappresentazione JSON 
{
  "title": string,
  "url": string
}
Campi
title

string

Il titolo da visualizzare per l'attribuzione.
url

string

L'URL a cui collegare l'attribuzione.

DetourSummary

Rappresentazione JSON 
{
  "detourDuration": string,
  "localizedDetourDistance": string
}
Campi
detourDuration

string (Duration format)

Il tempo di percorrenza aggiuntivo necessario per deviare verso questo luogo dal percorso principale. Questo valore non viene impostato se la route è specificata da encoded_polyline.

Una durata in secondi con un massimo di nove cifre frazionarie, che termina con "s". Esempio: "3.5s".
localizedDetourDistance

string

La distanza aggiuntiva necessaria per deviare verso questo luogo dal percorso principale, formattata per la visualizzazione nella lingua della richiesta (ad es. "1,2 mi" o "1,9 km").

Durata

Rappresentazione JSON 
{
  "seconds": string,
  "nanos": integer
}
Campi
seconds

string (int64 format)

Secondi con segno dell'intervallo di tempo. Deve essere compreso tra -315.576.000.000 e +315.576.000.000 inclusi. Nota: questi limiti vengono calcolati da: 60 sec/min * 60 min/ora * 24 ore/giorno * 365,25 giorni/anno * 10.000 anni
nanos

integer

Frazioni di secondo con segno con risoluzione in nanosecondi dell'intervallo di tempo. Le durate inferiori a un secondo sono rappresentate con un campo seconds pari a 0 e un campo nanos positivo o negativo. Per durate di un secondo o più, un valore diverso da zero per il campo nanos deve avere lo stesso segno del campo seconds. Deve essere compreso tra -999.999.999 e +999.999.999 inclusi.

Annotazioni dello strumento

Le annotazioni degli strumenti vengono inviate ai client MCP per descrivere il rischio di base di un determinato strumento. La maggior parte dei client considera questi suggerimenti non attendibili, ma possono essere utilizzati per decidere quando inviare una richiesta di conferma a un utente.

Oltre alla stringa del titolo, i seguenti suggerimenti booleani sono definiti come segue:

  • readOnlyHint: se true, lo strumento non modifica il suo ambiente. Valore predefinito: false.
  • destructiveHint: se true, lo strumento può eseguire azioni distruttive. Se è false, lo strumento può eseguire solo azioni additive. Valore predefinito: true.
  • idempotentHint: se true, la chiamata ripetuta dello strumento con gli stessi argomenti non avrà alcun effetto aggiuntivo sul suo ambiente. Valore predefinito: false.
  • openWorldHint: se true, lo strumento può interagire con un "open world" di entità esterne. Se false, lo strumento può interagire solo con entità interne. Ad esempio, uno strumento di ricerca web sarebbe open world, mentre uno strumento di memoria non lo sarebbe.

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