Servizio indicazioni stradali

Nota: librerie lato server

In questa pagina viene descritto il servizio lato client disponibile con l'API Maps JavaScript. Se vuoi utilizzare i servizi web di Google Maps sul tuo server, consulta la pagina relativa al client Node.js per i servizi Google Maps. La pagina a questo link introduce anche il client Java, il client Python e il client Go per i servizi Google Maps.

Panoramica

Vedi anche il riferimento relativo all'API Maps JavaScript: Istruzioni

Puoi calcolare le indicazioni stradali (utilizzando una varietà di metodi di trasporto) utilizzando l'oggetto DirectionsService. Questo oggetto comunica con il servizio Directions dell'API di Google Maps, che riceve le richieste di indicazioni stradali e restituisce un percorso efficiente. Il tempo di viaggio è il fattore principale che viene ottimizzato, ma possono essere presi in considerazione altri fattori come la distanza, il numero di svolte e molto altro. Puoi gestire personalmente i risultati relativi alle indicazioni stradali o utilizzare l'oggetto DirectionsRenderer per visualizzarli.

Quando specifichi l'origine o la destinazione in una richiesta di indicazioni stradali, puoi specificare una stringa di query (ad esempio "Chicago, IL" o "Darwin, NSW, Australia"), un valore LatLng o un oggetto Place.

Il servizio Directions può restituire indicazioni in più parti utilizzando una serie di tappe. Le indicazioni stradali vengono mostrate come una polilinea che disegna il percorso su una mappa o anche come serie di descrizioni testuali all'interno di un elemento <div> (ad esempio, "Svolta a destra sulla rampa del Ponte Williamsburg").

Come iniziare

Prima di utilizzare il servizio Directions nell'API Maps JavaScript, assicurati che l'API Directions sia attivata nella console Google Cloud, nello stesso progetto che hai configurato per l'API Maps JavaScript.

Per visualizzare l'elenco delle API abilitate:

1. Vai alla console Google Cloud.
2. Fai clic sul pulsante Seleziona un progetto, quindi scegli lo stesso progetto che hai configurato per l'API Maps JavaScript e fai clic su Apri.
3. Nell'elenco delle API nella dashboard, cerca API Directions.
4. Se vedi l'API nell'elenco, non devi fare altro. Se l'API non è elencata, abilitala:
   1. Nella parte superiore della pagina, seleziona ABILITA API per visualizzare la scheda Raccolta. In alternativa, dal menu a sinistra, seleziona Raccolta.
   2. Cerca l'API Directions, quindi selezionala dall'elenco dei risultati.
   3. Seleziona ABILITA. Al termine della procedura, l'API Directions viene visualizzata nell'elenco delle API nella dashboard.

Prezzi e norme

Prezzi

A partire dal 16 luglio 2018 è stato applicato un nuovo piano di pagamento a consumo per Maps, Routes e Places. Per scoprire di più sui nuovi prezzi e sui limiti di utilizzo per il tuo servizio JavaScript Directions, consulta Utilizzo e fatturazione per l'API Directions.

Norme

L'utilizzo del servizio Directions deve essere conforme alle norme descritte per l'API Directions.

Richieste di indicazioni stradali

L'accesso al servizio Directions è asincrono, dato che l'API Google Maps deve effettuare una chiamata a un server esterno. Per questo motivo, devi passare un metodo di callback da eseguire al termine della richiesta. Questo metodo di callback dovrebbe elaborare i risultati. Tieni presente che il servizio Directions potrebbe restituire più di un itinerario possibile come array di routes[] separati.

Per utilizzare le indicazioni stradali nell'API Maps JavaScript, crea un oggetto di tipo DirectionsService e chiama DirectionsService.route() per avviare una richiesta al servizio Directions, trasmettendole un valore letterale di oggetto DirectionsRequest contenente i termini di input e un metodo di callback da eseguire al ricevimento della risposta.

Il valore letterale dell'oggetto DirectionsRequest contiene i seguenti campi:

{
  origin: LatLng | String | google.maps.Place,
  destination: LatLng | String | google.maps.Place,
  travelMode: TravelMode,
  transitOptions: TransitOptions,
  drivingOptions: DrivingOptions,
  unitSystem: UnitSystem,
  waypoints[]: DirectionsWaypoint,
  optimizeWaypoints: Boolean,
  provideRouteAlternatives: Boolean,
  avoidFerries: Boolean,
  avoidHighways: Boolean,
  avoidTolls: Boolean,
  region: String
}

Questi campi sono spiegati di seguito:

• origin (obbligatorio) specifica la posizione di partenza da cui calcolare le indicazioni stradali. Questo valore può essere specificato come String (ad esempio, "Chicago, IL"), come valore LatLng o come oggetto Place. Se utilizzi un oggetto Place, puoi specificare un ID luogo, una stringa di query o una posizione LatLng. Puoi recuperare gli ID luogo dai servizi Geocodifica, Ricerca luoghi e Completamento automatico dei luoghi nell'API Maps JavaScript. Per un esempio di utilizzo di ID posizione da Place Autocomplete, consultate la sezione Place Autocomplete and Directions.
• destination (obbligatorio) specifica la posizione di arrivo in cui calcolare le indicazioni stradali. Le opzioni sono le stesse del campo origin descritto sopra.
• travelMode (obbligatorio) specifica il mezzo di trasporto da utilizzare per il calcolo delle indicazioni stradali. I valori validi sono specificati in Modalità di viaggio di seguito.
• transitOptions (facoltativo) specifica i valori che si applicano solo alle richieste in cui travelMode è TRANSIT. I valori validi sono descritti di seguito in Opzioni di trasporto pubblico.
• drivingOptions (facoltativo) specifica i valori che si applicano solo alle richieste in cui travelMode è DRIVING. I valori validi sono descritti di seguito in Opzioni di guida.

• unitSystem (facoltativo) specifica il sistema di unità da utilizzare per la visualizzazione dei risultati. I valori validi sono specificati in Sistemi di unità di seguito.

• waypoints[] (facoltativo) specifica un array di DirectionsWaypoint. I tappe alterano un percorso indirizzandolo attraverso le località specificate. Un Waypoint è specificato come valore letterale di oggetto con i campi mostrati di seguito:

  • location specifica la posizione del tappeto, come un LatLng, come un oggetto Place o come String che sarà geocodificato.
  • stopover è un valore booleano che indica che il waypoint è una fermata sulla route, che ha l'effetto di dividerla in due route.

  Per ulteriori informazioni sui tappe, consulta la sezione Utilizzare i tappe nei percorsi di seguito.

• optimizeWaypoints (facoltativo) specifica che il percorso che utilizza il waypoints in dotazione potrebbe essere ottimizzato riorganizzando i tappe in un ordine più efficiente. Se true, il servizio Directions restituirà l'elemento waypoints riordinato in un campo waypoint_order. Per ulteriori informazioni, consulta la sezione Utilizzo dei Waypoint nelle route riportata di seguito.
• provideRouteAlternatives (facoltativo) se impostato su true specifica che il servizio Directions può fornire più di un'alternativa di percorso nella risposta. Tieni presente che l'invio di alternative per le route potrebbe aumentare il tempo di risposta dal server. Questa opzione è disponibile solo per le richieste senza tappe intermedie.
• avoidFerries (facoltativo) se impostato su true indica che i percorsi calcolati devono evitare i traghetti, se possibile.
• avoidHighways (facoltativo) se impostato su true indica che le route calcolate dovrebbero evitare le autostrade principali, se possibile.
• avoidTolls (facoltativo) se impostato su true indica che i percorsi calcolati devono evitare le strade a pedaggio, se possibile.
• region (facoltativo) specifica il codice di regione, specificato come valore ccTLD ("dominio di primo livello") a due caratteri. Per saperne di più, consulta la Differenziazione della regione di seguito.

Nota: il campo durationInTraffic è ora deprecato. In precedenza, era il metodo consigliato per i clienti del piano Premium di Google Maps Platform per specificare se il risultato doveva includere una durata che tiene conto delle condizioni di traffico attuali. Ora devi utilizzare il campo drivingOptions.

Di seguito è riportato un esempio DirectionsRequest:

{
  origin: 'Chicago, IL',
  destination: 'Los Angeles, CA',
  waypoints: [
    {
      location: 'Joplin, MO',
      stopover: false
    },{
      location: 'Oklahoma City, OK',
      stopover: true
    }],
  provideRouteAlternatives: false,
  travelMode: 'DRIVING',
  drivingOptions: {
    departureTime: new Date(/* now, or future date */),
    trafficModel: 'pessimistic'
  },
  unitSystem: google.maps.UnitSystem.IMPERIAL
}

Modalità di viaggio

Per calcolare le indicazioni stradali, devi specificare la modalità di trasporto da utilizzare. Al momento sono supportate le seguenti modalità di viaggio:

• DRIVING (valore predefinito) indica le indicazioni stradali standard tramite la rete stradale.
• BICYCLING richiede indicazioni stradali in bicicletta tramite piste ciclabili e strade preferite.
• TRANSIT richiede indicazioni stradali tramite percorsi dei trasporti pubblici.
• WALKING richiede indicazioni a piedi tramite percorsi pedonali e marciapiedi.

Consulta i Dettagli sulla copertura di Google Maps Platform per determinare in che misura un paese supporta le indicazioni stradali. Se richiedi indicazioni stradali per una regione in cui il tipo di direzione non è disponibile, la risposta restituirà il valore DirectionsStatus="ZERO_RESULTS.

Nota: le indicazioni a piedi potrebbero non includere percorsi pedonali chiari, quindi le indicazioni a piedi restituiranno avvisi nel DirectionsResult. Questi avvisi devono sempre essere mostrati all'utente. Se non utilizzi l'impostazione predefinita DirectionsRenderer, sei responsabile della visualizzazione degli avvisi.

Opzioni di trasporto pubblico

Le opzioni disponibili per una richiesta di indicazioni stradali variano a seconda della modalità di viaggio. Quando vengono richieste indicazioni stradali, le opzioni avoidHighways, avoidTolls, waypoints[] e optimizeWaypoints vengono ignorate. Puoi specificare opzioni di routing specifiche per il trasporto pubblico tramite il valore letterale oggetto TransitOptions.

Le indicazioni per il trasporto pubblico sono sensibili al tempo. Le indicazioni stradali verranno restituite solo per gli orari futuri.

Il valore letterale dell'oggetto TransitOptions contiene i seguenti campi:

{
  arrivalTime: Date,
  departureTime: Date,
  modes[]: TransitMode,
  routingPreference: TransitRoutePreference
}

Questi campi sono spiegati di seguito:

• arrivalTime (facoltativo) specifica l'orario di arrivo desiderato come oggetto Date. Se viene specificato l'ora di arrivo, l'orario di partenza viene ignorato.
• departureTime (facoltativo) specifica l'orario di partenza desiderato come oggetto Date. departureTime verrà ignorato se arrivalTime è specificato. Il valore predefinito è adesso (ovvero l'ora attuale) se non viene specificato alcun valore per departureTime o arrivalTime.
• modes[] (facoltativo) è un array contenente uno o più valori letterali degli oggetti TransitMode. Questo campo può essere incluso solo se la richiesta include una chiave API. Ogni TransitMode specifica una modalità di trasporto pubblico preferita. Sono consentiti i seguenti valori:
  • BUS indica che il percorso calcolato dovrebbe preferire la corsa in autobus.
  • RAIL indica che il percorso calcolato dovrebbe preferire il viaggio in treno, tram, metropolitana leggera e metropolitana.
  • SUBWAY indica che il percorso calcolato dovrebbe preferire la metropolitana.
  • TRAIN indica che il percorso calcolato dovrebbe preferire la corsa in treno.
  • TRAM indica che il percorso calcolato dovrebbe preferire il viaggio in tram e tram.
• routingPreference (facoltativo) specifica le preferenze per i percorsi con il trasporto pubblico. Utilizzando questa opzione, puoi provare le opzioni restituite, anziché accettare il percorso migliore predefinito scelto dall'API. Questo campo può essere specificato solo se la richiesta include una chiave API. Sono consentiti i seguenti valori:
  • FEWER_TRANSFERS indica che la route calcolata dovrebbe preferire un numero limitato di trasferimenti.
  • LESS_WALKING indica che il percorso calcolato dovrebbe preferire un numero limitato di tratti a piedi.

Di seguito è riportato un esempio di DirectionsRequest per il trasporto pubblico:

{
  origin: 'Hoboken NJ',
  destination: 'Carroll Gardens, Brooklyn',
  travelMode: 'TRANSIT',
  transitOptions: {
    departureTime: new Date(1337675679473),
    modes: ['BUS'],
    routingPreference: 'FEWER_TRANSFERS'
  },
  unitSystem: google.maps.UnitSystem.IMPERIAL
}

Opzioni di guida

Puoi specificare le opzioni di routing per le indicazioni stradali attraverso l'oggetto DrivingOptions.

L'oggetto DrivingOptions contiene i seguenti campi:

{
  departureTime: Date,
  trafficModel: TrafficModel
}

Questi campi sono spiegati di seguito:

• departureTime (obbligatorio affinché il valore letterale dell'oggetto drivingOptions sia valido) specifica l'orario di partenza desiderato come oggetto Date. Il valore deve essere impostato sull'ora attuale o su una data futura. Non può essere nel passato. L'API converte tutte le date in UTC per garantire una gestione coerente dei fusi orari. Per i clienti del piano Premium di Google Maps Platform, se includi departureTime nella richiesta, l'API restituisce il percorso migliore in base alle condizioni di traffico previste in quel momento e include il tempo previsto nel traffico (duration_in_traffic) nella risposta. Se non specifichi un orario di partenza (vale a dire, se la richiesta non include drivingOptions), il percorso restituito è in genere quello corretto e non tiene conto delle condizioni del traffico.
• trafficModel (facoltativo) specifica le ipotesi da utilizzare per calcolare il tempo di traffico. Questa impostazione influisce sul valore restituito nel campo duration_in_traffic della risposta, che contiene il tempo previsto nel traffico in base a medie storiche. Il valore predefinito è bestguess. Sono consentiti i seguenti valori:
  • bestguess (valore predefinito) indica che duration_in_traffic restituito deve corrispondere alla stima migliore del tempo di percorrenza in base a informazioni note sia sulle condizioni del traffico storico sia sul traffico in tempo reale. Il traffico in tempo reale è sempre più importante in prossimità di departureTime.
  • pessimistic indica che il valore duration_in_traffic restituito dovrebbe essere più lungo del tempo di viaggio effettivo nella maggior parte dei giorni, anche se i giorni occasionali con condizioni del traffico particolarmente negative possono superare questo valore.
  • optimistic indica che il valore restituito da duration_in_traffic dovrebbe essere inferiore al tempo di percorrenza effettivo nella maggior parte dei giorni, anche se i giorni occasionali con condizioni del traffico particolarmente positive potrebbero essere più rapidi di questo valore.

Nota:se l'orario di partenza non è specificato, la scelta del percorso e della durata si basa sulla rete stradale e sulle condizioni di traffico medie indipendenti dal tempo. I risultati di una determinata richiesta possono variare nel tempo a causa di cambiamenti nella rete stradale, di condizioni di traffico medie aggiornate e della natura distribuita del servizio. I risultati possono variare anche tra percorsi quasi equivalenti in qualsiasi momento o a seconda della frequenza.

Nota: per assicurarti che la tua richiesta utilizzi le informazioni sul traffico in tempo reale, imposta departureTime su ora. Le richieste che utilizzano informazioni sul traffico vengono fatturate a una tariffa superiore. Scopri di più su come vengono fatturati i prodotti Google Maps Platform.

Di seguito è riportato un esempio di DirectionsRequest per le indicazioni stradali:

{
  origin: 'Chicago, IL',
  destination: 'Los Angeles, CA',
  travelMode: 'DRIVING',
  drivingOptions: {
    departureTime: new Date(Date.now() + N),  // for the time N milliseconds from now.
    trafficModel: 'optimistic'
  }
}

Sistemi di unità di misura

Per impostazione predefinita, le indicazioni stradali vengono calcolate e visualizzate utilizzando il sistema di unità del paese o della regione di origine. (Nota: le origini espresse utilizzando le coordinate di latitudine/longitudine anziché gli indirizzi vengono sempre impostate su unità di misura). 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 sostituire questo sistema di unità impostandone uno esplicitamente nella richiesta utilizzando uno dei seguenti valori di UnitSystem:

• UnitSystem.METRIC specifica l'utilizzo del sistema di metriche. Le distanze vengono mostrate utilizzando i chilometri.
• UnitSystem.IMPERIAL specifica l'utilizzo del sistema imperiale (inglese). Le distanze vengono mostrate utilizzando le miglia.

Nota:questa impostazione del sistema dell'unità influisce solo sul testo mostrato all'utente. Il risultato delle indicazioni stradali contiene anche valori di distanza, non mostrati all'utente, che sono sempre espressi in metri.

Differenziazione della regione per le indicazioni stradali

Il servizio Directions dell'API di Google Maps restituisce i risultati dell'indirizzo influenzati dal dominio (regione o paese) da cui hai caricato il bootstrap JavaScript. Poiché la maggior parte degli utenti carica https://maps.googleapis.com/, questo imposta un dominio implicito sugli Stati Uniti. Se carichi il bootstrap da un dominio supportato diverso, i risultati saranno influenzati da quel dominio. Ad esempio, le ricerche di "San Francisco" potrebbero restituire risultati diversi dalle applicazioni che caricano https://maps.googleapis.com/ (Stati Uniti) rispetto a quelle che caricano http://maps.google.es/ (Spagna).

Puoi anche impostare il servizio Directions in modo che restituisca i risultati di parte di una determinata regione utilizzando il parametro region. Questo parametro accetta un codice di regione, specificato come sottotag Unicode di due caratteri (non numerico). Nella maggior parte dei casi, questi tag vengono mappati direttamente a ccTLD ("dominio di primo livello") con valori di due caratteri come "uk" in "co.uk" ad esempio. In alcuni casi, il tag region supporta anche i codici ISO-3166-1, che a volte differiscono dai valori ccTLD ("GB" per "Gran Bretagna".

Quando utilizzi il parametro region:

• Specifica un solo paese o una sola regione. Più valori vengono ignorati e ciò potrebbe comportare una richiesta non riuscita.
• Utilizza solo tag secondari a due caratteri per regione (formato CLDR Unicode). Tutti gli altri input comporteranno errori.

La differenziazione per regione è supportata solo per i paesi e le regioni che supportano le indicazioni stradali. Consulta i dettagli di copertura di Google Maps Platform per visualizzare la copertura internazionale dell'API Directions.

Istruzioni di rendering

L'avvio di una richiesta di indicazioni stradali a DirectionsService con il metodo route() richiede il trasferimento di un callback che venga eseguito al termine della richiesta di servizio. Questo callback restituirà un DirectionsResult e un codice DirectionsStatus nella risposta.

Stato della query sulle indicazioni stradali

DirectionsStatus potrebbe restituire i seguenti valori:

• OK indica che la risposta contiene un elemento DirectionsResult valido.
• NOT_FOUND indica che non è stato possibile geocodificare almeno una delle località specificate nell'origine, nella destinazione o nei tappe della richiesta.
• ZERO_RESULTS indica che non è stato trovato alcun percorso tra l'origine e la destinazione.
• MAX_WAYPOINTS_EXCEEDED indica che in DirectionsRequest sono stati forniti troppi campi DirectionsWaypoint. Consulta la sezione di seguito sui limiti per i punti Way.
• MAX_ROUTE_LENGTH_EXCEEDED indica che la route richiesta è troppo lunga e non può essere elaborata. Questo errore si verifica quando vengono restituite indicazioni più complesse. Prova a ridurre il numero di tappe, svolte o istruzioni.
• INVALID_REQUEST indica che DirectionsRequest fornito non era valido. Le cause più comuni di questo codice di errore sono le richieste prive di origine o destinazione o di una richiesta di transito che includa tappe.
• OVER_QUERY_LIMIT indica che la pagina web ha inviato troppe richieste nel periodo di tempo consentito.
• REQUEST_DENIED indica che la pagina web non può utilizzare il servizio di indicazioni stradali.
• UNKNOWN_ERROR indica che non è stato possibile elaborare una richiesta di indicazioni stradali a causa di un errore del server. Se provi di nuovo, la richiesta potrebbe avere esito positivo.

Devi assicurarti che la query sulle indicazioni restituisca risultati validi selezionando questo valore prima di elaborarlo.

Visualizzazione del risultato di Directions

DirectionsResult contiene il risultato della query delle indicazioni stradali, che puoi gestire tu stesso o passare a un oggetto DirectionsRenderer, che può gestire automaticamente la visualizzazione del risultato su una mappa.

Per visualizzare un DirectionsResult utilizzando un DirectionsRenderer, devi fare quanto segue:

1. Crea un oggetto DirectionsRenderer.
2. Richiama setMap() sul renderer per associarlo alla mappa passata.
3. Chiama setDirections() sul renderer, passandolo a DirectionsResult come indicato sopra. Poiché il renderer è un elemento MVCObject, rileva automaticamente eventuali modifiche alle proprietà e aggiorna la mappa quando le indicazioni stradali associate cambiano.

L'esempio seguente calcola le indicazioni stradali tra due località sulla Route 66, in cui l'origine e la destinazione sono impostate dai valori "start" e "end" specificati negli elenchi a discesa. L'elemento DirectionsRenderer gestisce la visualizzazione della polilinea tra le posizioni indicate e il posizionamento degli indicatori all'origine, alla destinazione e agli eventuali tappe, se applicabili.

function initMap() {
  var directionsService = new google.maps.DirectionsService();
  var directionsRenderer = new google.maps.DirectionsRenderer();
  var chicago = new google.maps.LatLng(41.850033, -87.6500523);
  var mapOptions = {
    zoom:7,
    center: chicago
  }
  var map = new google.maps.Map(document.getElementById('map'), mapOptions);
  directionsRenderer.setMap(map);
}

function calcRoute() {
  var start = document.getElementById('start').value;
  var end = document.getElementById('end').value;
  var request = {
    origin: start,
    destination: end,
    travelMode: 'DRIVING'
  };
  directionsService.route(request, function(result, status) {
    if (status == 'OK') {
      directionsRenderer.setDirections(result);
    }
  });
}

Nel corpo dell'HTML:

<div>
<strong>Start: </strong>
<select id="start" onchange="calcRoute();">
  <option value="chicago, il">Chicago</option>
  <option value="st louis, mo">St Louis</option>
  <option value="joplin, mo">Joplin, MO</option>
  <option value="oklahoma city, ok">Oklahoma City</option>
  <option value="amarillo, tx">Amarillo</option>
  <option value="gallup, nm">Gallup, NM</option>
  <option value="flagstaff, az">Flagstaff, AZ</option>
  <option value="winona, az">Winona</option>
  <option value="kingman, az">Kingman</option>
  <option value="barstow, ca">Barstow</option>
  <option value="san bernardino, ca">San Bernardino</option>
  <option value="los angeles, ca">Los Angeles</option>
</select>
<strong>End: </strong>
<select id="end" onchange="calcRoute();">
  <option value="chicago, il">Chicago</option>
  <option value="st louis, mo">St Louis</option>
  <option value="joplin, mo">Joplin, MO</option>
  <option value="oklahoma city, ok">Oklahoma City</option>
  <option value="amarillo, tx">Amarillo</option>
  <option value="gallup, nm">Gallup, NM</option>
  <option value="flagstaff, az">Flagstaff, AZ</option>
  <option value="winona, az">Winona</option>
  <option value="kingman, az">Kingman</option>
  <option value="barstow, ca">Barstow</option>
  <option value="san bernardino, ca">San Bernardino</option>
  <option value="los angeles, ca">Los Angeles</option>
</select>
</div>

Visualizza esempio

L'esempio seguente mostra le indicazioni stradali utilizzando diverse modalità di viaggio tra Haight-Ashbury e Ocean Beach a San Francisco, CA:

function initMap() {
  var directionsService = new google.maps.DirectionsService();
  var directionsRenderer = new google.maps.DirectionsRenderer();
  var haight = new google.maps.LatLng(37.7699298, -122.4469157);
  var oceanBeach = new google.maps.LatLng(37.7683909618184, -122.51089453697205);
  var mapOptions = {
    zoom: 14,
    center: haight
  }
  var map = new google.maps.Map(document.getElementById('map'), mapOptions);
  directionsRenderer.setMap(map);
}

function calcRoute() {
  var selectedMode = document.getElementById('mode').value;
  var request = {
      origin: haight,
      destination: oceanBeach,
      // Note that JavaScript allows us to access the constant
      // using square brackets and a string value as its
      // "property."
      travelMode: google.maps.TravelMode[selectedMode]
  };
  directionsService.route(request, function(response, status) {
    if (status == 'OK') {
      directionsRenderer.setDirections(response);
    }
  });
}

Nel corpo dell'HTML:

<div>
<strong>Mode of Travel: </strong>
<select id="mode" onchange="calcRoute();">
  <option value="DRIVING">Driving</option>
  <option value="WALKING">Walking</option>
  <option value="BICYCLING">Bicycling</option>
  <option value="TRANSIT">Transit</option>
</select>
</div>

Visualizza esempio

Un elemento DirectionsRenderer non solo gestisce la visualizzazione della polilinea e di eventuali indicatori associati, ma può anche gestire la visualizzazione testuale delle indicazioni stradali come una serie di passaggi. A tale scopo, chiama setPanel() sul tuo DirectionsRenderer, trasmettendolo al secondo <div> in cui visualizzare queste informazioni. In questo modo, inoltre, assicurati di mostrare le informazioni sul copyright appropriate e gli eventuali avvisi associati al risultato.

Le indicazioni testuali verranno fornite utilizzando l'impostazione della lingua preferita del browser o la lingua specificata durante il caricamento del codice JavaScript dell'API utilizzando il parametro language. Per maggiori informazioni, consulta la pagina Localizzazione. Nel caso delle indicazioni stradali, l'ora verrà visualizzata nel fuso orario in corrispondenza di quella fermata del trasporto pubblico.

L'esempio seguente è identico a quello mostrato sopra, ma include un riquadro <div> in cui visualizzare le indicazioni stradali:

function initMap() {
  var directionsService = new google.maps.DirectionsService();
  var directionsRenderer = new google.maps.DirectionsRenderer();
  var chicago = new google.maps.LatLng(41.850033, -87.6500523);
  var mapOptions = {
    zoom:7,
    center: chicago
  }
  var map = new google.maps.Map(document.getElementById('map'), mapOptions);
  directionsRenderer.setMap(map);
  directionsRenderer.setPanel(document.getElementById('directionsPanel'));
}

function calcRoute() {
  var start = document.getElementById('start').value;
  var end = document.getElementById('end').value;
  var request = {
    origin:start,
    destination:end,
    travelMode: 'DRIVING'
  };
  directionsService.route(request, function(response, status) {
    if (status == 'OK') {
      directionsRenderer.setDirections(response);
    }
  });
}

Nel corpo dell'HTML:

<div id="map" style="float:left;width:70%;height:100%"></div>
<div id="directionsPanel" style="float:right;width:30%;height:100%"></div>

Visualizza esempio

L'oggetto DirectionsResult

Quando invii una richiesta di indicazioni stradali a DirectionsService, ricevi una risposta composta da un codice di stato e un risultato, ovvero un oggetto DirectionsResult. DirectionsResult è un valore letterale di oggetto con i seguenti campi:

• geocoded_waypoints[] contiene un array di oggetti DirectionsGeocodedWaypoint, ciascuno contenente i dettagli sulla geocodifica di origine, destinazione e tappe.
• routes[] contiene un array di oggetti DirectionsRoute. Ogni route indica un modo per andare dall'origine alla destinazione fornita in DirectionsRequest. In genere, per una determinata richiesta viene restituito un solo percorso, a meno che il campo provideRouteAlternatives della richiesta non sia impostato su true, in cui possono essere restituiti più percorsi.

Nota: la proprietà via_waypoint è ritirata in route alternative. La versione 3.27 è l'ultima versione dell'API che aggiunge ulteriori punti di via in percorsi alternativi. Per le versioni 3.28 e successive dell'API, puoi continuare a implementare indicazioni trascinabili utilizzando il servizio Directions disattivando il trascinamento delle route alternative. Deve essere trascinabile solo il percorso principale. Gli utenti possono trascinare il percorso principale finché non corrisponde a un percorso alternativo.

Waypoint geocodificati per indicazioni stradali

Un DirectionsGeocodedWaypoint contiene dettagli sulla geocodifica di origine, destinazione e tappe.

DirectionsGeocodedWaypoint è un valore letterale di oggetto con i seguenti campi:

• geocoder_status indica il codice di stato risultante dall'operazione di geocodifica. Questo campo può contenere i seguenti valori.
  • "OK" indica che non si sono verificati errori; l'indirizzo è stato analizzato correttamente e è stato restituito almeno un codice geografico.
  • "ZERO_RESULTS" indica che il codice geografico è riuscito, ma non ha restituito risultati. Questo può succedere se il geocodificatore ha trasmesso un address inesistente.

• partial_match indica che il geocodificatore non ha restituito una corrispondenza esatta per la richiesta originale, anche se è riuscita a trovare una corrispondenza con una parte dell'indirizzo richiesto. Ti consigliamo di esaminare la richiesta originale per individuare errori di ortografia e/o un indirizzo incompleto.

  Nella maggior parte dei casi, le corrispondenze parziali si verificano per gli indirizzi stradali che non esistono nella località trasmessa nella richiesta. Le corrispondenze parziali possono anche essere restituite quando una richiesta corrisponde a due o più sedi nella stessa località. Ad esempio, "Hillpar St, Bristol, UK" restituirà una corrispondenza parziale sia per Henry Street che per Henrietta Street. Tieni presente che se una richiesta include un componente dell'indirizzo con errori ortografici, il servizio di geocodifica potrebbe suggerire un indirizzo alternativo. Anche i suggerimenti attivati in questo modo verranno contrassegnati come corrispondenze parziali.

• place_id è un identificatore univoco di un luogo, che può essere utilizzato con altre API di Google. Ad esempio, potete utilizzare la place_id con la libreria API di Google Places per ottenere dettagli su un'attività locale, come numero di telefono, orari di apertura, recensioni degli utenti e altro ancora. Consulta la panoramica dell'ID luogo.
• types[] è un array che indica il tipo del risultato restituito. Questo array contiene un insieme di zero o più tag che identificano il tipo di funzionalità restituita nel risultato. Ad esempio, un codice geografico di "Chicago" restituisce "Località" che indica che "Chicago" è una città e restituisce anche "politica" che indica un'entità politica.

Indicazioni stradali

Nota: l'oggetto legacy DirectionsTrip è stato rinominato DirectionsRoute. Tieni presente che ora un percorso si riferisce all'intero percorso dall'inizio alla fine, invece che a una semplice tratta di un percorso padre.

DirectionsRoute contiene un singolo risultato dall'origine e dalla destinazione specificate. Questo percorso può essere composto da una o più vie (di tipo DirectionsLeg) a seconda che siano stati specificati dei tappe. Inoltre, il percorso contiene informazioni sul copyright e sugli avvisi che devono essere mostrate all'utente oltre alle informazioni di routing.

DirectionsRoute è un valore letterale di oggetto con i seguenti campi:

• legs[] contiene un array di oggetti DirectionsLeg, ognuno dei quali contiene informazioni su una tratta della route, da due posizioni all'interno della route specificata. Sarà presente una gamba separata per ogni tappa o destinazione specificata. (Una route senza punti di via conterrà esattamente un DirectionsLeg). Ogni tratto è costituito da una serie di DirectionStep.
• waypoint_order contiene un array che indica l'ordine dei punti di arrivo nella route calcolata. Questo array potrebbe contenere un ordine modificato se DirectionsRequest è stato passato a optimizeWaypoints: true.
• overview_path contiene un array di LatLng che rappresentano un percorso approssimativo (attenuato) delle indicazioni stradali risultanti.
• overview_polyline contiene un singolo oggetto points che contiene una rappresentazione di polilinea codificata della route. Questa polilinea è un percorso approssimato (liscio) delle indicazioni stradali risultanti.
• bounds contiene un LatLngBounds che indica i limiti della polilinea lungo questo percorso.
• copyrights contiene il testo del copyright da visualizzare per questa route.
  Nota: se non utilizzi l'oggetto DirectionsRenderer fornito, devi gestire e visualizzare personalmente queste informazioni.
• warnings[] contiene un array di avvisi da visualizzare quando vengono mostrate queste indicazioni stradali. Se non utilizzi l'oggetto DirectionsRenderer fornito, devi gestire e visualizzare personalmente questi avvisi.
• fare contiene la tariffa totale (ovvero il costo totale del biglietto) per questo itinerario. Questa proprietà viene restituita solo per le richieste di trasporto pubblico e solo per i percorsi in cui sono disponibili informazioni sulle tariffe per tutte le corse dei trasporti pubblici. Le informazioni includono:
  • currency: un codice valuta ISO 4217 che indica la valuta in cui è espresso l'importo.
  • value: importo totale della tariffa, indicato nella valuta sopra indicata.

Indicazioni per le gambe

Nota: l'oggetto legacy DirectionsRoute è stato rinominato DirectionsLeg.

Un DirectionsLeg definisce una singola tratta di un viaggio dall'origine alla destinazione nella route calcolata. Per i percorsi che non contengono tappe, il percorso sarà costituito da un'unica "linea", ma per i percorsi che definiscono uno o più tappe, la tratta sarà composta da una o più rotte, corrispondenti alle tappe specifiche del percorso.

DirectionsLeg è un valore letterale di oggetto con i seguenti campi:

• steps[] contiene una matrice di oggetti DirectionsStep che indicano le informazioni su ogni passaggio separato della tratta.

• distance indica la distanza totale percorsa da questa gamba, come oggetto Distance nel seguente modulo:

  • value indica la distanza in metri
  • text contiene una rappresentazione stringa della distanza, che per impostazione predefinita viene visualizzata nelle unità utilizzate all'origine. Ad esempio, le miglia verranno utilizzate per qualsiasi origine all'interno degli Stati Uniti. Puoi eseguire l'override di questo sistema di unità impostando specificatamente un UnitSystem nella query originale. Tieni presente che, indipendentemente dal sistema di unità utilizzato, il campo distance.value contiene sempre un valore espresso in metri.

  Questi campi potrebbero non essere definiti se la distanza è sconosciuta.

• duration indica la durata totale di questa gamba, come un oggetto Duration nel seguente formato:

  • value indica la durata in secondi.
  • text contiene una rappresentazione stringa della durata.

  Questi campi potrebbero non essere definiti se la durata è sconosciuta.

• duration_in_traffic indica la durata totale di questa tratta, tenendo conto delle attuali condizioni di traffico. duration_in_traffic viene restituito solo se tutte le seguenti condizioni sono vere:

  • La richiesta non include i tappe. Vale a dire che non include i tappe in cui stopover è true.
  • La richiesta è specifica per le indicazioni stradali: il mode è impostato su driving.
  • departureTime è incluso nel campo drivingOptions della richiesta.
  • Sono disponibili condizioni del traffico per il percorso richiesto.

  duration_in_traffic contiene i seguenti campi:

  • value indica la durata in secondi.
  • text contiene una rappresentazione leggibile della durata.
• arrival_time contiene l'orario di arrivo previsto per questa tratta. Questa proprietà viene restituita solo per le indicazioni di trasporto pubblico. Il risultato viene restituito come un oggetto Time con tre proprietà:
  • value la data e l'ora specificate come oggetto Date JavaScript.
  • text il tempo specificato come stringa. L'ora viene visualizzata nel fuso orario della fermata del trasporto pubblico.
  • time_zone contiene il fuso orario di questa stazione. Il valore è il nome del fuso orario definito nel database dei fusi orari IANA, ad esempio "America/New_York".
• departure_time contiene l'orario di partenza stimato per questa gamba, specificato come oggetto Time. departure_time è disponibile solo per le indicazioni stradali del trasporto pubblico.
• start_location contiene il LatLng dell'origine di questa gamba. Poiché il servizio web Directions calcola le indicazioni stradali tra le località utilizzando l'opzione di trasporto più vicina (di solito una strada) nei punti di partenza e di arrivo, start_location potrebbe essere diverso dall'origine fornita di questo tratto se, ad esempio, una strada non si trova vicino all'origine.
• end_location contiene il LatLng della destinazione di questa gamba. Poiché DirectionsService calcola le indicazioni stradali tra le località utilizzando l'opzione di trasporto più vicina (di solito una strada) nei punti di partenza e di arrivo, end_location potrebbe essere diverso dalla destinazione fornita per questa gamba se, ad esempio, una strada non si trova vicino alla destinazione.
• start_address contiene l'indirizzo leggibile (generalmente una via) all'inizio di questa gamba.
  
  Questi contenuti devono essere letti così come sono. Non analizzare l'indirizzo formattato in modo programmatico.
• end_address contiene l'indirizzo leggibile (in genere un indirizzo stradale) alla fine di questa gamba.
  
  Questi contenuti devono essere letti così come sono. Non analizzare l'indirizzo formattato in modo programmatico.

Indicazioni stradali

Un elemento DirectionsStep è l'unità più atomica del percorso di una direzione, contenente un singolo passaggio che descrive una singola istruzione di viaggio specifica. Ad esempio, "Svolta a W. 4th Street" Il passaggio non solo descrive le istruzioni, ma contiene anche le informazioni su distanza e durata relative al modo in cui è correlato. Ad esempio, un passaggio indicato come "Unisciti alla I-80 West" può contenere una durata di "37 miglia" e "40 minuti", che indica che il prossimo passaggio è a 40 minuti/40 minuti da questo passaggio.

Quando utilizzi il servizio Indicazioni stradali per cercare indicazioni stradali con il trasporto pubblico, l'array di passi includerà informazioni specifiche sul trasporto pubblico sotto forma di oggetto transit. Se le indicazioni stradali includono più modalità di trasporto, verranno fornite indicazioni dettagliate per raggiungere la destinazione a piedi o in auto in una matrice steps[]. Ad esempio, un passaggio a piedi includerà le indicazioni stradali dalle posizioni di inizio e fine: "Cammina fino a Innes Ave & Fitch St". Il passaggio includerà le indicazioni a piedi dettagliate per quel percorso nell'array di steps[], ad esempio: "Procedi a nord-ovest", "Svolta a sinistra su Arelious Walker" e "Svolta a sinistra su Innes Ave".

DirectionsStep è un valore letterale di oggetto con i seguenti campi:

• instructions contiene le istruzioni per questo passaggio all'interno di una stringa di testo.
• distance contiene la distanza percorsa da questo passaggio fino al passaggio successivo, come oggetto Distance. (Vedi la descrizione in DirectionsLeg qui sopra.) Questo campo potrebbe essere indefinito se la distanza è sconosciuta.
• duration contiene una stima del tempo necessario per eseguire il passaggio, fino al passaggio successivo, come oggetto Duration. (Vedi la descrizione in DirectionsLeg sopra). Questo campo potrebbe essere indefinito se la durata è sconosciuta.
• start_location contiene il LatLng geocodificato del punto di partenza di questo passaggio.
• end_location contiene il punto LatLng del punto finale di questo passaggio.
• polyline contiene un singolo oggetto points che contiene una rappresentazione della polilinea codificata del passaggio. Questa polilinea è un percorso approssimativo (liscio) del passaggio.
• steps[] un valore letterale di un oggetto DirectionsStep che contiene indicazioni dettagliate per i percorsi a piedi o in auto nelle indicazioni sul trasporto pubblico. I passaggi secondari sono disponibili solo per le indicazioni stradali per il trasporto pubblico.
• travel_mode contiene TravelMode utilizzato in questo passaggio. Le indicazioni per il trasporto pubblico possono includere una combinazione di indicazioni a piedi e di trasporto pubblico.
• path contiene un array di LatLngs che descrive il corso di questo passaggio.
• transit contiene informazioni specifiche sul trasporto pubblico, come l'orario di arrivo e di partenza e il nome della linea di trasporto pubblico.

Informazioni specifiche sul trasporto pubblico

Le indicazioni stradali relative al trasporto pubblico restituiscono informazioni aggiuntive non pertinenti ad altri mezzi di trasporto. Queste proprietà aggiuntive sono esposte tramite l'oggetto TransitDetails, restituito come proprietà di DirectionsStep. Dall'oggetto TransitDetails puoi accedere a informazioni aggiuntive per gli oggetti TransitStop, TransitLine, TransitAgency e VehicleType come descritto di seguito.

Dettagli trasporto pubblico

L'oggetto TransitDetails espone le seguenti proprietà:

• arrival_stop contiene un oggetto TransitStop che rappresenta la stazione di arrivo/fermata con le seguenti proprietà:
  • name il nome della fermata/della stazione di transito. Ad esempio: "Quadrato Unione".
  • location la posizione della stazione di transito/fermata, rappresentata come un LatLng.
• departure_stop contiene un oggetto TransitStop che rappresenta la stazione di partenza/arresto.
• arrival_time contiene l'ora di arrivo, specificata come un oggetto Time con tre proprietà:
  • value la data e l'ora specificate come oggetto Date JavaScript.
  • text il tempo specificato come stringa. L'ora viene visualizzata nel fuso orario della fermata del trasporto pubblico.
  • time_zone contiene il fuso orario di questa stazione. Il valore è il nome del fuso orario definito nel database dei fusi orari IANA, ad esempio "America/New_York".
• departure_time contiene l'orario di partenza, specificato come oggetto Time.
• headsign specifica la direzione in cui percorrere su questa linea, come è indicato sul veicolo o alla fermata di partenza. Spesso sarà la stazione del capolinea.
• headway quando disponibile, specifica il numero di secondi previsto tra le partenze dalla stessa fermata in questo momento. Ad esempio, con un valore headway di 600, se ti sfugge il tuo autobus, potresti aspettarti dieci minuti di attesa.
• line contiene un valore letterale di oggetto TransitLine contenente le informazioni sulla linea di trasporto pubblico utilizzata in questo passaggio. TransitLine fornisce il nome e l'operatore della riga, insieme ad altre proprietà descritte nella documentazione di riferimento di TransitLine.
• num_stops contiene il numero di scali in questo passaggio. Include la fermata di arrivo, ma non la fermata di partenza. Ad esempio, se le indicazioni stradali prevedono di partire dalla fermata A, passando per le fermate B e C e fino alla fermata D, num_stops restituirà 3.

Linea di trasporto pubblico

L'oggetto TransitLine espone le seguenti proprietà:

• name contiene il nome completo di questa linea di trasporto pubblico, ad esempio "Via Roma 12" o "Corso Italia 14".
• short_name contiene il nome breve di questa linea di trasporto pubblico. In genere è un numero di riga, ad esempio "2" o "M14".
• agencies è un array contenente un singolo oggetto TransitAgency. L'oggetto TransitAgency fornisce informazioni sull'operatore di questa riga, incluse le seguenti proprietà:
  • name contiene il nome dell'azienda di trasporto pubblico.
  • phone contiene il numero di telefono dell'azienda di trasporto pubblico.
  • url contiene l'URL dell'azienda di trasporto pubblico.

  Nota: se esegui manualmente il rendering delle indicazioni stradali per il trasporto pubblico anziché utilizzare l'oggetto DirectionsRenderer, devi visualizzare i nomi e gli URL delle aziende di trasporto pubblico che gestiscono i risultati della corsa.

• url contiene un URL per questa linea di trasporto pubblico fornito dall'azienda di trasporto pubblico.
• icon contiene un URL dell'icona associata a questa riga. La maggior parte delle città utilizzerà icone generiche che variano in base al tipo di veicolo. Alcune linee di trasporto pubblico, come la metropolitana di New York, presentano icone specifiche.
• color contiene il colore di uso comune nella segnaletica per questo trasporto pubblico. Il colore verrà specificato come stringa esagonale, ad esempio: #FF0033.
• text_color contiene il colore di testo comunemente utilizzato per la segnaletica di questa riga. Il colore verrà specificato come stringa esadecimale.
• vehicle contiene un oggetto Vehicle che include le seguenti proprietà:
  • name contiene il nome del veicolo su questa linea. Ad esempio: "Subway"
  • type contiene il tipo di veicolo utilizzato su questa linea. Consulta la documentazione Tipo di veicolo per un elenco completo dei valori supportati.
  • icon contiene un URL per l'icona comunemente associata a questo tipo di veicolo.
  • local_icon contiene l'URL dell'icona associata a questo tipo di veicolo, in base alla segnaletica del trasporto pubblico locale.

Tipo di veicolo

L'oggetto VehicleType espone le seguenti proprietà:

Valore	Definizione
VehicleType.RAIL	Ferrovia.
VehicleType.METRO_RAIL	Metropolitana leggera.
VehicleType.SUBWAY	Metropolitana leggera sotterranea.
VehicleType.TRAM	Metropolitana leggera fuori terra.
VehicleType.MONORAIL	Monorotaia.
VehicleType.HEAVY_RAIL	Ferrovia pesante.
VehicleType.COMMUTER_TRAIN	Ferrovia suburbana.
VehicleType.HIGH_SPEED_TRAIN	Treno ad alta velocità.
VehicleType.BUS	Autobus.
VehicleType.INTERCITY_BUS	Autobus interurbano.
VehicleType.TROLLEYBUS	Tram.
VehicleType.SHARE_TAXI	Il taxi condiviso è una tipologia di autobus con la possibilità di scendere e prendere passeggeri ovunque lungo il percorso.
VehicleType.FERRY	Traghetto.
VehicleType.CABLE_CAR	Un veicolo che funziona su un cavo, solitamente a terra. Le funivie aeree possono essere del tipo VehicleType.GONDOLA_LIFT.
VehicleType.GONDOLA_LIFT	Una funivia.
VehicleType.FUNICULAR	Un veicolo che sale su una pendenza. In genere, una funicolare è costituita da due carrozze, ciascuna delle quali funge da contrappeso per l'altra.
VehicleType.OTHER	Tutti gli altri veicoli restituiranno questo tipo.

Ispezione DirectionsResults

I componenti DirectionsResults (DirectionsRoute, DirectionsLeg, DirectionsStep e TransitDetails) possono essere ispezionati e utilizzati durante l'analisi di qualsiasi risposta delle indicazioni stradali.

Importante: se esegui manualmente il rendering delle indicazioni di trasporto pubblico invece di utilizzare l'oggetto DirectionsRenderer, devi visualizzare i nomi e gli URL delle aziende di trasporto pubblico che gestiscono i risultati della corsa.

L'esempio seguente mostra le indicazioni a piedi per determinate attrazioni turistiche di New York. Esaminiamo DirectionsStep del percorso per aggiungere indicatori per ogni passaggio e alleghiamo informazioni a un InfoWindow con testo didattico per quel passaggio.

Nota: dal momento che stiamo calcolando le indicazioni a piedi, mostriamo anche eventuali avvisi all'utente in un riquadro <div> separato.

var map;
var directionsRenderer;
var directionsService;
var stepDisplay;
var markerArray = [];

function initMap() {
  // Instantiate a directions service.
  directionsService = new google.maps.DirectionsService();

  // Create a map and center it on Manhattan.
  var manhattan = new google.maps.LatLng(40.7711329, -73.9741874);
  var mapOptions = {
    zoom: 13,
    center: manhattan
  }
  map = new google.maps.Map(document.getElementById('map'), mapOptions);

  // Create a renderer for directions and bind it to the map.
  var rendererOptions = {
    map: map
  }
  directionsRenderer = new google.maps.DirectionsRenderer(rendererOptions)

  // Instantiate an info window to hold step text.
  stepDisplay = new google.maps.InfoWindow();
}

function calcRoute() {

  // First, clear out any existing markerArray
  // from previous calculations.
  for (i = 0; i < markerArray.length; i++) {
    markerArray[i].setMap(null);
  }

  // Retrieve the start and end locations and create
  // a DirectionsRequest using WALKING directions.
  var start = document.getElementById('start').value;
  var end = document.getElementById('end').value;
  var request = {
      origin: start,
      destination: end,
      travelMode: 'WALKING'
  };

  // Route the directions and pass the response to a
  // function to create markers for each step.
  directionsService.route(request, function(response, status) {
    if (status == "OK") {
      var warnings = document.getElementById("warnings_panel");
      warnings.innerHTML = "" + response.routes[0].warnings + "";
      directionsRenderer.setDirections(response);
      showSteps(response);
    }
  });
}

function showSteps(directionResult) {
  // For each step, place a marker, and add the text to the marker's
  // info window. Also attach the marker to an array so we
  // can keep track of it and remove it when calculating new
  // routes.
  var myRoute = directionResult.routes[0].legs[0];

  for (var i = 0; i < myRoute.steps.length; i++) {
      var marker = new google.maps.Marker({
        position: myRoute.steps[i].start_point,
        map: map
      });
      attachInstructionText(marker, myRoute.steps[i].instructions);
      markerArray[i] = marker;
  }
}

function attachInstructionText(marker, text) {
  google.maps.event.addListener(marker, 'click', function() {
    stepDisplay.setContent(text);
    stepDisplay.open(map, marker);
  });
}

Nel corpo dell'HTML:

<div>
<strong>Start: </strong>
<select id="start">
  <option value="penn station, new york, ny">Penn Station</option>
  <option value="grand central station, new york, ny">Grand Central Station</option>
  <option value="625 8th Avenue New York NY 10018">Port Authority Bus Terminal</option>
  <option value="staten island ferry terminal, new york, ny">Staten Island Ferry Terminal</option>
  <option value="101 E 125th Street, New York, NY">Harlem - 125th St Station</option>
</select>
<strong>End: </strong>
<select id="end" onchange="calcRoute();">
  <option value="260 Broadway New York NY 10007">City Hall</option>
  <option value="W 49th St & 5th Ave, New York, NY 10020">Rockefeller Center</option>
  <option value="moma, New York, NY">MOMA</option>
  <option value="350 5th Ave, New York, NY, 10118">Empire State Building</option>
  <option value="253 West 125th Street, New York, NY">Apollo Theatre</option>
  <option value="1 Wall St, New York, NY">Wall St</option>
</select>
<div>

Visualizza esempio

Utilizzo di tappe nei percorsi

Attenzione: le richieste che utilizzano più di 10 tappe, o l'ottimizzazione di questi ultimi, vengono fatturate a una tariffa superiore. Scopri di più su come vengono fatturati i prodotti Google Maps Platform.

Come indicato nell'ambito di DirectionsRequest, potete anche specificare i waypoint (di tipo DirectionsWaypoint) quando calcolite i percorsi per le indicazioni stradali a piedi, in bicicletta o in auto tramite il servizio Directions. I Waypoint non sono disponibili per le indicazioni stradali del trasporto pubblico. I tappe consentono di calcolare le rotte attraverso ulteriori posizioni, nel qual caso la rotta restituita passa attraverso le tappe indicate.

Un waypoint è costituito dai seguenti campi:

• location (obbligatorio) specifica l'indirizzo del tappeto.
• stopover (facoltativo) indica se questo Waypoint è una fermata effettiva sul percorso (true) o solo una preferenza per il percorso attraverso la posizione indicata (false). Gli scali sono true per impostazione predefinita.

Attenzione: se imposti stopover su false per evitare soste, le indicazioni devono essere molto rigide nella loro interpretazione della tappa. Questo può causare gravi deviazioni sul percorso o su ZERO_RESULTS nel codice di stato della risposta se il servizio Directions non è in grado di creare indicazioni stradali per quel punto.

Per impostazione predefinita, il servizio Directions calcola un percorso attraverso i tappe forniti nell'ordine indicato. Facoltativamente, puoi passare optimizeWaypoints: true all'interno di DirectionsRequest per consentire al servizio Directions di ottimizzare il percorso fornito riordinando i tappe in modo più efficiente. Questa ottimizzazione è un'applicazione del problema di un venditore che viaggia. Il tempo di viaggio è il fattore principale che viene ottimizzato, ma possono essere presi in considerazione altri fattori, come la distanza, il numero di svolte e molto altro ancora, nel decidere quale percorso è il più efficiente. Tutti i tappe devono essere fermate per consentire al servizio Directions di ottimizzare il percorso.

Se indichi al servizio Directions di ottimizzare l'ordine dei tappe, il suo ordine verrà restituito nel campo waypoint_order all'interno dell'oggetto DirectionsResult.

L'esempio seguente calcola i percorsi per vari paesi degli Stati Uniti utilizzando una serie di punti di partenza, punti di arrivo e tappe. Per selezionare più tappe, premi Ctrl + clic quando selezioni gli elementi nell'elenco. Tieni presente che esaminiamo routes.start_address e routes.end_address per fornirci il testo per i punti di inizio e di fine di ogni percorso.

TypeScript

function initMap(): void {
  const directionsService = new google.maps.DirectionsService();
  const directionsRenderer = new google.maps.DirectionsRenderer();
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 6,
      center: { lat: 41.85, lng: -87.65 },
    }
  );

  directionsRenderer.setMap(map);

  (document.getElementById("submit") as HTMLElement).addEventListener(
    "click",
    () => {
      calculateAndDisplayRoute(directionsService, directionsRenderer);
    }
  );
}

function calculateAndDisplayRoute(
  directionsService: google.maps.DirectionsService,
  directionsRenderer: google.maps.DirectionsRenderer
) {
  const waypts: google.maps.DirectionsWaypoint[] = [];
  const checkboxArray = document.getElementById(
    "waypoints"
  ) as HTMLSelectElement;

  for (let i = 0; i < checkboxArray.length; i++) {
    if (checkboxArray.options[i].selected) {
      waypts.push({
        location: (checkboxArray[i] as HTMLOptionElement).value,
        stopover: true,
      });
    }
  }

  directionsService
    .route({
      origin: (document.getElementById("start") as HTMLInputElement).value,
      destination: (document.getElementById("end") as HTMLInputElement).value,
      waypoints: waypts,
      optimizeWaypoints: true,
      travelMode: google.maps.TravelMode.DRIVING,
    })
    .then((response) => {
      directionsRenderer.setDirections(response);

      const route = response.routes[0];
      const summaryPanel = document.getElementById(
        "directions-panel"
      ) as HTMLElement;

      summaryPanel.innerHTML = "";

      // For each route, display summary information.
      for (let i = 0; i < route.legs.length; i++) {
        const routeSegment = i + 1;

        summaryPanel.innerHTML +=
          "<b>Route Segment: " + routeSegment + "</b><br>";
        summaryPanel.innerHTML += route.legs[i].start_address + " to ";
        summaryPanel.innerHTML += route.legs[i].end_address + "<br>";
        summaryPanel.innerHTML += route.legs[i].distance!.text + "<br><br>";
      }
    })
    .catch((e) => window.alert("Directions request failed due to " + status));
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

Nota: leggi la guida sull'utilizzo di TypeScript e Google Maps.

JavaScript

function initMap() {
  const directionsService = new google.maps.DirectionsService();
  const directionsRenderer = new google.maps.DirectionsRenderer();
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 6,
    center: { lat: 41.85, lng: -87.65 },
  });

  directionsRenderer.setMap(map);
  document.getElementById("submit").addEventListener("click", () => {
    calculateAndDisplayRoute(directionsService, directionsRenderer);
  });
}

function calculateAndDisplayRoute(directionsService, directionsRenderer) {
  const waypts = [];
  const checkboxArray = document.getElementById("waypoints");

  for (let i = 0; i < checkboxArray.length; i++) {
    if (checkboxArray.options[i].selected) {
      waypts.push({
        location: checkboxArray[i].value,
        stopover: true,
      });
    }
  }

  directionsService
    .route({
      origin: document.getElementById("start").value,
      destination: document.getElementById("end").value,
      waypoints: waypts,
      optimizeWaypoints: true,
      travelMode: google.maps.TravelMode.DRIVING,
    })
    .then((response) => {
      directionsRenderer.setDirections(response);

      const route = response.routes[0];
      const summaryPanel = document.getElementById("directions-panel");

      summaryPanel.innerHTML = "";

      // For each route, display summary information.
      for (let i = 0; i < route.legs.length; i++) {
        const routeSegment = i + 1;

        summaryPanel.innerHTML +=
          "<b>Route Segment: " + routeSegment + "</b><br>";
        summaryPanel.innerHTML += route.legs[i].start_address + " to ";
        summaryPanel.innerHTML += route.legs[i].end_address + "<br>";
        summaryPanel.innerHTML += route.legs[i].distance.text + "<br><br>";
      }
    })
    .catch((e) => window.alert("Directions request failed due to " + status));
}

window.initMap = initMap;
index.js

Limiti e restrizioni relativi ai Waypoint

Si applicano i limiti e le limitazioni di utilizzo seguenti:

• Il numero massimo di tappe consentito quando si utilizza il servizio Directions nell'API Maps JavaScript è 25, oltre all'origine e alla destinazione. I limiti sono gli stessi per il servizio web dell'API Directions.
• Per il servizio web dell'API Directions, ai clienti sono consentiti 25 tappe, oltre all'origine e alla destinazione.
• I clienti del piano Premium di Google Maps Platform possono accedere a 25 tappe, oltre all'origine e alla destinazione.
• I Waypoint non sono supportati per le indicazioni stradali del trasporto pubblico.

Indicazioni trascinabili

Gli utenti possono modificare dinamicamente le indicazioni stradali per biciclette, a piedi o in auto visualizzate utilizzando un DirectionsRenderer se sono trascinabili, consentendo di selezionare e modificare i percorsi facendo clic sui percorsi risultanti e trascinandoli sulla mappa. Indica se il display di un renderer consente indicazioni stradali trascinabili impostando la proprietà draggable su true. Le indicazioni per il trasporto pubblico non possono essere trascinate.

Quando è possibile trascinare le indicazioni stradali, un utente può selezionare qualsiasi punto del percorso (o waypoint) del risultato visualizzato e spostare il componente indicato in una nuova posizione. DirectionsRenderer verrà aggiornato in modo dinamico per mostrare il percorso modificato. Dopo il rilascio, verrà aggiunto alla mappa un waypoint di transizione, indicato con un piccolo indicatore bianco. La selezione e lo spostamento di un tratto di percorso modificano la rotta del percorso, mentre la selezione e lo spostamento dell'indicatore di percorso (compresi i punti di partenza e di arrivo) alterano i tratti del percorso che lo attraversano.

Poiché le indicazioni stradali trascinabili vengono modificate e visualizzate sul lato client, puoi monitorare e gestire l'evento directions_changed su DirectionsRenderer per ricevere una notifica quando l'utente ha modificato le indicazioni stradali visualizzate.

Il codice seguente mostra un viaggio da Perth, sulla costa occidentale dell'Australia, a Sydney, sulla costa orientale. Il codice monitora l'evento directions_changed per aggiornare la distanza totale di tutte le tappe del percorso.

TypeScript

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 4,
      center: { lat: -24.345, lng: 134.46 }, // Australia.
    }
  );

  const directionsService = new google.maps.DirectionsService();
  const directionsRenderer = new google.maps.DirectionsRenderer({
    draggable: true,
    map,
    panel: document.getElementById("panel") as HTMLElement,
  });

  directionsRenderer.addListener("directions_changed", () => {
    const directions = directionsRenderer.getDirections();

    if (directions) {
      computeTotalDistance(directions);
    }
  });

  displayRoute(
    "Perth, WA",
    "Sydney, NSW",
    directionsService,
    directionsRenderer
  );
}

function displayRoute(
  origin: string,
  destination: string,
  service: google.maps.DirectionsService,
  display: google.maps.DirectionsRenderer
) {
  service
    .route({
      origin: origin,
      destination: destination,
      waypoints: [
        { location: "Adelaide, SA" },
        { location: "Broken Hill, NSW" },
      ],
      travelMode: google.maps.TravelMode.DRIVING,
      avoidTolls: true,
    })
    .then((result: google.maps.DirectionsResult) => {
      display.setDirections(result);
    })
    .catch((e) => {
      alert("Could not display directions due to: " + e);
    });
}

function computeTotalDistance(result: google.maps.DirectionsResult) {
  let total = 0;
  const myroute = result.routes[0];

  if (!myroute) {
    return;
  }

  for (let i = 0; i < myroute.legs.length; i++) {
    total += myroute.legs[i]!.distance!.value;
  }

  total = total / 1000;
  (document.getElementById("total") as HTMLElement).innerHTML = total + " km";
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

Nota: leggi la guida sull'utilizzo di TypeScript e Google Maps.

JavaScript

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: { lat: -24.345, lng: 134.46 }, // Australia.
  });
  const directionsService = new google.maps.DirectionsService();
  const directionsRenderer = new google.maps.DirectionsRenderer({
    draggable: true,
    map,
    panel: document.getElementById("panel"),
  });

  directionsRenderer.addListener("directions_changed", () => {
    const directions = directionsRenderer.getDirections();

    if (directions) {
      computeTotalDistance(directions);
    }
  });
  displayRoute(
    "Perth, WA",
    "Sydney, NSW",
    directionsService,
    directionsRenderer,
  );
}

function displayRoute(origin, destination, service, display) {
  service
    .route({
      origin: origin,
      destination: destination,
      waypoints: [
        { location: "Adelaide, SA" },
        { location: "Broken Hill, NSW" },
      ],
      travelMode: google.maps.TravelMode.DRIVING,
      avoidTolls: true,
    })
    .then((result) => {
      display.setDirections(result);
    })
    .catch((e) => {
      alert("Could not display directions due to: " + e);
    });
}

function computeTotalDistance(result) {
  let total = 0;
  const myroute = result.routes[0];

  if (!myroute) {
    return;
  }

  for (let i = 0; i < myroute.legs.length; i++) {
    total += myroute.legs[i].distance.value;
  }

  total = total / 1000;
  document.getElementById("total").innerHTML = total + " km";
}

window.initMap = initMap;
index.js

Nota:il codice JavaScript viene compilato dallo snippet TypeScript.

Visualizza esempio

Prova di esempio

JSFiddle.net CodeSandbox.io Google Cloud Shell