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, dai un'occhiata al client Node.js per Google Maps Services. La pagina a questo link introduce anche i client Java, Python e Go per Google Maps Services.

Panoramica

Consulta anche la documentazione di riferimento sull'API Maps JavaScript: Indicazioni stradali

Puoi calcolare le indicazioni stradali (utilizzando diversi metodi di trasporto) utilizzando l'oggetto DirectionsService. Questo oggetto comunica con il servizio Directions dell'API di Google Maps, che riceve richieste di indicazioni stradali e restituisce un percorso efficiente. Il tempo di percorrenza è il fattore principale che viene ottimizzato, ma possono essere presi in considerazione altri fattori come la distanza, il numero di svolte e molti altri. Puoi gestire i risultati di queste indicazioni stradali o utilizzare l'oggetto DirectionsRenderer per eseguire il rendering di questi risultati.

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 Indicazioni stradali può restituire indicazioni stradali in più parti utilizzando una serie di tappe. Le indicazioni stradali vengono visualizzate 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 e prendi la rampa del ponte di 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, seleziona lo stesso progetto configurato per l'API Maps JavaScript e fai clic su Apri.
3. Nell'elenco delle API sulla Dashboard, cerca l'API Directions.
4. Se l'API è presente nell'elenco, significa che è tutto a posto. Se l'API non è nell'elenco, abilitala:
   1. Nella parte superiore della pagina, seleziona ABILITA API per visualizzare la scheda Libreria. In alternativa, seleziona Libreria dal menu a sinistra.
   2. Cerca l'API Directions, quindi selezionala dall'elenco dei risultati.
   3. Seleziona ABILITA. Al termine del processo, l'API Directions viene visualizzata nell'elenco delle API sulla dashboard.

Prezzi e norme

Prezzi

A partire dal 16 luglio 2018, è entrato in vigore un nuovo piano tariffario di pagamento a consumo per Maps, Routes e Places. Per scoprire di più sui nuovi prezzi e sui limiti di utilizzo per l'utilizzo del 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, poiché l'API di Google Maps deve effettuare una chiamata a un server esterno. Per questo motivo, devi passare un metodo di callback da eseguire al completamento della richiesta. Questo metodo di callback dovrebbe elaborare i risultati. Tieni presente che il servizio Directions potrebbe restituire più di un itinerario possibile sotto forma di array di routes[] separati.

Per utilizzare le indicazioni nell'API Maps JavaScript, crea un oggetto di tipo DirectionsService e chiama DirectionsService.route() per avviare una richiesta al servizio Directions, passando un valore letterale di oggetto DirectionsRequest contenente i termini di input e un metodo di callback da eseguire alla ricezione 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 località 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 località LatLng. Puoi recuperare gli ID luogo dai servizi Geocoding, Place Search e Place Autocomplete nell'API Maps JavaScript. Per un esempio di utilizzo degli ID luogo di Place Autocomplete, consulta la pagina Place Autocomplete and Directions.
• destination (obbligatorio) specifica la località di arrivo per cui calcolare le indicazioni stradali. Le opzioni sono le stesse del campo origin descritto sopra.
• travelMode (obbligatorio) specifica la modalità di trasporto da utilizzare per il calcolo delle indicazioni stradali. I valori validi sono specificati in Travel Modes di seguito.
• transitOptions (facoltativo) specifica i valori che si applicano solo alle richieste in cui travelMode è TRANSIT. I valori validi sono descritti nella sezione Opzioni di trasporto pubblico di seguito.
• drivingOptions (facoltativo) specifica i valori che si applicano solo alle richieste in cui travelMode è DRIVING. I valori validi sono descritti nella sezione Opzioni di guida di seguito.

• unitSystem (facoltativo) specifica quale sistema di unità 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 Waypoint modificano un percorso indicandolo attraverso le località specificate. Un Waypoint viene specificato come valore letterale di oggetto con i campi mostrati di seguito:

  • location specifica la posizione del Waypoint, come LatLng, come oggetto Place o come String che verrà geocodificato.
  • stopover è un valore booleano che indica che il Waypoint è una fermata sul percorso, il che ha l'effetto di dividerlo in due route.

  Per ulteriori informazioni sui Waypoint, consulta la sezione Utilizzo dei Waypoint nei Percorsi di seguito.

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

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

Di seguito è riportato un esempio di 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

Quando calcoli le indicazioni stradali, devi specificare quale modalità di trasporto utilizzare. Al momento sono supportate le seguenti modalità di viaggio:

• DRIVING (Valore predefinito) indica indicazioni stradali standard utilizzando la rete stradale.
• BICYCLING richiede indicazioni in bicicletta tramite piste ciclabili e strade preferite.
• TRANSIT richiede indicazioni stradali tramite percorsi di trasporto pubblico.
• WALKING richiede indicazioni a piedi attraverso 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 quel tipo di direzione non è disponibile, la risposta restituirà DirectionsStatus="ZERO_RESULTS".

Nota: le indicazioni a piedi potrebbero non includere percorsi pedonali puliti, pertanto le indicazioni a piedi restituiranno avvisi in DirectionsResult. Questi avvisi devono essere sempre mostrati all'utente. Se non utilizzi l'impostazione predefinita DirectionsRenderer, è tua responsabilità garantire la visualizzazione degli avvisi.

Opzioni di trasporto pubblico

Le opzioni disponibili per una richiesta di indicazioni stradali variano in base alla modalità di viaggio. Quando richiedi indicazioni stradali con il trasporto pubblico, le opzioni avoidHighways, avoidTolls, waypoints[] e optimizeWaypoints verranno 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 un orario di arrivo, quello di partenza viene ignorato.
• departureTime (facoltativo) specifica l'orario di partenza desiderato come oggetto Date. departureTime verrà ignorato se viene specificato arrivalTime. 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 di oggetto 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 l'autobus.
  • RAIL indica che il percorso calcolato dovrebbe preferire viaggiare 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 la modalità tram e metropolitana leggera.
• routingPreference (facoltativo) specifica le preferenze per le route di trasporto pubblico. Utilizzando questa opzione, puoi differenziare le opzioni restituite, anziché accettare la route migliore predefinita scelta dall'API. Questo campo può essere specificato solo se la richiesta include una chiave API. Sono consentiti i seguenti valori:
  • FEWER_TRANSFERS indica che il percorso calcolato dovrebbe preferire un numero limitato di cambi.
  • LESS_WALKING indica che il percorso calcolato dovrebbe preferire tratti a piedi limitati.

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 tramite l'oggetto DrivingOptions.

L'oggetto DrivingOptions contiene i seguenti campi:

{
  departureTime: Date,
  trafficModel: TrafficModel
}

Questi campi sono spiegati di seguito:

• departureTime (obbligatorio per la validità del valore letterale dell'oggetto drivingOptions) specifica l'orario di partenza desiderato come oggetto Date. Il valore deve essere impostato sull'ora attuale o su un periodo di tempo futuro. Non può essere nel passato. (l'API converte tutte le date nel fuso orario UTC per garantire una gestione coerente nei vari fusi orari.) Per i clienti con un 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 nella risposta il tempo previsto nel traffico (duration_in_traffic). Se non specifichi un orario di partenza (ovvero, se la richiesta non include drivingOptions), il percorso restituito è un percorso generalmente valido senza tenere conto delle condizioni del traffico.
• trafficModel (facoltativo) 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 valore predefinito è bestguess. Sono consentiti i seguenti valori:
  • bestguess (valore predefinito) indica che duration_in_traffic restituito dovrebbe essere la migliore stima del tempo di percorrenza in base alle informazioni note sulle condizioni del traffico storico e sul traffico in tempo reale. Il traffico in tempo reale diventa più importante con l'avvicinarsi del departureTime.
  • pessimistic indica che duration_in_traffic restituito dovrebbe essere più lungo del tempo di percorrenza effettivo nella maggior parte dei giorni, anche se giorni occasionali con condizioni di traffico particolarmente sfavorevoli possono superare questo valore.
  • optimistic indica che il valore duration_in_traffic restituito dovrebbe essere più breve del tempo di percorrenza effettivo nella maggior parte dei giorni, anche se i giorni occasionali con condizioni di traffico particolarmente buone possono essere più veloci di questo valore.

Attenzione: se non specifichi un orario di partenza, il percorso e la durata scelti si basano sulla rete stradale e sulle condizioni medie del traffico dipendenti dal tempo, non sulle condizioni attuali delle strade. Di conseguenza, i percorsi potrebbero includere strade temporaneamente chiuse. I risultati di una determinata richiesta possono variare nel tempo a causa di cambiamenti della rete stradale, condizioni medie del traffico aggiornate e natura distribuita del servizio. Inoltre, i risultati possono variare tra percorsi quasi equivalenti in qualsiasi momento o frequenza.

Nota: per assicurarti che la tua richiesta utilizzi le informazioni sul traffico in tempo reale, imposta departureTime su adesso. Le richieste che utilizzano le 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à

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 utilizzano sempre le unità metriche. Ad esempio, un percorso da "Chicago, IL" a "Toronto, ONT" mostrerà i risultati in miglia, mentre il percorso inverso mostra i risultati in chilometri. Puoi eseguire l'override di questo sistema di unità impostandone uno esplicitamente all'interno della richiesta utilizzando uno dei seguenti valori UnitSystem:

• UnitSystem.METRIC specifica l'utilizzo del sistema metrico. Le distanze sono mostrate in chilometri.
• UnitSystem.IMPERIAL specifica l'utilizzo del sistema imperiale (inglese). Le distanze vengono mostrate in miglia.

Nota: questa impostazione di 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 delle regioni per le indicazioni stradali

Il servizio Directions dell'API di Google Maps restituisce risultati relativi agli indirizzi influenzati dal dominio (regione o paese) da cui hai caricato il bootstrap JavaScript. Poiché la maggior parte degli utenti carica https://maps.googleapis.com/, imposta un dominio implicito per gli Stati Uniti. Se carichi il bootstrap da un altro dominio supportato, i risultati saranno influenzati da quel dominio. Ad esempio, la ricerca di "San Francisco" potrebbe 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 Indicazioni stradali in modo che restituisca risultati differenziati per una determinata regione utilizzando il parametro region. Questo parametro accetta un codice regione, specificato come sottotag di regione Unicode a due caratteri (non numerico). Nella maggior parte dei casi, questi tag vengono mappati direttamente ai valori a due caratteri ccTLD ("dominio di primo livello"), ad esempio "uk" in "co.uk". In alcuni casi, il tag region supporta anche i codici ISO-3166-1, che a volte differiscono dai valori ccTLD (ad esempio "GB" per "Gran Bretagna").

Quando utilizzi il parametro region:

• Specifica solo un paese o una regione. Più valori vengono ignorati e potrebbero determinare una richiesta non riuscita.
• Utilizza solo sottotag della regione a due caratteri (formato Unicode CLDR). Tutti gli altri input genereranno errori.

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

Direzioni di rendering

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

Stato della query Indicazioni stradali

DirectionsStatus potrebbe restituire i seguenti valori:

• OK indica che la risposta contiene un 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 è stata trovata alcuna route tra l'origine e la destinazione.
• MAX_WAYPOINTS_EXCEEDED indica che sono stati forniti troppi campi DirectionsWaypoint in DirectionsRequest. Consulta la sezione seguente sui limiti per i punti di percorso.
• MAX_ROUTE_LENGTH_EXCEEDED indica che la route richiesta è troppo lunga e non può essere elaborata. Questo errore si verifica quando vengono restituite direzioni più complesse. Prova a ridurre il numero di tappe, svolte o istruzioni.
• INVALID_REQUEST indica che il valore DirectionsRequest fornito non è valido. Le cause più comuni di questo codice di errore sono le richieste prive di origine o destinazione o una richiesta di trasporto pubblico che include 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 è autorizzata a 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 riprovi, la richiesta potrebbe andare a buon fine.

Devi assicurarti che la query sulle indicazioni stradali abbia restituito risultati validi controllando questo valore prima di elaborare il risultato.

Visualizzazione del DirectionsResult

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

Per visualizzare un elemento DirectionsResult utilizzando un elemento DirectionsRenderer, devi:

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

L'esempio seguente calcola le indicazioni stradali tra due località su Route 66, dove l'origine e la destinazione sono impostate dai valori "start" e "end" specificati negli elenchi a discesa. Gli handle DirectionsRenderer visualizzano la polilinea tra le posizioni indicate e il posizionamento degli indicatori nel punto di origine, di destinazione ed eventuali tappe, se applicabile.

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 del codice 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 del codice 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 DirectionsRenderer non solo gestisce la visualizzazione della polilinea e degli eventuali indicatori associati, ma può anche gestire la visualizzazione testuale delle indicazioni stradali come una serie di passaggi. Per farlo, chiama setPanel() sul tuo DirectionsRenderer, passando l'<div> in cui visualizzare queste informazioni. In questo modo, inoltre, puoi mostrare le informazioni sul copyright appropriate e gli eventuali avvisi che potrebbero essere 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 tramite il parametro language. Per saperne di più, consulta Localizzazione. Per le indicazioni stradali, l'ora verrà visualizzata nel fuso orario di quella fermata.

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 del codice 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, che è un oggetto DirectionsResult. DirectionsResult è un valore letterale oggetto con i seguenti campi:

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

Nota: la proprietà via_waypoint è ritirata nei percorsi alternativi. La versione 3.27 è l'ultima versione dell'API che aggiunge ulteriori punti di accesso tramite tappe in percorsi alternativi. Per le versioni 3.28 e successive dell'API, puoi continuare a implementare le direzioni trascinabili utilizzando il servizio Directions, disattivando il trascinamento dei percorsi alternativi. Solo il percorso principale deve essere trascinabile. Gli utenti possono trascinare il percorso principale finché non corrisponde a un percorso alternativo.

Waypoint geocodificati delle 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 la geocodifica è riuscita, ma non ha restituito alcun risultato. Questo può accadere se al geocodificatore è stato trasmesso un codice address inesistente.

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

  Nella maggior parte dei casi, le corrispondenze parziali si verificano per indirizzi che non esistono all'interno della località indicata nella richiesta. Le corrispondenze parziali possono essere restituite anche quando una richiesta corrisponde a due o più località 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 errato, il servizio di geocodifica potrebbe suggerire un indirizzo alternativo. Anche i suggerimenti attivati in questo modo verranno contrassegnati come corrispondenza parziale.

• place_id è l'identificatore univoco di un luogo, che può essere utilizzato con altre API di Google. Ad esempio, puoi utilizzare place_id con la libreria dell'API Google Places per ottenere i dettagli di un'attività locale, come numero di telefono, orario di apertura, recensioni degli utenti e altro ancora. Vedi la panoramica di 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 caratteristica restituito nel risultato. Ad esempio, un codice geografico di "Chicago" restituisce "località", che indica che "Chicago" è una città, e "politica", che indica che si tratta di un'entità politica.

Percorsi con indicazioni stradali

Nota: l'oggetto DirectionsTrip precedente è stato rinominato DirectionsRoute. Tieni presente che un percorso ora si riferisce all'intero viaggio dall'inizio alla fine, anziché semplicemente a una tratta della corsa di un genitore.

Un elemento DirectionsRoute contiene un singolo risultato dall'origine e dalla destinazione specificate. Il percorso può essere costituito da una o più tappe (di tipo DirectionsLeg) a seconda che siano stati specificati dei tappe. Inoltre, la route contiene anche informazioni sul copyright e di avviso che devono essere mostrate all'utente in aggiunta alle informazioni sul routing.

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

• legs[] contiene un array di oggetti DirectionsLeg, ciascuno dei quali contiene informazioni su un tratto del percorso, da due posizioni all'interno della route specificata. Sarà presente una tratta separata per ogni tappa o destinazione specificati. Un percorso senza tappe conterrà esattamente un DirectionsLeg. Ogni tratta è composta da una serie di DirectionStep.
• waypoint_order contiene un array che indica l'ordine di eventuali tappe nella route calcolata. Questo array potrebbe contenere un ordine modificato se DirectionsRequest è stato trasmesso optimizeWaypoints: true.
• overview_path contiene un array di LatLng che rappresentano un percorso approssimativo (attenuato) delle direzioni risultanti.
• overview_polyline contiene un singolo oggetto points che contiene una rappresentazione polilinea codificata della route. Questa polilinea è un percorso approssimativo (attenuato) delle direzioni risultanti.
• bounds contiene un elemento LatLngBounds che indica i limiti della polilinea lungo questo percorso specificato.
• copyrights contiene il testo relativo al copyright da visualizzare per questo percorso.
  Nota: se non utilizzi l'oggetto DirectionsRenderer fornito, devi gestire e visualizzare queste informazioni autonomamente.
• 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 i costi totali del biglietto) per questo itinerario. Questa proprietà viene restituita solo per le richieste di trasporto pubblico e solo per i percorsi in cui le informazioni sulle tariffe sono disponibili per tutte le fermate del trasporto pubblico. Le informazioni includono:
  • currency: un codice valuta ISO 4217 che indica la valuta in cui è espresso l'importo.
  • value: l'importo totale della tariffa nella valuta specificata sopra.

Indicazioni stradali

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

Un DirectionsLeg definisce una singola tratta di un tragitto dall'origine alla destinazione nel percorso calcolato. Per i percorsi che non contengono tappe, il percorso sarà costituito da una singola "tratto", mentre per i percorsi che definiscono uno o più tappe, il percorso sarà costituito da una o più tappe, corrispondenti alle parti specifiche del viaggio.

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

• steps[] contiene un array di oggetti DirectionsStep che indicano informazioni su ogni singola fase della tratta del viaggio.

• distance indica la distanza totale percorsa da questo tratto, come un oggetto Distance nel seguente formato:

  • value indica la distanza in metri
  • text contiene una rappresentazione stringa della distanza, che per impostazione predefinita viene visualizzata in 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 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 oggetto Duration del seguente formato:

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

  Se la durata è sconosciuta, questi campi potrebbero non essere definiti.

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

  • La richiesta non include tappe di sosta. Ciò significa che non include tappe in cui stopover è true.
  • La richiesta riguarda specificamente le indicazioni stradali: mode è impostato su driving.
  • departureTime è incluso nel campo drivingOptions della richiesta.
  • Le condizioni del traffico sono disponibili per la route richiesta.

  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 stradali con il trasporto pubblico. Il risultato viene restituito come oggetto Time con tre proprietà:
  • value l'ora specificata come oggetto Date JavaScript.
  • text l'ora specificata 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 tratta, specificato come oggetto Time. departure_time è disponibile solo per le indicazioni stradali con il trasporto pubblico.
• start_location contiene il valore LatLng dell'origine di questa gamba. Poiché il servizio web Indicazioni stradali calcola le indicazioni stradali da un luogo all'altro utilizzando l'opzione di trasporto più vicina (di solito una strada) nei punti di partenza e di arrivo, start_location potrebbe essere diversa dall'origine fornita per questo tratto se, ad esempio, una strada non si trova vicino al punto di partenza.
• end_location contiene il LatLng della destinazione di questa tratta. 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 diversa dalla destinazione fornita per questo tratto se, ad esempio, una strada non è vicina alla destinazione.
• start_address contiene l'indirizzo leggibile (in genere l'indirizzo) di inizio della tratta.
  
  Questi contenuti sono destinati a essere letti così come sono. Non analizzare in modo programmatico l'indirizzo formattato.
• end_address contiene l'indirizzo leggibile (in genere l'indirizzo) alla fine della tratta.
  
  Questi contenuti sono destinati a essere letti così come sono. Non analizzare in modo programmatico l'indirizzo formattato.

Indicazioni stradali

Un DirectionsStep è l'unità più atomica del percorso di una direzione, contenente un singolo passaggio che descrive una singola istruzione specifica del viaggio. Ad esempio, "Svolta a sinistra in direzione W. Via Verdi" Il passaggio non solo descrive l'istruzione, ma contiene anche informazioni su distanza e durata relative al modo in cui questo passaggio si riferisce al passaggio successivo. Ad esempio, un passaggio indicato come "Merge on I-80 West" può contenere una durata di "37 miglia" e "40 minuti", che indica che il passaggio successivo è a 39 miglia/40 minuti da questo passaggio.

Quando utilizzi il servizio Indicazioni stradali per cercare indicazioni per il trasporto pubblico, l'array di passi includerà informazioni specifiche per il trasporto pubblico sotto forma di oggetto transit. Se le indicazioni stradali includono più modalità di trasporto, vengono fornite indicazioni dettagliate per i passi a piedi o in auto in un array steps[]. Ad esempio, un passaggio a piedi includerà le indicazioni stradali dalla posizione di partenza e di arrivo: "Walk to Innes Ave & Fitch St". Questo passaggio includerà indicazioni a piedi dettagliate per il percorso nell'array steps[], ad esempio "Procedi verso nord-ovest", "Svolta a sinistra su Arelious Walker" e "Svolta a sinistra in 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 a quello successivo, sotto forma di oggetto Distance. Vedi la descrizione nella sezione DirectionsLeg sopra. Questo campo potrebbe non essere definito se la distanza è sconosciuta.
• duration contiene una stima del tempo necessario per eseguire il passaggio, fino a quello successivo, sotto forma di oggetto Duration. Vedi la descrizione nella sezione DirectionsLeg qui sopra. Questo campo potrebbe non essere definito se la durata è sconosciuta.
• start_location contiene il valore LatLng geocodificato del punto di partenza di questo passaggio.
• end_location contiene il valore LatLng del punto finale di questo passaggio.
• polyline contiene un singolo oggetto points che contiene una rappresentazione polilinea codificata del passaggio. Questa polilinea è un percorso approssimativo (attenuato) del passaggio.
• steps[] un valore letterale oggetto DirectionsStep che contiene indicazioni dettagliate per i passi a piedi o in auto nelle indicazioni di trasporto pubblico. I passaggi secondari sono disponibili solo per le indicazioni stradali con il trasporto pubblico.
• travel_mode contiene il valore TravelMode utilizzato in questo passaggio. Le indicazioni di trasporto pubblico possono includere una combinazione di indicazioni a piedi e con il trasporto pubblico.
• path contiene un array di LatLngs che descrive lo svolgimento di questo passaggio.
• transit contiene informazioni specifiche sul trasporto pubblico, come gli orari di arrivo e di partenza e il nome della linea di trasporto pubblico.

Informazioni specifiche sul trasporto pubblico

Le indicazioni di trasporto pubblico restituiscono informazioni aggiuntive non pertinenti per altre modalità di trasporto. Queste proprietà aggiuntive vengono esposte tramite l'oggetto TransitDetails, restituita 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/fermata di arrivo con le seguenti proprietà:
  • name il nome della stazione/fermata di trasporto pubblico. Ad esempio: "Piazza Cordusio".
  • location la posizione della stazione/fermata di trasporto pubblico, rappresentata come LatLng.
• departure_stop contiene un oggetto TransitStop che rappresenta la stazione/la fermata di partenza.
• arrival_time contiene l'ora di arrivo, specificata come un oggetto Time con tre proprietà:
  • value l'ora specificata come oggetto Date JavaScript.
  • text l'ora specificata 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 viaggiare su questa linea, in quanto è indicata sul veicolo o alla fermata di partenza. Spesso si tratta della stazione di capolinea.
• headway, se disponibile, specifica il numero di secondi previsto di secondi tra una partenza dalla stessa fermata in questo momento. Ad esempio, con un valore headway pari a 600, è prevista un'attesa di dieci minuti in caso di perdita dell'autobus.
• line contiene un valore letterale oggetto TransitLine che contiene informazioni sulla linea di trasporto pubblico utilizzata in questo passaggio. TransitLine fornisce il nome e l'operatore della linea, insieme alle altre proprietà descritte nella documentazione di riferimento di TransitLine.
• num_stops contiene il numero di fermate in questo passaggio. Include la fermata di arrivo, ma non quella di partenza. Ad esempio, se le indicazioni stradali prevedono la partenza dalla fermata A, passando per le fermate B e C e arrivando 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 es. "7 Avenue Express" o "14th St Crosstown".
• short_name contiene il nome breve di questa linea di trasporto pubblico. In genere si tratta di 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 visualizzi manualmente le indicazioni stradali con il trasporto pubblico anziché utilizzare l'oggetto DirectionsRenderer, devi visualizzare i nomi e gli URL delle aziende di trasporto pubblico che pubblicano i risultati della corsa.

• url contiene un URL per questa linea di trasporto pubblico fornito dall'azienda di trasporto pubblico.
• icon contiene un URL per l'icona associata a questa linea. La maggior parte delle città utilizza icone generiche che variano in base al tipo di veicolo. Alcune linee di trasporto pubblico, come la metropolitana di New York, hanno icone specifiche per ogni linea.
• color contiene il colore comunemente utilizzato nella segnaletica di questo trasporto pubblico. Il colore verrà specificato come stringa esadecimale, ad esempio #FF0033.
• text_color contiene il colore del 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 riga. Ad esempio: "Metropolitana"
  • type contiene il tipo di veicolo utilizzato in questa linea. Consulta la documentazione relativa al 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 per il trasporto locale.

Tipo di veicolo

L'oggetto VehicleType espone le seguenti proprietà:

Valore	Definizione
VehicleType.RAIL	Treno.
VehicleType.METRO_RAIL	Metropolitana leggera.
VehicleType.SUBWAY	Metropolitana leggera sotterranea.
VehicleType.TRAM	Metropolitana leggera sopra il suolo.
VehicleType.MONORAIL	Monorotaia.
VehicleType.HEAVY_RAIL	Treno pesante.
VehicleType.COMMUTER_TRAIN	Ferrovia suburbana.
VehicleType.HIGH_SPEED_TRAIN	Treno ad alta velocità.
VehicleType.BUS	Autobus.
VehicleType.INTERCITY_BUS	Autolinee regionali e nazionali.
VehicleType.TROLLEYBUS	Filobus.
VehicleType.SHARE_TAXI	Il taxi condiviso è un tipo di autobus che consente di scendere e far salire a bordo passeggeri in qualsiasi punto del percorso.
VehicleType.FERRY	Traghetto.
VehicleType.CABLE_CAR	Un veicolo che funziona tramite cavo, solitamente a terra. Le funivie aeree possono essere del tipo VehicleType.GONDOLA_LIFT.
VehicleType.GONDOLA_LIFT	Una funivia.
VehicleType.FUNICULAR	Veicolo trainato da un cavo su una ripida pendenza. Una funicolare è generalmente composta da due carrozze, ciascuna delle quali agisce da contrappeso per l'altra.
VehicleType.OTHER	Tutti gli altri veicoli restituiranno questo tipo.

Controllo di DirectionsResults

I componenti DirectionsResults, DirectionsRoute, DirectionsLeg, DirectionsStep e TransitDetails, possono essere ispezionati e utilizzati durante l'analisi delle risposte alle indicazioni stradali.

Importante: se visualizzi manualmente le indicazioni stradali con il trasporto pubblico anziché utilizzare l'oggetto DirectionsRenderer, devi visualizzare i nomi e gli URL delle aziende di trasporto pubblico che pubblicano i risultati della corsa.

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

Nota: poiché 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 del codice 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 dei Waypoint nei Percorsi

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

Come indicato in DirectionsRequest, puoi anche specificare waypoint (di tipo DirectionsWaypoint) quando calcoli i percorsi utilizzando il servizio Indicazioni stradali per indicazioni a piedi, in bicicletta o in auto. I Waypoint non sono disponibili per le indicazioni stradali con il trasporto pubblico. I Waypoint consentono di calcolare i percorsi attraverso località aggiuntive, nel qual caso il percorso restituito passa attraverso quelli specificati.

Un waypoint è costituito dai seguenti campi:

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

Attenzione: se imposti stopover su false per evitare tappe, le indicazioni stradali sono molto rigide nell'interpretazione del percorso. Potrebbero verificarsi gravi deviazioni sul percorso o ZERO_RESULTS nel codice di stato della risposta se Directions Service non è in grado di creare indicazioni stradali per quel punto.

Per impostazione predefinita, il servizio Indicazioni stradali calcola un percorso attraverso i tappe forniti nell'ordine indicato. Se vuoi, puoi trasmettere optimizeWaypoints: true all'interno dell' DirectionsRequest per consentire al servizio Indicazioni stradali di ottimizzare il percorso fornito riorganizzando i tappe in un ordine più efficiente. (Questa ottimizzazione è un'applicazione del problema con i venditori ambulanti.) Il tempo di percorrenza è il fattore principale che viene ottimizzato, ma altri fattori come la distanza, il numero di svolte e molti altri possono essere presi in considerazione per decidere quale percorso è il più efficiente. Tutti i tappe devono essere tappe affinché il servizio Directions possa ottimizzare il proprio percorso.

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

L'esempio seguente calcola le rotte che attraversano i diversi paesi degli Stati Uniti utilizzando una serie di punti di partenza, 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 dei punti di partenza e di arrivo di ogni route.

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 per i Waypoint

Si applicano i seguenti limiti e restrizioni di utilizzo:

• Il numero massimo di tappe consentiti quando si utilizza il servizio Directions nell'API Maps JavaScript è 25, più l'origine e la 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, più l'origine e la destinazione.
• Ai clienti del piano Premium di Google Maps Platform sono consentiti 25 tappe, oltre all'origine e alla destinazione.
• I Waypoint non sono supportati per le indicazioni di trasporto pubblico.

Indicazioni trascinabili

Gli utenti possono modificare le indicazioni in bicicletta, a piedi o in auto visualizzate utilizzando un elemento DirectionsRenderer in modo dinamico se sono trascinabili. In questo modo, possono selezionare e modificare i percorsi facendo clic e trascinando i percorsi risultanti sulla mappa. Puoi indicare se la visualizzazione di un renderer consente le direzioni trascinabili impostando la relativa proprietà draggable su true. Le indicazioni di trasporto pubblico non possono essere rese trascinabili.

Se le indicazioni stradali sono trascinabili, l'utente può selezionare qualsiasi punto del percorso (o tappa) del risultato visualizzato e spostare il componente indicato in una nuova posizione. DirectionsRenderer verrà aggiornato in modo dinamico per mostrare il percorso modificato. Al momento del rilascio, verrà aggiunto alla mappa un tappa di transizione (indicata da un piccolo indicatore bianco). La selezione e lo spostamento di un segmento di percorso ne altera il tratto del percorso, mentre la selezione e lo spostamento di un indicatore di tappe (inclusi i punti di partenza e di arrivo) altera i tratti del percorso che lo attraversa.

Poiché le direzioni trascinabili vengono modificate e ne viene eseguito il rendering lato client, ti consigliamo di monitorare e gestire l'evento directions_changed in DirectionsRenderer per ricevere una notifica quando l'utente modifica le indicazioni stradali visualizzate.

Il seguente codice 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 Sample

JSFiddle.net Google Cloud Shell