MCP Reference: mapstools.googleapis.com

Chiama questo strumento quando la richiesta dell'utente è trovare luoghi, attività, indirizzi, località, punti di interesse o qualsiasi altra ricerca correlata a Google Maps.

Requisiti di input (FONDAMENTALI):

1. text_query (stringa - OBBLIGATORIO): la query di ricerca principale. Deve definire chiaramente ciò che l'utente sta cercando.

   • Esempi: 'restaurants in New York', 'coffee shops near Golden Gate Park', 'SF MoMA', '1600 Amphitheatre Pkwy, Mountain View, CA, USA', 'pets friendly parks in Manhattan, New York', 'date night restaurants in Chicago', 'accessible public libraries in Los Angeles'.
   • Per dettagli specifici sul luogo: includi l'attributo richiesto (ad es. 'Google Store Mountain View opening hours', 'SF MoMa phone number', 'Shoreline Park Mountain View address').

2. location_bias (oggetto - FACOLTATIVO): utilizza questo parametro per dare la priorità ai risultati vicini a un'area geografica specifica.

   • Formato: {"location_bias": {"circle": {"center": {"latitude": [value], "longitude": [value]}, "radius_meters": [value (optional)]}}}
   • Utilizzo:
     • Per applicare un bias a un raggio di 5 km: {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}, "radius_meters": 5000}}}
     • Per dare una forte priorità al punto centrale: {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}}}} (omettendo radius_meters).

3. language_code (stringa - FACOLTATIVO): la lingua in cui mostrare il riepilogo dei risultati di ricerca.

   • Formato: un codice lingua di due lettere (ISO 639-1), facoltativamente seguito da un trattino basso e da un codice paese di due lettere (ISO 3166-1 alpha-2), ad esempio en, ja, en_US, zh_CN, es_MX. Se il codice lingua non viene fornito, i risultati saranno in inglese.

4. region_code (stringa - FACOLTATIVO): il codice regione CLDR Unicode dell'utente. Questo parametro viene utilizzato per visualizzare i Place Details, ad esempio il nome del luogo specifico per la regione, se disponibile. Il parametro può influire sui risultati in base alla legge vigente.

   • Formato: un codice paese di due lettere (ISO 3166-1 alpha-2), ad esempio US, CA.

5. page_size (integer - FACOLTATIVO): il numero massimo di luoghi da restituire, da 1 a 10. Il valore predefinito è 5. Imposta un valore superiore a 5 solo quando l'utente vuole confrontare più di 5 luoghi; i valori da 6 a 10 comportano costi e latenza più elevati.

6. include_extended_details (booleano - FACOLTATIVO): imposta questo campo su true quando la richiesta dell'utente richiede insight qualitativi dettagliati, dinamiche in tempo reale o attributi di entità specializzati. Il valore predefinito è false. L'impostazione di questo valore su true comporta costi e latenza più elevati.

Instructions for Tool Call:

• Dati sulla posizione (CRITICO): la ricerca deve contenere dati sulla posizione sufficienti. Se la località è ambigua (ad es. solo "pizzerie"), devi specificarla nel parametro text_query (ad es. "pizzerie a New York") o utilizzare il parametro location_bias. Includi il nome della città, dello stato/della provincia e della regione/del paese, se necessario per evitare ambiguità.

• Fornisci sempre il text_query più specifico e ricco di contesto possibile.

• Utilizza location_bias solo se le coordinate vengono fornite esplicitamente o se è opportuno dedurre una posizione dal contesto noto di un utente e necessario per ottenere risultati migliori.

• L'output basato su dati reali deve essere attribuito alla fonte utilizzando le informazioni del campo attribution, se disponibili.

Calcola i percorsi di viaggio tra un'origine e una destinazione, facoltativamente attraverso fermate intermedie. Restituisce la distanza e la durata di ogni percorso.

Requisiti di input (FONDAMENTALI):

1. origin e destination (oggetti - OBBLIGATORI): ciascuno deve essere fornito utilizzando esattamente uno dei seguenti elementi:

   • address (stringa, ad es. 'Eiffel Tower, Paris'). I luoghi, i punti di riferimento e le attività con un nome vengono risolti direttamente, quindi NON chiamare prima search_places solo per geocodificare un waypoint. Includi qualsiasi città, regione o paese menzionato dall'utente.
   • lat_lng (oggetto, {"latitude": number, "longitude": number}).
   • place_id (stringa, ad esempio 'ChIJOwE_Id1w5EAR4Q27FkL6T_0'), ad esempio da search_places.

2. intermediate_waypoints (array di oggetti - FACOLTATIVO): fino a 25 tappe da attraversare, in ordine, tra l'origine e la destinazione. Stesso formato di origin. Non supportato con TRANSIT. Includi solo le fermate richieste dall'utente. Se specifichi più di 10 tappe intermedie, i costi e la latenza saranno più elevati.

3. travel_mode (enum - FACOLTATIVO): DRIVE (predefinito), WALK, BICYCLE o TRANSIT.

4. Tempistica (FACOLTATIVO - imposta al massimo UN valore): timestamp RFC 3339 con un offset UTC, ad esempio '2026-09-19T08:00:00-07:00'. Il valore predefinito è la partenza immediata. Per TRANSIT, l'ora può essere impostata fino a 7 giorni nel passato o fino a 100 giorni nel futuro. Per le altre modalità, l'ora può essere impostata fino a 365 giorni nel futuro e non deve essere nel passato.

   • departure_time: da utilizzare quando l'utente indica quando partirà (ad es. "domani alle 8:00").
   • arrival_time: da utilizzare quando l'utente indica l'orario di arrivo (ad es. "arrivo alle 9:00").

5. routing_preference (enum - FACOLTATIVO):

   • ROUTING_PREFERENCE_TRAFFIC_UNAWARE (predefinito): ignora il traffico in tempo reale, gli incidenti e le chiusure. 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 su un orario di arrivo stimato basato sul traffico. Comporta costi e latenza più elevati.

6. location_bias (oggetto - FACOLTATIVO): {"latitude": number, "longitude": number} utilizzato per eliminare l'ambiguità dei nomi dei luoghi negli indirizzi dei waypoint. Se un nome è ambiguo (ad es. "Springfield") e l'utente non ha fornito una regione, mantieni il nome così come è stato fornito in address e imposta location_bias sull'area prevista anziché indovinare una regione.

7. compute_alternative_routes (booleano - FACOLTATIVO): impostalo su true solo quando l'utente richiede opzioni o alternative per il percorso. Il valore predefinito è false, che restituisce solo il percorso consigliato.

8. include_polyline (booleano - FACOLTATIVO): imposta su true solo quando è necessaria la geometria del percorso (encoded_polyline). Il valore predefinito è false.

Instructions for Tool Call:

• Se l'origine o la destinazione non sono presenti, DEVI chiedere chiarimenti all'utente prima di chiamare lo strumento.
• Per le domande del tipo "Quanto dista A da B?", utilizza B come origin e A come destination.

Esempio di chiamata allo strumento: {"origin":{"address":"Eiffel Tower"},"destination":{"place_id":"ChIJt_5xIthw5EARoJ71mGq7t74"},"intermediate_waypoints":[{"address":"Louvre Museum"}],"travel_mode":"DRIVE","departure_time":"2026-09-19T08:00:00+02:00"}

Instructions for Response:

• Quando vengono richiesti percorsi alternativi, questi vengono ordinati dal più consigliato al meno consigliato.
• Se routes è vuoto, comunica all'utente che non è stato trovato alcun percorso. Non provare a indovinare un percorso.
• Per trovare luoghi lungo un percorso DRIVE, passa il retrieval_token del percorso a search_along_route. Il token è valido per 10 minuti.
• Indica solo i fatti restituiti dallo strumento. NON inventare indicazioni stradali passo passo, linee di trasporto pubblico, stazioni, banchine o coincidenze.
• L'output basato su dati reali deve essere attribuito alla fonte utilizzando il campo attribution di ogni percorso, se disponibile.

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 a voci in results.
• L'output basato su dati reali deve essere attribuito alla fonte utilizzando il campo attribution di ogni results[].place, se disponibile.

Risolve un elenco di query di località specifiche (nomi di punti di riferimento o indirizzi esatti) in ID luogo di Google Maps canonici.

Requisiti di input (FONDAMENTALI):

1. queries (array di oggetti - OBBLIGATORIO): un elenco di query di località da risolvere. Puoi specificare fino a 20 query.

   • Ogni oggetto query deve avere:
     • text (stringa - OBBLIGATORIO): la query di testo che rappresenta un nome o un indirizzo di un luogo specifico da risolvere.
       • Esempi: 'Googleplex, Mountain View, CA', '1600 Amphitheatre Pkwy, Mountain View, CA', 'Eiffel Tower, Paris'.

2. location_bias (oggetto - FACOLTATIVO): utilizza questo parametro per dare la priorità ai risultati vicini a un'area geografica specifica.

   • Formato: {"viewport": {"low": {"latitude": [value], "longitude": [value]}, "high": {"latitude": [value], "longitude": [value]}}}

3. region_code (stringa - FACOLTATIVO): il codice regione CLDR Unicode (codice paese di due lettere, ad esempio US, CA) dell'utente per influenzare i risultati.

Instructions for Tool Call:

• Specificità (CRITICO): le query devono rappresentare un nome o un indirizzo di un luogo specifico. Le ricerche generiche come 'restaurants' o i nomi di catene come 'Starbucks' non sono supportati.
• NON chiamare questo strumento se gli strumenti downstream che prevedi di richiamare accettano già direttamente stringhe di indirizzi o nomi di luoghi non elaborati.

Salva in Google Maps:

• La risposta include un campo save_to_maps_url: un singolo link a Google Maps contenente tutti i luoghi risolti correttamente.
• Quando l'utente vuole salvare, condividere o aprire i luoghi risolti come elenco in Google Maps, presentagli questo link. NON creare questo link manualmente.

Gestione degli errori (CRITICO):

• Si tratta di uno strumento di elaborazione batch. Una richiesta potrebbe restituire "risultati misti" (ad esempio, alcune query vengono risolte correttamente, mentre altre non vanno a buon fine).
• L'elenco di output di results viene mappato 1:1 con gli indici queries di input. Una query non riuscita genererà un messaggio Result vuoto (nessun entity impostato) nell'indice corrispondente nell'elenco results.
• DEVI controllare il campo della mappa failed_requests nella risposta per identificare l'indice di query specifico che non è riuscito. La chiave di failed_requests rappresenta l'indice in base zero della query non riuscita nella richiesta. Non dare per scontato che l'intera chiamata batch non sia riuscita a causa di un errore parziale.

Risolve un elenco di URL di Google Maps in ID luogo canonici di Google Maps.

Quando chiamare questo strumento (CRITICO):

• Utilizza questo strumento quando l'utente fornisce uno o più link o URL di condivisione di Google Maps (ad es. "https://maps.app.goo.gl/…", "https://www.google.com/maps/place/…" o "https://maps.google.com/…") e devi estrarre gli ID luogo canonici sottostanti.
• Puoi specificare fino a 20 URL da risolvere in una singola richiesta batch.

Requisiti di input (FONDAMENTALI):

• urls (array di stringhe - OBBLIGATORIO): l'elenco degli URL di Google Maps da risolvere. Ogni URL deve essere un URL di Google Maps valido e relativo a un singolo luogo.

Salva in Google Maps:

• La risposta include un campo save_to_maps_url: un singolo link a Google Maps contenente tutti i luoghi risolti correttamente.
• Quando l'utente vuole salvare, condividere o aprire i luoghi risolti come elenco in Google Maps (ad es. raccogliere i luoghi condivisi in una conversazione), presentagli questo link. NON creare questo link manualmente.

Gestione degli errori (CRITICO):

• Si tratta di uno strumento di elaborazione batch. Una richiesta potrebbe restituire "risultati misti" (ad esempio, alcuni URL vengono risolti correttamente, mentre altri no).
• L'elenco di output di entities viene mappato 1:1 con gli indici urls di input. Una risoluzione dell'URL non riuscita comporterà un messaggio Entity vuoto (nessun campo impostato) nell'indice corrispondente nell'elenco entities.
• DEVI controllare il campo della mappa failed_requests nella risposta per identificare l'indice dell'URL specifico che non è riuscito. La chiave di failed_requests rappresenta l'indice in base zero dell'URL non riuscito nella richiesta. Non dare per scontato che l'intera chiamata batch non sia riuscita a causa di un errore parziale.