Ricevere indicazioni stradali tramite l'API Directions (legacy)

Sviluppatori dello Spazio economico europeo (SEE)

Questo prodotto è in stato legacy. A partire da ottobre 2026, l'API Directions (legacy) non potrà più essere abilitata per i nuovi progetti Google Cloud. I progetti esistenti continuano a essere completamente supportati. Per nuove funzionalità e prestazioni migliorate, esegui la migrazione all'API Routes.

Per i calcoli delle indicazioni stradali che rispondono in tempo reale all'input dell'utente (ad esempio, all'interno di un elemento dell'interfaccia utente), puoi utilizzare l'API Directions (Legacy) o, se utilizzi l'API Maps JavaScript, il servizio Directions. Per l'utilizzo lato server, puoi utilizzare il client Java, il client Python, il client Go e il client Node.js per i servizi Google Maps.

Con l'API Directions (Legacy), puoi:

  • Cerca indicazioni stradali per diverse modalità di trasporto, tra cui trasporto pubblico, auto, percorsi a piedi o in bicicletta.
  • Restituisce indicazioni stradali in più parti utilizzando una serie di tappe.
  • Specifica le origini, le destinazioni e i waypoint come stringhe di testo (ad es. "Chicago, IL" o "Darwin, NT, Australia"), come ID luogo o come coordinate di latitudine/longitudine.

L'API restituisce i percorsi più efficienti quando calcola le indicazioni stradali. Il tempo di percorrenza è il fattore principale ottimizzato, ma l'API può anche prendere in considerazione altri fattori, come la distanza, il numero di svolte e molti altri, per decidere quale percorso è il più efficiente.

Prima di iniziare

Prima di iniziare a utilizzare l'API Directions (Legacy), devi avere un progetto con un account di fatturazione e l'API Directions (Legacy) abilitata. Per saperne di più, consulta Configura nella console Cloud.

Crea le tue richieste dell'API Directions (Legacy)

Una richiesta dell'API Directions (Legacy) ha il seguente formato:

https://maps.googleapis.com/maps/api/directions/outputFormat?parameters

dove outputFormat può essere uno dei seguenti valori:

  • json (consigliato) indica l'output in JavaScript Object Notation (JSON)
  • xml indica l'output in formato XML

Nota: Gli URL devono essere codificati correttamente per essere validi e sono limitati a 16384 caratteri per tutti i servizi web. Tieni presente questo limite quando crei gli URL.

Come di consueto negli URL, tutti i parametri sono separati utilizzando il carattere e commerciale (&). Tutti i caratteri riservati (ad esempio il segno più "+") devono essere codificati nell'URL. L'elenco dei parametri e dei relativi valori possibili è riportato di seguito.

Parametri obbligatori

destinazione

L'ID luogo, l'indirizzo o il valore testuale di latitudine/longitudine per cui vuoi calcolare le indicazioni stradali. Le opzioni per il parametro di destinazione sono le stesse del parametro di origine.

origine

L'ID luogo, l'indirizzo o il valore testuale di latitudine/longitudine da cui vuoi calcolare le indicazioni stradali.

  • Gli ID luogo devono essere preceduti dal prefisso place_id:. Puoi recuperare gli ID luogo dall'API Geocoding e dall'API Places (incluso Place Autocomplete). Per un esempio di utilizzo degli ID luogo di Place Autocomplete, consulta Place Autocomplete e Directions. Per saperne di più sugli ID luogo, consulta la panoramica degli ID luogo. 

    origin=place_id:ChIJ3S-JXmauEmsRUcIaWtf4MzE

  • Se passi un indirizzo, il servizio Directions geocodifica la stringa e la converte in una coordinata di latitudine/longitudine per calcolare le indicazioni stradali. Questa coordinata potrebbe essere diversa da quella restituita dall'API Geocoding, ad esempio l'ingresso di un edificio anziché il suo centro. 

    origin=24+Sussex+Drive+Ottawa+ON

    È preferibile utilizzare gli ID luogo anziché gli indirizzi o le coordinate di latitudine/longitudine. L'utilizzo delle coordinate comporterà sempre l'aggancio del punto alla strada più vicina a queste coordinate, che potrebbe non essere un punto di accesso alla proprietà o nemmeno una strada che conduce rapidamente o in sicurezza alla destinazione.

  • Se passi le coordinate, il punto verrà agganciato alla strada più vicina. È preferibile passare un ID luogo. Se passi le coordinate, assicurati che non ci siano spazi tra i valori di latitudine e longitudine. 

    origin=41.43206,-81.38992

  • I Plus Code devono essere formattati come codice globale o codice composto. Formatta i Plus Code come mostrato qui (i segni più vengono convertiti in %2B e gli spazi in %20).

    • Un codice globale è un prefisso di 4 caratteri e un codice locale di almeno 6 caratteri (849VCWC8+R9 è 849VCWC8%2BR9).
    • Un codice composto è un codice locale di almeno sei caratteri con una posizione esplicita (CWC8+R9 Mountain View, CA, USA è CWC8%2BR9%20Mountain%20View%20CA%20USA).
Nota: per maggiore efficienza e precisione, utilizza gli ID luogo, se possibile. Questi ID sono univoci ed espliciti, come una coppia di valori di latitudine/longitudine, e offrono vantaggi di geocodifica per il routing, come punti di accesso e variabili di traffico. A differenza di un indirizzo, gli ID non richiedono al servizio di eseguire una ricerca o una richiesta intermedia di dettagli dei luoghi, pertanto le prestazioni sono migliori.

Parametri facoltativi

alternative

Se impostato su true, specifica che il servizio Directions può fornire più di un'alternativa di percorso nella risposta. Tieni presente che fornire percorsi alternativi potrebbe aumentare il tempo di risposta del server. Questa opzione è disponibile solo per le richieste senza waypoint intermedi. Per saperne di più, consulta la guida ai waypoint.

arrival_time

Specifica l'orario di arrivo preferito per le indicazioni per il trasporto pubblico, in secondi dalla mezzanotte del 1° gennaio 1970 UTC. Puoi specificare departure_time o arrival_time, ma non entrambi. Tieni presente che arrival_time deve essere specificato come numero intero.

evitare

Indica che i percorsi calcolati devono evitare le caratteristiche indicate. Questo parametro supporta i seguenti argomenti:

  • tolls indica che il percorso calcolato deve evitare strade/ponti a pedaggio.
  • highways indica che il percorso calcolato deve evitare le autostrade.
  • ferries indica che il percorso calcolato deve evitare i traghetti.
  • indoor indica che il percorso calcolato deve evitare scale interne per le indicazioni stradali a piedi e con il trasporto pubblico.

È possibile richiedere un percorso che eviti qualsiasi combinazione di pedaggi, autostrade e traghetti passando più limitazioni al parametro avoid. Ad esempio: 

avoid=tolls|highways|ferries.

departure_time

Specifica l'orario di partenza preferito. Puoi specificare l'ora come numero intero in secondi dalla mezzanotte del 1° gennaio 1970 UTC. Se viene specificato un valore departure_time successivo a 9999-12-31T23:59:59.999999999Z, l'API utilizzerà il valore di riserva departure_time 9999-12-31T23:59:59.999999999Z. In alternativa, puoi specificare un valore di now, che imposta l'ora di partenza sull'ora corrente (corretta al secondo più vicino). L'orario di partenza può essere specificato in due casi:

  • Per le richieste in cui la modalità di viaggio è il trasporto pubblico: puoi facoltativamente specificare departure_time o arrival_time. Se non viene specificato nessuno dei due orari, departure_time viene impostato per impostazione predefinita su ora (ovvero l'orario di partenza viene impostato per impostazione predefinita sull'ora corrente).
  • Per le richieste in cui la modalità di viaggio è in auto: puoi specificare departure_time per ricevere un percorso e una durata del viaggio (campo di risposta: duration_in_traffic) che tengono conto delle condizioni del traffico. Il valore departure_time deve essere impostato sull'ora corrente o su un'ora futura. Non può essere nel passato.
Nota: se l'orario di partenza non è specificato, la scelta del percorso e della durata si basa sulla rete stradale e sulle condizioni medie del traffico indipendenti dal tempo. I risultati di una determinata richiesta possono variare nel tempo a causa di modifiche alla rete stradale, condizioni del traffico medie aggiornate e natura distribuita del servizio. I risultati possono anche variare tra percorsi quasi equivalenti in qualsiasi momento o frequenza.
Nota: le richieste di Distance Matrix che specificano departure_time quando mode=driving sono limitate a un massimo di 100 elementi per richiesta. Il numero di origini moltiplicato per il numero di destinazioni definisce il numero di elementi.

language

La lingua in cui restituire i risultati. Tieni presente che questo vale solo per gli indirizzi geocodificati in start_address e end_address, il testo localizzato nei campi distance e duration (in tratti e passaggi) e la descrizione delle manovre in html_instructions, ma non per i nomi e gli indirizzi in html_instructions, che sono formattati nella lingua e nello script locali.

  • Consulta l'elenco delle lingue supportate. Google aggiorna spesso le lingue supportate, pertanto questo elenco potrebbe non essere esaustivo.
  • Se language non viene fornito, l'API tenta di utilizzare la lingua preferita specificata nell'intestazione Accept-Language.
  • L'API fa del suo meglio per fornire un indirizzo leggibile sia per l'utente sia per le persone del posto. Per raggiungere questo obiettivo, restituisce gli indirizzi nella lingua locale, traslitterati in un alfabeto leggibile dall'utente, se necessario, rispettando la lingua preferita. Tutti gli altri indirizzi vengono restituiti nella lingua preferita. I componenti dell'indirizzo vengono restituiti tutti nella stessa lingua, che viene scelta dal primo componente.
  • Se un nome non è disponibile nella lingua preferita, l'API utilizza la corrispondenza più vicina.
  • La lingua preferita ha una piccola influenza sull'insieme di risultati che l'API sceglie di restituire e sull'ordine in cui vengono restituiti. Il geocodificatore interpreta le abbreviazioni in modo diverso a seconda della lingua, ad esempio le abbreviazioni per i tipi di strade o i sinonimi che potrebbero essere validi in una lingua ma non in un'altra. Ad esempio, utca e tér sono sinonimi di strada in ungherese.

modalità

Per il calcolo di distanze e indicazioni stradali, puoi specificare la modalità di trasporto da utilizzare. Per impostazione predefinita, viene utilizzata la modalità driving. Per impostazione predefinita, le indicazioni stradali vengono calcolate come indicazioni per la guida. Sono supportate le seguenti modalità di viaggio:

  • driving (predefinito) indica le indicazioni stradali o la distanza standard utilizzando la rete stradale.
  • walking richiede indicazioni a piedi o distanza tramite percorsi pedonali e marciapiedi (se disponibili).
  • bicycling richiede indicazioni in bicicletta o la distanza tramite piste ciclabili e strade preferite (se disponibili).
  • transit richiede indicazioni stradali o distanza utilizzando i percorsi dei mezzi pubblici (se disponibili). Se imposti la modalità su mezzi pubblici, puoi facoltativamente specificare un departure_time o un arrival_time. Se non viene specificato nessuno dei due orari, departure_time viene impostato per impostazione predefinita su ora (ovvero l'orario di partenza viene impostato per impostazione predefinita sull'ora corrente). Se vuoi, puoi anche includere un transit_mode e/o un transit_routing_preference. Le corse con il trasporto pubblico sono disponibili per un massimo di 7 giorni nel passato o di 100 giorni nel futuro, in base alla disponibilità delle informazioni sul trasporto pubblico fornite dai fornitori di dati. Gli orari del trasporto pubblico cambiano di frequente, le corse disponibili possono variare nel tempo e non è garantito che i risultati delle previsioni con largo anticipo siano coerenti.
Nota: a volte le indicazioni stradali per gli spostamenti a piedi e in bicicletta potrebbero non includere percorsi pedonali o ciclabili chiari, pertanto queste indicazioni restituiranno avvisi nel risultato restituito che devi mostrare all'utente.

regione

Il codice regione, specificato come valore di due caratteri ccTLD ("dominio di primo livello"). La maggior parte dei codici ccTLD è identica ai codici ISO 3166-1, con alcune eccezioni degne di nota. Ad esempio, il ccTLD del Regno Unito è "uk" (.co.uk), mentre il suo codice ISO 3166-1 è"gb " (tecnicamente per l'entità "Regno Unito di Gran Bretagna e Irlanda del Nord").

traffic_model

Specifica le ipotesi da utilizzare per il calcolo del tempo nel traffico. Questa impostazione influisce sul valore restituito nel campo duration_in_traffic della risposta, che contiene il tempo previsto nel traffico in base alle medie storiche. Il parametro traffic_model può essere specificato solo per le indicazioni stradali in cui la richiesta include un departure_time. I valori disponibili per questo parametro sono:

  • best_guess (predefinito) indica che il valore duration_in_traffic restituito deve essere la migliore stima del tempo di percorrenza in base a ciò che è noto sulle condizioni del traffico storiche e in tempo reale. Il traffico in tempo reale diventa più importante quanto più departure_time è vicino al momento attuale.
  • pessimistic indica che il valore duration_in_traffic restituito dovrebbe essere superiore al tempo di percorrenza effettivo nella maggior parte dei giorni, anche se occasionalmente, in caso di condizioni del traffico particolarmente negative, potrebbe superare questo valore.
  • optimistic indica che il valore duration_in_traffic restituito deve essere inferiore al tempo di percorrenza effettivo nella maggior parte dei giorni, anche se occasionalmente, in condizioni di traffico particolarmente favorevoli, il tempo di percorrenza potrebbe essere inferiore a questo valore.

Il valore predefinito di best_guess fornirà le previsioni più utili per la stragrande maggioranza dei casi d'uso. È possibile che la previsione del tempo di percorrenza di best_guess sia inferiore a optimistic o, in alternativa, superiore a pessimistic, a causa del modo in cui il modello predittivo di best_guess integra le informazioni sul traffico in tempo reale.

transit_mode

Specifica una o più modalità di trasporto preferite. Questo parametro può essere specificato solo per le indicazioni per il trasporto pubblico. Il parametro supporta i seguenti argomenti:

  • bus indica che il percorso calcolato deve preferire il viaggio in autobus.
  • subway indica che il percorso calcolato deve preferire il viaggio in metropolitana.
  • train indica che il percorso calcolato deve preferire il viaggio in treno.
  • tram indica che il percorso calcolato deve preferire il viaggio in tram e metropolitana leggera.
  • rail indica che il percorso calcolato deve preferire il viaggio in treno, tram, metropolitana leggera e metropolitana. Equivale a transit_mode=train|tram|subway.

transit_routing_preference

Specifica le preferenze per i percorsi con il trasporto pubblico. Utilizzando questo parametro, puoi influenzare le opzioni restituite, anziché accettare il percorso migliore predefinito scelto dall'API. Questo parametro può essere specificato solo per le indicazioni per il trasporto pubblico. Il parametro supporta i seguenti argomenti:

  • less_walking indica che il percorso calcolato deve preferire tratti a piedi limitati.
  • fewer_transfers indica che il percorso calcolato deve preferire un numero limitato di cambi.

unità

Specifica il sistema di unità da utilizzare per la visualizzazione dei risultati.

I risultati delle indicazioni stradali contengono testo all'interno di campi di distanza che possono essere visualizzati dall'utente per indicare la distanza di un particolare "passaggio" del percorso. Per impostazione predefinita, questo testo utilizza il sistema di unità di misura del paese o della regione di origine.

Ad esempio, un percorso da "Chicago, IL" a "Toronto, ONT" mostrerà i risultati in miglia, mentre il percorso inverso mostrerà i risultati in chilometri. Puoi eseguire l'override di questo sistema di unità impostandone uno in modo esplicito all'interno del parametro units della richiesta, passando uno dei seguenti valori:

  • metric specifica l'utilizzo del sistema metrico decimale. Le distanze testuali vengono restituite in chilometri e metri.
  • imperial specifica l'utilizzo del sistema imperiale (inglese). Le distanze testuali vengono restituite in miglia e piedi.
Nota: questa impostazione del sistema di unità di misura influisce solo sul testo visualizzato nei campi della distanza. I campi relativi alla distanza contengono anche valori che sono sempre espressi in metri.

waypoint

Attenzione: le richieste che utilizzano più di 10 tappe (tra 11 e 25) o l'ottimizzazione delle tappe vengono fatturate a una tariffa più elevata. Scopri di più sulla fatturazione per i prodotti Google Maps Platform.

Specifica un array di località intermedie da includere lungo il percorso tra i punti di partenza e di destinazione come località di passaggio o di sosta. I waypoint modificano un percorso indirizzandolo attraverso le località specificate. L'API supporta i waypoint per le seguenti modalità di viaggio: guida, a piedi e in bicicletta, ma non per il trasporto pubblico. Puoi fornire una o più località separate dal carattere pipe (| o %7C), sotto forma di ID luogo, indirizzo o coordinate di latitudine/longitudine. Per impostazione predefinita, il servizio Directions calcola un percorso utilizzando i waypoint nell'ordine in cui vengono forniti. La precedenza per l'analisi del valore del waypoint è l'ID luogo, le coordinate di latitudine/longitudine e poi l'indirizzo.

  • Se passi un ID luogo, devi anteporre il prefisso place_id:. Puoi recuperare gli ID luogo dall'API Geocoding e dall'API Places (incluso Place Autocomplete). Per un esempio di utilizzo degli ID luogo di Place Autocomplete, consulta Place Autocomplete e Directions. Per saperne di più sugli ID luogo, consulta la panoramica degli ID luogo.
    Per maggiore efficienza e precisione, utilizza gli ID luogo, se possibile. Questi ID sono univocamente espliciti come una coppia di valori di latitudine/longitudine e offrono vantaggi di geocodifica per il routing, come punti di accesso e variabili di traffico. A differenza di un indirizzo, gli ID non richiedono al servizio di eseguire una ricerca o una richiesta intermedia per i dettagli dei luoghi, pertanto le prestazioni sono migliori.
  • Se passi le coordinate di latitudine/longitudine, i valori vengono inviati direttamente al server frontend per calcolare le indicazioni stradali senza geocodifica. I punti vengono posizionati sulle strade e potrebbero non fornire la precisione richiesta dalla tua app. Utilizza le coordinate quando hai la certezza che i valori specifichino effettivamente i punti di cui la tua app ha bisogno per il routing, indipendentemente da possibili punti di accesso o dettagli di geocodifica aggiuntivi. Assicurati che i valori di latitudine e longitudine siano separati da una virgola (%2C) e non da uno spazio (%20).
  • Se passi un indirizzo, il servizio Directions geocodifica la stringa e la converte in coordinate di latitudine/longitudine per calcolare le indicazioni stradali. Se il valore dell'indirizzo è ambiguo, potrebbe attivare una ricerca per distinguerlo da indirizzi simili. Ad esempio, "1st Street" potrebbe essere un valore completo o un valore parziale per "1st street NE" o "1st St SE". Questo risultato potrebbe essere diverso da quello restituito dall'API Geocoding. Puoi evitare possibili interpretazioni errate utilizzando gli ID luogo.
  • In alternativa, puoi fornire un insieme di punti codificati utilizzando l'algoritmo di polilinea codificata. Un set codificato è utile per un numero elevato di waypoint, perché l'URL è notevolmente più breve. Tutti i servizi web hanno un limite di URL di 16.384 caratteri.
    • Le polilinee codificate devono essere precedute dal prefisso enc: e seguite da due punti (:). Ad esempio: waypoints=enc:gfo}EtohhU:.
    • Puoi anche includere più polilinee codificate, separate dal carattere barra verticale (|). Ad esempio, waypoints=via:enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:| via:enc:udymA{~bxM:

Influenza i percorsi con tappe e waypoint di passaggio

Per ogni waypoint nella richiesta, la risposta alle indicazioni stradali aggiunge una voce all'array legs per fornire i dettagli delle tappe in quel tratto del percorso.

Se vuoi influenzare il percorso utilizzando i waypoint senza aggiungere una sosta, aggiungi il prefisso via: al waypoint. I waypoint con prefisso via: non aggiungono una voce all'array legs, ma indirizzano il percorso attraverso il waypoint.

Il seguente URL modifica la richiesta precedente in modo che il percorso venga instradato attraverso Lexington senza fermate: 

https://maps.googleapis.com/maps/api/directions/json?
origin=Boston,MA&destination=Concord,MA
&waypoints=Charlestown,MA|via:Lexington,MA

Il prefisso via: è più efficace quando si creano percorsi in risposta al trascinamento dei waypoint sulla mappa da parte dell'utente. In questo modo, l'utente può vedere l'aspetto del percorso finale in tempo reale e assicurarsi che i waypoint siano posizionati in luoghi accessibili all'API Directions.

Attenzione: l'utilizzo del prefisso via: per evitare le tappe genera indicazioni stradali che interpretano rigorosamente il waypoint. Questa interpretazione potrebbe comportare deviazioni significative lungo il percorso o ZERO_RESULTS nel codice di stato della risposta se l'API Directions non è in grado di creare indicazioni stradali attraverso quel punto.

Ottimizza i waypoint

Per impostazione predefinita, il servizio Directions calcola un percorso attraverso i waypoint forniti nell'ordine indicato. Se vuoi, puoi passare optimize:true come primo argomento all'interno del parametro waypoints per consentire al servizio Directions di ottimizzare il percorso fornito riorganizzando i waypoint in un ordine più efficiente. (Questa ottimizzazione è un'applicazione del problema del commesso viaggiatore). Il tempo di percorrenza è il fattore principale che viene ottimizzato, ma per decidere quale percorso è più efficiente possono essere presi in considerazione altri fattori, come la distanza, il numero di svolte e molti altri. Tutti i waypoint devono essere tappe intermedie affinché il servizio Directions possa ottimizzare il percorso.

Se indichi al servizio Directions di ottimizzare l'ordine dei waypoint, l'ordine verrà restituito nel campo waypoint_order all'interno dell'oggetto routes. Il campo waypoint_order restituisce valori basati su zero.

L'esempio seguente calcola un viaggio su strada da Adelaide, nell'Australia Meridionale, a ciascuna delle principali regioni vinicole dell'Australia Meridionale utilizzando l'ottimizzazione dei percorsi. 

https://maps.googleapis.com/maps/api/directions/json?
origin=Adelaide,SA&destination=Adelaide,SA
&waypoints=optimize:true|Barossa+Valley,SA|Clare,SA|Connawarra,SA|McLaren+Vale,SA

L'ispezione del percorso calcolato indicherà che il calcolo utilizza i waypoint nel seguente ordine: 

"waypoint_order": [ 3, 2, 0, 1 ]
Attenzione: le richieste che utilizzano l'ottimizzazione dei waypoint vengono fatturate a una tariffa più elevata. Scopri di più sulla fatturazione dei prodotti Google Maps Platform.

Passaggi successivi

Esempi di indicazioni stradali

Risposte di Directions