Ricevere indicazioni stradali tramite l'API Directions (legacy)

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 origini, destinazioni e tappe 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: per essere validi, gli URL devono essere codificati correttamente e sono limitati a 16.384 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 esegue la geocodifica della 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 anche una strada che porta 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 caratteri di escape dell'URL in %2B e gli spazi vengono convertiti in caratteri di escape dell'URL 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 i gradini interni 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 al 31/12/9999T23:59:59.999999999Z, l'API utilizzerà il valore di riserva departure_time 31/12/9999T23:59:59.999999999Z. In alternativa, puoi specificare il valore now, che imposta l'ora di partenza sull'ora corrente (con un'approssimazione 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 è la guida: 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 per 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 nella scrittura 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 valore 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). 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 dei trasporti pubblici cambiano di frequente, le corse disponibili potrebbero cambiare nel tempo e non è garantito che i risultati delle previsioni con largo anticipo siano coerenti.
  Nota: a volte le indicazioni in bicicletta e a piedi 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 alle informazioni note 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 in alcuni giorni con 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 giorni con condizioni del 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 mostrati all'utente per indicare la distanza di un determinato "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 esplicitamente 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: in auto, a piedi e in bicicletta, ma non con 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 una 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 del luogo, 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 necessari alla tua app 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 esegue la geocodifica della 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 disambiguare indirizzi simili. Ad esempio, "1st Street" potrebbe essere un valore completo o 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 per polilinee codificate. Un set codificato è utile per un numero elevato di waypoint, perché l'URL è notevolmente più breve. Tutti i servizi web hanno un limite di 16.384 caratteri per gli URL.
    • 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 punti di sosta e di passaggio

  Per ogni waypoint nella richiesta, la risposta delle 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 intermedie genera indicazioni stradali che interpretano il waypoint in modo rigoroso. 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

• Modalità di viaggio
• Informazioni sul traffico
• Waypoint e ottimizzazione dei waypoint
• Limitazioni dei percorsi
• Sistemi di unità
• Saturazione della regione
• Modificatori dei luoghi

Risposte di Directions

• DirectionsResponse
• DirectionsRoute
• DirectionsLeg
• DirectionsStep e DirectionsPolyline
• DirectionsTransitDetails
• DirectionsStatus
• DirectionsGeocodedWaypoint