Directions Service (legacy)

Sviluppatori dello Spazio economico europeo (SEE)
Nota: librerie lato server

Panoramica

Puoi calcolare le indicazioni stradali (utilizzando vari mezzi 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 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 questi risultati direzionali autonomamente o utilizzare l'oggetto DirectionsRenderer per eseguirne il rendering.

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 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, in aggiunta, come una serie di descrizioni testuali all'interno di un elemento <div> (ad esempio, "Svolta a destra sulla rampa del ponte di Williamsburg").

Per iniziare

Prima di utilizzare il servizio Directions nell'API Maps JavaScript, assicurati che l'API Directions (Legacy) sia abilitata 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 seleziona 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 (Legacy).
  4. Se l'API è presente nell'elenco, non devi fare altro. Se l'API non è elencata, abilitala all'indirizzo https://console.cloud.google.com/apis/library/directions-backend.googleapis.com

Prezzi e norme

Prezzi

Per scoprire di più sui prezzi e sulle norme di utilizzo del servizio JavaScript Directions, consulta Utilizzo e fatturazione per l'API Directions (legacy).

Norme

L'utilizzo del servizio Directions deve essere conforme alle policy descritte per l'API Directions (Legacy).

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 deve 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 stradali nell'API Maps JavaScript, crea un oggetto di tipo DirectionsService e chiama DirectionsService.route() per avviare una richiesta al servizio Directions, passando un oggetto letterale DirectionsRequest contenente i termini di input e un metodo di callback da eseguire alla ricezione della risposta.

L'oggetto letterale 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 Place Autocomplete e Directions.
  • destination (obbligatorio) specifica la località di arrivo per la quale 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 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 nella sezione Opzioni di transito 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 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 waypoint modificano un percorso indirizzandolo attraverso le località specificate. Un waypoint viene specificato come oggetto letterale con i campi mostrati di seguito:

    • location specifica la posizione della tappa come LatLng, come oggetto Place o come String che verrà geocodificato.
    • stopover è un valore booleano che indica che la tappa è una fermata lungo il percorso, il che ha l'effetto di dividere il percorso in due.

    Per saperne di più sui waypoint, consulta la sezione Utilizzo dei waypoint nei percorsi di seguito.

  • optimizeWaypoints (facoltativo) specifica che il percorso che utilizza i waypoints forniti può essere ottimizzato riorganizzando i waypoint in un ordine più efficiente. Se true, il servizio Directions restituirà i waypoints riordinati in un campo waypoint_order. Per ulteriori informazioni, consulta Utilizzo dei waypoint nei percorsi di seguito.
  • provideRouteAlternatives (facoltativo) se impostato su true, specifica che il servizio Directions può fornire più di un percorso alternativo nella risposta. Tieni presente che fornire percorsi alternativi potrebbe 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 i percorsi calcolati 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 le strade a pedaggio, se possibile.
  • region (facoltativo) specifica il codice regione, indicato come valore di due caratteri ccTLD ("dominio di primo livello"). Per saperne di più, consulta la sezione Sottoporre a bias per regione di seguito.

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 la modalità di trasporto da utilizzare. Al momento sono supportate le seguenti modalità di viaggio:

  • DRIVING (valore predefinito) indica le indicazioni stradali standard che utilizzano la rete stradale.
  • BICYCLING richiede indicazioni stradali in bicicletta tramite piste ciclabili e strade preferite.
  • TRANSIT richiede indicazioni stradali tramite percorsi di trasporto pubblico.
  • 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 questo tipo di indicazioni non è disponibile, la risposta restituirà DirectionsStatus="ZERO_RESULTS".

Nota: le indicazioni a piedi potrebbero non includere percorsi pedonali chiari, pertanto restituiranno avvisi in DirectionsResult. Questi avvisi devono essere sempre visualizzati per l'utente. Se non utilizzi l'elemento DirectionsRenderer predefinito, è tua responsabilità assicurarti che gli avvisi vengano visualizzati.

Opzioni di trasporto pubblico

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

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

L'oggetto letterale 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 specificata l'ora di arrivo, l'ora di partenza viene ignorata.
  • departureTime (facoltativo) specifica l'orario di partenza desiderato come oggetto Date. departureTime verrà ignorato se viene specificato arrivalTime. Il valore predefinito è l'ora corrente se non viene specificato alcun valore per departureTime o arrivalTime.
  • modes[] (facoltativo) è un array contenente uno o più oggetti letterali TransitMode. Questo campo può essere incluso solo se la richiesta include una chiave API. Ogni TransitMode specifica una modalità di trasporto preferita. Sono consentiti i seguenti valori:
    • BUS indica che il percorso calcolato deve preferire il viaggio in autobus.
    • RAIL indica che il percorso calcolato deve preferire i viaggi in treno, tram, metropolitana leggera e metropolitana.
    • SUBWAY indica che il percorso calcolato deve preferire gli spostamenti in metropolitana.
    • TRAIN indica che il percorso calcolato deve preferire il viaggio in treno.
    • TRAM indica che il percorso calcolato deve preferire i viaggi in tram e metropolitana leggera.
  • routingPreference (facoltativo) specifica le preferenze per i percorsi con il trasporto pubblico. Utilizzando questa opzione, puoi influenzare 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 il percorso calcolato deve preferire un numero limitato di cambi.
    • LESS_WALKING indica che il percorso calcolato deve preferire quantità limitate di tratti a piedi.

Di seguito è riportato un esempio di DirectionsRequest con 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 affinché l'oggetto letterale drivingOptions sia valido) specifica l'orario di partenza desiderato come oggetto Date. Il valore deve essere impostato sull'ora corrente o su un'ora futura. Non può essere nel passato. (L'API converte tutte le date in UTC per garantire una gestione coerente tra i 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 del traffico previste in quel momento e include il tempo previsto nel traffico (duration_in_traffic) nella risposta. Se non specifichi un orario di partenza (ovvero se la richiesta non include drivingOptions), il percorso restituito è generalmente un buon percorso 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 di percorrenza previsto nel traffico in base alle medie storiche. Il valore predefinito è bestguess. Sono consentiti i seguenti valori:
    • bestguess (valore predefinito) indica che il valore duration_in_traffic restituito deve essere la migliore stima del tempo di percorrenza in base a ciò che è noto sulle condizioni del traffico storiche e in tempo reale. Il traffico in tempo reale diventa più importante quanto più departureTime è vicino al momento attuale.
    • pessimistic indica che il valore duration_in_traffic restituito deve essere superiore al tempo di percorrenza effettivo nella maggior parte dei giorni, anche se in alcuni giorni con condizioni del traffico particolarmente negative questo valore potrebbe essere superato.
    • optimistic indica che il valore duration_in_traffic restituito deve essere inferiore al tempo di percorrenza effettivo nella maggior parte dei giorni, anche se in alcuni giorni con condizioni del traffico particolarmente favorevoli il tempo di percorrenza potrebbe essere inferiore a questo valore.

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à di misura del paese o della regione di partenza. (Nota: le origini espresse utilizzando le coordinate di latitudine/longitudine anziché gli indirizzi utilizzano sempre le unità di misura del sistema metrico decimale.) Ad esempio, un percorso da "Chicago, IL" a "Toronto, ONT" mostrerà i risultati in miglia, mentre il percorso inverso mostrerà i risultati in chilometri. Puoi eseguire l'override di questo sistema di unità impostandone uno in modo esplicito all'interno della richiesta utilizzando uno dei seguenti valori UnitSystem:

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

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

Impostazione della regione per le indicazioni stradali

Il servizio di indicazioni stradali 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/, viene impostato 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, 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 risultati influenzati da una determinata regione utilizzando il parametro region. Questo parametro accetta un codice regione, specificato come sottotag di regione Unicode di due caratteri (non numerici). Nella maggior parte dei casi, questi tag vengono mappati direttamente ai valori di due caratteri del 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 un solo paese o una sola regione. I valori multipli vengono ignorati e potrebbero comportare una richiesta non riuscita.
  • Utilizza solo sottotag di regione di due caratteri (formato Unicode CLDR). Tutti gli altri input genereranno errori.

La preferenza per una regione è supportata solo per i paesi e le regioni che supportano le indicazioni stradali. Consulta i dettagli sulla copertura di Google Maps Platform per visualizzare la copertura internazionale per l'API Directions (Legacy).

Rendering delle indicazioni stradali

Per avviare una richiesta di indicazioni stradali per DirectionsService con il metodo route(), è necessario passare un callback che viene eseguito al completamento della richiesta di servizio. Questo callback restituirà un DirectionsResult e un codice DirectionsStatus nella risposta.

Stato della query di indicazioni stradali

DirectionsStatus può 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 waypoint della richiesta.
  • ZERO_RESULTS indica che non è stato possibile trovare un percorso tra l'origine e la destinazione.
  • MAX_WAYPOINTS_EXCEEDED indica che sono stati forniti troppi campi DirectionsWaypoint in DirectionsRequest. Consulta la sezione di seguito sui limiti per i waypoint.
  • MAX_ROUTE_LENGTH_EXCEEDED indica che il percorso richiesto è troppo lungo e non può essere elaborato. Questo errore si verifica quando vengono restituite indicazioni più complesse. Prova a ridurre il numero di waypoint, 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 oppure una richiesta di trasporto pubblico che include waypoint.
  • 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. La richiesta potrebbe andare a buon fine se riprovi.

Prima di elaborare il risultato, devi assicurarti che la query sulle indicazioni stradali abbia restituito risultati validi controllando questo valore.

Visualizzazione di 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 DirectionsResult utilizzando un DirectionsRenderer, devi:

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

L'esempio seguente calcola le indicazioni stradali tra due località sulla Route 66, dove l'origine e la destinazione sono impostate dai valori "start" e "end" specificati negli elenchi a discesa. DirectionsRenderer gestisce la visualizzazione della polilinea tra le località indicate e il posizionamento degli indicatori in corrispondenza di origine, destinazione ed eventuali waypoint, 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 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, in California:

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 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 oggetto 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. Per farlo, chiama setPanel() sul tuo DirectionsRenderer, passandogli il <div> in cui visualizzare queste informazioni. In questo modo, ti assicuri anche di 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 dell'API JavaScript utilizzando il parametro language. Per saperne di più, consulta Localizzazione. Nel caso delle indicazioni per il trasporto pubblico, l'ora verrà visualizzata nel fuso orario della 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 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 all'DirectionsService, ricevi una risposta composta da un codice di stato e un risultato, ovvero un oggetto DirectionsResult. DirectionsResult è un oggetto letterale con i seguenti campi:

  • geocoded_waypoints[] contiene un array di oggetti DirectionsGeocodedWaypoint, ognuno dei quali contiene dettagli sulla geocodifica di origine, destinazione e tappe.
  • routes[] contiene un array di oggetti DirectionsRoute. Ogni percorso indica un modo per raggiungere la destinazione dal luogo di partenza fornito in DirectionsRequest. In genere, per ogni richiesta viene restituito un solo percorso, a meno che il campo provideRouteAlternatives della richiesta non sia impostato su true, nel qual caso potrebbero essere restituiti più percorsi.

Nota: la proprietà via_waypoint è deprecata nei percorsi alternativi. La versione 3.27 è l'ultima versione dell'API che aggiunge waypoint aggiuntivi nei percorsi alternativi. Per le versioni 3.28 e successive dell'API, puoi continuare a implementare le indicazioni stradali 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.

Punti di passaggio geocodificati delle indicazioni stradali

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

DirectionsGeocodedWaypoint è un oggetto letterale 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 ed è stato restituito almeno un codice geografico.
    • "ZERO_RESULTS" indica che la geocodifica è andata a buon fine, ma non ha restituito risultati. Questo può accadere se al geocodificatore è stato passato un address inesistente.

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

    Le corrispondenze parziali si verificano più spesso per indirizzi che non esistono all'interno della località che passi 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 sia 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. I suggerimenti attivati in questo modo verranno contrassegnati anche come corrispondenza parziale.

  • place_idè un 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. Consulta la panoramica degli 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 elemento restituito nel risultato. Ad esempio, un geocodice di "Chicago" restituisce "locality", che indica che "Chicago" è una città, e restituisce anche "political", che indica che si tratta di un'entità politica.

Percorsi con indicazioni stradali

Nota: l'oggetto DirectionsTrip legacy è stato rinominato in DirectionsRoute. Tieni presente che un percorso ora si riferisce all'intero tragitto dall'inizio alla fine, anziché semplicemente a una tappa di un percorso principale.

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

DirectionsRoute è un oggetto letterale con i seguenti campi:

  • legs[] contiene un array di oggetti DirectionsLeg, ognuno dei quali contiene informazioni su una tappa del percorso, da due località all'interno del percorso specificato. Verrà visualizzata una tratta separata per ogni waypoint o destinazione specificati. Un percorso senza tappe intermedie conterrà esattamente un elemento DirectionsLeg. Ogni tratto è costituito da una serie di elementi DirectionStep.
  • waypoint_order contiene un array che indica l'ordine di eventuali waypoint nel percorso calcolato. Questo array potrebbe contenere un ordine modificato se DirectionsRequest è stato passato optimizeWaypoints: true.
  • overview_path contiene un array di LatLng che rappresentano un percorso approssimativo (smussato) delle indicazioni stradali risultanti.
  • overview_polyline contiene un singolo oggetto points che contiene una rappresentazione della polilinea codificata del percorso. Questa polilinea è un percorso approssimativo (smussato) 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 questo percorso.
  • warnings[] contiene un array di avvisi da mostrare quando vengono visualizzate queste indicazioni stradali. Se non utilizzi l'oggetto DirectionsRenderer fornito, devi gestire e visualizzare questi avvisi autonomamente.
  • fare contiene la tariffa totale (ovvero i costi totali dei biglietti) per questo percorso. Questa proprietà viene restituita solo per le richieste di trasporto pubblico e solo per i percorsi per i quali sono disponibili informazioni sulle tariffe per tutte le tratte 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.

Tratte delle indicazioni stradali

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

Un DirectionsLeg definisce una singola tappa di un percorso dal luogo di partenza alla destinazione nel percorso calcolato. Per i percorsi che non contengono tappe, il percorso sarà costituito da un'unica "tratta", ma per i percorsi che definiscono una o più tappe, il percorso sarà costituito da una o più tratte, corrispondenti alle tratte specifiche del percorso.

DirectionsLeg è un oggetto letterale con i seguenti campi:

  • steps[] contiene un array di oggetti DirectionsStep che indicano informazioni su ogni singolo passaggio della tappa del percorso.

  • distance indica la distanza totale coperta da questa tappa, come oggetto Distance nel seguente formato:

    • value indica la distanza in metri
    • text contiene una rappresentazione di stringa della distanza, che per impostazione predefinita viene visualizzata nelle unità utilizzate nell'origine. Ad esempio, le miglia verranno utilizzate per qualsiasi origine negli Stati Uniti. Puoi eseguire l'override di questo sistema di unità impostando in modo specifico un'unità UnitSystem nella query originale. Tieni presente che, indipendentemente dal sistema di unità di misura 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 tappa, come oggetto Duration nel seguente formato:

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

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

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

    • La richiesta non include waypoint di sosta. In altre parole, non include i waypoint in cui stopover è true.
    • La richiesta riguarda specificamente le indicazioni stradali: il parametro mode è impostato su driving.
    • Il valore departureTime è incluso nel campo drivingOptions della richiesta.
    • Le condizioni del traffico sono disponibili 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 stimato per questa tappa. Questa proprietà viene restituita solo per le indicazioni per il trasporto pubblico. Il risultato viene restituito come oggetto Time con tre proprietà:
    • value l'ora specificata come oggetto JavaScript Date.
    • text l'ora specificata come stringa. L'orario viene visualizzato nel fuso orario della fermata dei mezzi pubblici.
    • 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 tappa, specificato come oggetto Time. departure_time è disponibile solo per le indicazioni per il trasporto pubblico.
  • start_location contiene il LatLng dell'origine di questa tappa. 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 questa tappa se, ad esempio, non è presente una strada vicino all'origine.
  • end_location contiene il LatLng della destinazione di questa tappa. Poiché l'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 tappa se, ad esempio, non c'è una strada vicino alla destinazione.
  • start_address contiene l'indirizzo leggibile (in genere una via) dell'inizio di questa tappa.

    Questi contenuti devono essere letti così come sono. Non analizzare l'indirizzo formattato in modo programmatico.
  • end_address contiene l'indirizzo leggibile (in genere una via) della fine di questa tratta.

    Questi contenuti devono essere letti così come sono. Non analizzare l'indirizzo formattato in modo programmatico.

Passaggi delle indicazioni stradali

Un DirectionsStep è l'unità più atomica del percorso di una direzione e contiene un singolo passaggio che descrive un'istruzione specifica e singola sul percorso. Ad esempio "Svolta a sinistra in W. 4th St." Il passaggio non solo descrive l'istruzione, ma contiene anche informazioni sulla distanza e sulla durata relative alla relazione tra questo passaggio e quello successivo. Ad esempio, un passaggio indicato come "Immettiti sulla I-80 West" può contenere una durata di "37 miglia" e "40 minuti", a indicare che il passaggio successivo si trova a 37 miglia/40 minuti da questo passaggio.

Quando utilizzi il servizio Directions per cercare indicazioni per il trasporto pubblico, l'array steps includerà informazioni specifiche sul trasporto pubblico aggiuntive sotto forma di un oggetto transit. Se le indicazioni includono più modalità di trasporto, verranno fornite indicazioni dettagliate per i passaggi a piedi o in auto in un array steps[]. Ad esempio, un passaggio a piedi includerà le indicazioni stradali dalle località di partenza e di arrivo: "Cammina fino a Innes Ave & Fitch St". Questo passaggio includerà indicazioni a piedi dettagliate per il percorso nell'array steps[], ad esempio: "Procedi in direzione nord-ovest", "Svolta a sinistra su Arelious Walker" e "Svolta a sinistra su Innes Ave".

DirectionsStep è un oggetto letterale con i seguenti campi:

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

Informazioni specifiche sul trasporto pubblico

Le indicazioni per il trasporto pubblico restituiscono informazioni aggiuntive che non sono pertinenti per altre modalità di trasporto. Queste proprietà aggiuntive vengono 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 sul 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 Barberini".
    • location la posizione della stazione/fermata di transito, rappresentata come LatLng.
  • departure_stop contiene un oggetto TransitStop che rappresenta la stazione/fermata di partenza.
  • arrival_time contiene l'ora di arrivo, specificata come oggetto Time con tre proprietà:
    • value l'ora specificata come oggetto JavaScript Date.
    • text l'ora specificata come stringa. L'orario viene visualizzato nel fuso orario della fermata dei mezzi pubblici.
    • 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'ora di partenza, specificata come oggetto Time.
  • headsign specifica la direzione di viaggio su questa linea, come indicato sul veicolo o alla fermata di partenza. Spesso si tratta della stazione capolinea.
  • headway se disponibile, specifica il numero previsto di secondi tra le partenze dalla stessa fermata in questo momento. Ad esempio, con un valore headway di 600, se perdi l'autobus dovresti aspettare dieci minuti.
  • line contiene un oggetto letterale TransitLine che contiene informazioni sulla linea di trasporto pubblico utilizzata in questo passaggio. TransitLine fornisce il nome e l'operatore della linea, insieme ad 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, il passaggio per le fermate B e C e l'arrivo 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 "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 linea, ad esempio "2" o "M14".
  • agencies è un array contenente un singolo oggetto TransitAgency. L'oggetto TransitAgency fornisce informazioni sull'operatore di questa linea, 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 il rendering delle indicazioni per il trasporto pubblico manualmente anziché utilizzare l'oggetto DirectionsRenderer, devi mostrare i nomi e gli URL delle aziende di trasporto pubblico che forniscono i risultati del percorso.

  • 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 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, hanno icone specifiche per quella linea.
  • color contiene il colore di uso comune nella segnaletica per questo trasporto pubblico. Il colore verrà specificato come stringa esadecimale, ad esempio #FF0033.
  • text_color contiene il colore del testo di uso comune per la segnaletica di questa linea. 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 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 del 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 in superficie.
VehicleType.MONORAIL Monorotaia.
VehicleType.HEAVY_RAIL Ferrovia pesante.
VehicleType.COMMUTER_TRAIN Treno pendolare.
VehicleType.HIGH_SPEED_TRAIN Treno ad alta velocità.
VehicleType.BUS Bus.
VehicleType.INTERCITY_BUS Autobus interurbano.
VehicleType.TROLLEYBUS Filobus.
VehicleType.SHARE_TAXI Il taxi condiviso è un tipo di autobus con la possibilità di far scendere e salire i passeggeri in qualsiasi punto del percorso.
VehicleType.FERRY Traghetto.
VehicleType.CABLE_CAR Un veicolo che funziona su un cavo, di solito a terra. Le funivie possono essere del tipo VehicleType.GONDOLA_LIFT.
VehicleType.GONDOLA_LIFT Una funivia.
VehicleType.FUNICULAR Un veicolo che viene trainato su un pendio ripido da un cavo. Una funicolare è in genere costituita da due carrozze, ognuna delle quali funge da contrappeso per l'altra.
VehicleType.OTHER Tutti gli altri veicoli restituiranno questo tipo.

Ispezione di DirectionsResults

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

Importante: se esegui il rendering delle indicazioni per il trasporto pubblico manualmente anziché utilizzare l'oggetto DirectionsRenderer, devi mostrare i nomi e gli URL delle aziende di trasporto pubblico che forniscono i risultati del percorso.

L'esempio seguente mostra le indicazioni a piedi per raggiungere alcune attrazioni turistiche di New York. Esaminiamo il campo DirectionsStep del percorso per aggiungere indicatori per ogni passaggio e alleghiamo le informazioni a un InfoWindow con il testo di 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 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 in Routes

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

Un waypoint è costituito dai seguenti campi:

  • location (obbligatorio) specifica l'indirizzo del waypoint.
  • stopover (facoltativo) indica se questo waypoint è una fermata effettiva lungo il percorso (true) o solo una preferenza per l'itinerario attraverso la località indicata (false). Le tappe sono true per impostazione predefinita.

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

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

L'esempio seguente calcola i percorsi tra paesi diversi negli Stati Uniti utilizzando una serie di punti di partenza, punti di arrivo e waypoint. Per selezionare più waypoint, premi Ctrl-clic quando selezioni gli elementi nell'elenco. Tieni presente che esaminiamo routes.start_address e routes.end_address per ottenere il testo per il punto di partenza e di arrivo 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;

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;

Limiti e restrizioni per i waypoint

Si applicano i seguenti limiti di utilizzo e limitazioni:

  • Il numero massimo di tappe consentite quando utilizzi il servizio Directions nell'API Maps JavaScript è 25, più l'origine e la destinazione. I limiti sono gli stessi per il servizio web API Directions (Legacy).
  • Per il servizio web API Directions (legacy), i clienti possono utilizzare 25 waypoint, oltre all'origine e alla destinazione.
  • I clienti del piano Premium di Google Maps Platform possono utilizzare 25 waypoint, oltre all'origine e alla destinazione.
  • I waypoint non sono supportati per le indicazioni per il trasporto pubblico.

Indicazioni trascinabili

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

Quando le indicazioni stradali sono trascinabili, un utente può selezionare qualsiasi punto sul percorso (o waypoint) del risultato visualizzato e spostare il componente indicato in una nuova posizione. Il DirectionsRenderer si aggiornerà dinamicamente per mostrare il percorso modificato. Al rilascio, alla mappa verrà aggiunto un waypoint di transizione (indicato da un piccolo indicatore bianco). Se selezioni e sposti un segmento di percorso, la tappa corrispondente verrà modificata, mentre se selezioni e sposti un indicatore di waypoint (inclusi i punti di partenza e di arrivo), verranno modificate le tappe del percorso che passano attraverso quel waypoint.

Poiché le indicazioni stradali trascinabili vengono modificate e visualizzate lato client, potresti voler monitorare e gestire l'evento directions_changed su DirectionsRenderer per ricevere una notifica quando l'utente ha modificato 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;

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;
Visualizza esempio