Servizio Indicazioni

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

Panoramica

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

Quando specifichi la stazione di partenza o di arrivo 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 può restituire indicazioni stradali suddivise in più parti utilizzando una serie di waypoint. Le indicazioni stradali vengono visualizzate come polilinea che traccia il percorso su una mappa oppure come una serie di descrizioni testuali all'interno di un elemento <div> (ad es. "Svolta a destra sulla rampa del ponte di Williamsburg").

Per iniziare

Prima di utilizzare il servizio Directions nell'API Maps JavaScript, assicurati innanzitutto che l'API Directions (legacy) sia attivata nella console Google Cloud, nello stesso progetto 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, poi 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 vedi l'API 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 informazioni sui prezzi e sulle norme di utilizzo del servizio di indicazioni stradali JavaScript, consulta Utilizzo e fatturazione per l'API Directions (legacy).

Norme

L'utilizzo del servizio Indicazioni deve essere conforme alle norme descritte per l'API Indicazioni (legacy).

Richieste di indicazioni stradali

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

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 Indicazioni stradali, passando un valore letterale dell'oggetto DirectionsRequest contenente i termini di input e un metodo di callback da eseguire al ricevimento della risposta.

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

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

Questi campi sono descritti di seguito:

  • origin (obbligatorio) specifica la posizione di partenza da cui calcolare le indicazioni stradali. Questo valore può essere specificato come String (ad esempio "Chicago, IL"), come valore LatLng o come oggetto Place. Se utilizzi un oggetto Place, puoi specificare un ID luogo, una stringa di query o una 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 indicazioni stradali.
  • destination (obbligatorio) specifica la destinazione 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 calcolare le indicazioni stradali. I valori validi sono specificati in Modalità di viaggio di seguito.
  • transitOptions (facoltativo) specifica 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 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 Unit Systems di seguito.

  • waypoints[] (facoltativo) specifica un array di DirectionsWaypoint. I waypoint modificano un percorso passando per le posizioni specificate. Un waypoint viene specificato come un letterale oggetto con i campi riportati 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 fermata è una fermata lungo il percorso, con il risultato di suddividere il percorso in due percorsi.

    Per ulteriori informazioni sui waypoint, vedi Utilizzare i waypoint nelle route di seguito.

  • optimizeWaypoints (facoltativo) specifica che il percorso che utilizza waypoints fornito può essere ottimizzato riordinando i waypoint in un ordine più efficiente. Se true, il servizio Indicazioni restituirà il waypoints riordinato in un campo waypoint_order. Per ulteriori informazioni, consulta la sezione Utilizzare le tappe nelle route riportata di seguito.
  • provideRouteAlternatives (facoltativo) se impostato su true specifica che il servizio Indicazioni può fornire più di un percorso alternativo nella risposta. Tieni presente che fornire alternative di percorso potrebbe aumentare il tempo di risposta del server. Questa opzione è disponibile solo per le richieste senza waypoint intermedi.
  • avoidFerries (facoltativo) se impostato su true indica che gli itinerari calcolati devono evitare i traghetti, se possibile.
  • avoidHighways (facoltativo) se impostato su true indica che gli itinerari calcolati devono evitare, se possibile, le autostrade principali.
  • 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, specificato come valore di due caratteri di un ccTLD ("dominio di primo livello"). Per ulteriori informazioni, consulta Bias di regione di seguito.

Di seguito è riportato un DirectionsRequest di esempio:

{
  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 linee di trasporto pubblico.
  • WALKING richiede indicazioni stradali per camminare 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 quel tipo di indicazioni non è disponibile, la risposta restituirà DirectionsStatus="ZERO_RESULTS".

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

Opzioni di trasporto pubblico

Le opzioni disponibili per una richiesta di indicazioni stradali variano in base alle modalità di viaggio. Quando richiedi indicazioni stradali per i trasporti pubblici, le opzioni avoidHighways, avoidTolls, waypoints[] e optimizeWaypoints verranno ignorate. Puoi specificare opzioni di routing specifiche per i trasporti pubblici tramite il TransitOptions valore letterale dell'oggetto.

Le indicazioni stradali con mezzi pubblici sono soggette a variazioni nel tempo. Le indicazioni stradali verranno restituite solo per i periodi futuri.

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

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

Questi campi sono descritti di seguito:

  • arrivalTime (facoltativo) specifica l'ora di arrivo preferita come oggetto Date. Se viene specificato l'orario di arrivo, l'orario di partenza viene ignorato.
  • departureTime (facoltativo) specifica l'ora di partenza preferita come oggetto Date. Il valore departureTime verrà ignorato se viene specificato arrivalTime. Il valore predefinito è la data e l'ora attuali se non viene specificato alcun valore per departureTime o arrivalTime.
  • modes[] (facoltativo) è un array contenente uno o più literali 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 deve privilegiare i viaggi 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 privilegiare i viaggi in metropolitana.
    • TRAIN indica che il percorso calcolato deve preferire i viaggi in treno.
    • TRAM indica che il percorso calcolato deve privilegiare i viaggi in tram e metropolitana leggera.
  • routingPreference (facoltativo) specifica le preferenze per i percorsi con il trasporto pubblico. Con 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 trasferimenti.
    • LESS_WALKING indica che il percorso calcolato deve preferire tratti a piedi limitati.

Di seguito è riportato un esempio di DirectionsRequest per 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 descritti di seguito:

  • departureTime (obbligatorio per la validità del literale dell'oggetto drivingOptions) specifica l'ora di partenza desiderata come oggetto Date. Il valore deve essere impostato sull'ora corrente o su un momento futuro. Non può essere nel passato. L'API converte tutte le date in UTC per garantire un'elaborazione 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 di traffico previste al momento e include il tempo di percorrenza previsto nel traffico (duration_in_traffic) nella risposta. Se non specifichi un'ora di partenza (ovvero se la richiesta non include drivingOptions), il percorso restituito è in genere buono, ma non tiene conto delle condizioni del traffico.
  • trafficModel (facoltativo) specifica le ipotesi da utilizzare per calcolare il 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 il valore duration_in_traffic restituito deve essere la stima migliore del tempo di percorrenza in base alle informazioni note sulle condizioni del traffico storiche e in tempo reale. Il traffico in tempo reale diventa più importante quanto più prossimo è il giorno departureTime.
    • 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 di traffico particolarmente difficili questo valore può 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 di traffico particolarmente buone il tempo di percorrenza può essere inferiore a questo valore.

Di seguito è riportato un DirectionsRequest di esempio 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 coordinate di latitudine/longitudine anziché indirizzi sono sempre predefinite in unità metriche. 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 override 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 indicate in chilometri.
  • UnitSystem.IMPERIAL specifica l'utilizzo del sistema imperiale (inglese). Le distanze sono indicate in miglia.

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

Bias di regione per le indicazioni stradali

Il servizio Indicazioni dell'API 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 dominio supportato diverso, i risultati saranno influenzati da quel dominio. Ad esempio, le ricerche di "San Francisco" possono restituire risultati diversi se le applicazioni vengono caricate https://maps.googleapis.com/ (Stati Uniti) rispetto a una caricata http://maps.google.es/ (Spagna).

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

Quando utilizzi il parametro region:

  • Specifica un solo paese o una sola regione. I valori multipli vengono ignorati e potrebbero comportare un errore nella richiesta.
  • Utilizza solo sottotag di regione di due caratteri (formato Unicode CLDR). Tutti gli altri input causeranno errori.

La predisposizione per regione è supportata solo per i paesi e le regioni che supportano le indicazioni. Consulta la pagina Dettagli sulla copertura di Google Maps Platform per visualizzare la copertura internazionale dell'API Directions (legacy).

Istruzioni per il rendering

L'avvio di una richiesta di indicazioni stradali al servizio DirectionsService con il metodo route() richiede il passaggio di un callback che viene eseguito al termine della richiesta di servizio. Questo callback restituirà un codice 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 almeno una delle località specificate come origine, destinazione o punto di passaggio della richiesta non è stata geocodificata.
  • 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 nel 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 in cui mancano l'origine o la destinazione oppure una richiesta per i trasporti pubblici che include i 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 a causa di un errore del server. La richiesta potrebbe essere andata a buon fine se provi di nuovo.

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

Visualizzazione di DirectionsResult

DirectionsResult contiene il risultato della query di 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 procedere come segue:

  1. Crea un oggetto DirectionsRenderer.
  2. Chiama setMap() sul visualizzatore per associarlo alla mappa passata.
  3. Chiama setDirections() sul renderer, passandogli DirectionsResult come indicato sopra. Poiché il visualizzatore è un MVCObject, rileva automaticamente qualsiasi modifica alle sue proprietà e aggiorna la mappa quando le indicazioni 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 del polilinea tra le località indicate e il posizionamento degli indicatori all'origine, alla destinazione e a eventuali waypoint, se applicabili.

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

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

Nel corpo 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 che utilizzano diversi modi di spostamento 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 DirectionsRenderer non gestisce solo la visualizzazione del 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, passandogli il <div> in cui visualizzare queste informazioni. In questo modo, ti assicurerai anche di mostrare le informazioni sul copyright appropriate e eventuali avvisi associati al risultato.

Le indicazioni testuali verranno fornite utilizzando l'impostazione della lingua preferita del browser o la lingua specificata al caricamento dell'API JavaScript utilizzando il parametro language. Per ulteriori informazioni, consulta Localizzazione. Nel caso delle indicazioni per i trasporti pubblici, l'ora verrà visualizzata nel fuso orario della 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 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

Oggetto DirectionsResult

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

  • geocoded_waypoints[] contiene un array di oggetti DirectionsGeocodedWaypoint, ognuno contenente dettagli sul geocoding di partenza, destinazione e waypoint.
  • routes[] contiene un array di oggetti DirectionsRoute. Ogni percorso indica un modo per arrivare dalla stazione di partenza a quella di destinazione indicata 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 possono essere restituiti più percorsi.

Nota:la proprietà via_waypoint è ritirata nei percorsi alternativi. La versione 3.27 è l'ultima versione dell'API che aggiunge punti di passaggio aggiuntivi nei percorsi alternativi. Per le versioni 3.28 e successive dell'API, puoi continuare a implementare le indicazioni trascinabili utilizzando il servizio Indicazioni 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 per le indicazioni stradali

Un DirectionsGeocodedWaypoint contiene dettagli sul geocodice di partenza, destinazione e waypoint.

DirectionsGeocodedWaypoint è un letterale 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 almeno un codice geografico è stato restituito.
    • "ZERO_RESULTS" indica che la geocodifica è andata a buon fine, ma non ha restituito risultati. Ciò può verificarsi 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 gli indirizzi che non esistono nella località specificata nella richiesta. Possono essere riportate anche corrispondenze parziali 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 scritto male, il servizio di geocodifica potrebbe suggerire un indirizzo alternativo. Anche i suggerimenti attivati in questo modo verranno contrassegnati 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 Maps per ottenere i dettagli di un'attività locale, come numero di telefono, orari 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 codice geografico di "Chicago" restituisce "località", che indica che "Chicago" è una città, e anche "politico", che indica che si tratta di un'entità politica.

Percorsi indicazioni stradali

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

Un DirectionsRoute contiene un singolo risultato proveniente da l'origine e la destinazione specificate. Questo percorso può essere costituito da uno o più tratti (di tipo DirectionsLeg), a seconda che siano stati specificati waypoint. Inoltre, il percorso contiene anche informazioni sul copyright e avvisi che devono essere mostrati all'utente, oltre alle informazioni di routing.

DirectionsRoute è un letterale oggetto con i seguenti campi:

  • legs[] contiene un array di oggetti DirectionsLeg, ciascuno dei quali contiene informazioni su una tappa del percorso, da due località all'interno del percorso specificato. Verrà presente un tratto separato per ogni waypoint o destinazione specificato. Un itinerario senza waypoint conterrà esattamente un DirectionsLeg. Ogni tratto è costituito da una serie di DirectionStep.
  • waypoint_order contiene un array che indica l'ordine di eventuali waypoint nel percorso calcolato. Questo array potrebbe contenere un ordine alterato se è stato passato DirectionsRequest. optimizeWaypoints: true.
  • overview_path contiene un array di LatLng che rappresentano un percorso approssimativo (appiattito) delle indicazioni risultanti.
  • overview_polyline contiene un singolo oggetto points che contiene una rappresentazione del percorso con polilinee codificate. Questa polilinea è un percorso approssimativo (appiattito) delle indicazioni stradali risultanti.
  • bounds contiene un LatLngBounds che indica i confini del polilinea lungo questo determinato percorso.
  • copyrights contiene il testo del copyright da visualizzare per questo percorso.
  • 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 autonomamente questi avvisi.
  • fare contiene la tariffa totale (ovvero il costo totale del biglietto) per questa tratta. Questa proprietà viene restituita solo per le richieste di trasporto pubblico e solo per i percorsi in cui sono disponibili informazioni sulle tariffe per tutte le tratte. 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.

Gambe per indicazioni

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

Un DirectionsLeg definisce un singolo tratto di un viaggio dall'origine alla destinazione nel percorso calcolato. Per i percorsi che non contengono waypoint, il percorso sarà costituito da un singolo "tratto", mentre per i percorsi che definiscono uno o più waypoint, il percorso sarà costituito da uno o più tratti, corrispondenti ai tratti specifici del viaggio.

DirectionsLeg è un letterale oggetto 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 percorsa da questo tratto, come oggetto Distance del seguente modulo:

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

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

  • duration indica la durata totale di questo tratto, come oggetto Duration del seguente modulo:

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

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

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

    • La richiesta non include i waypoint di sosta. In altre parole, non include i waypoint 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 il percorso richiesto.

    duration_in_traffic contiene i seguenti campi:

    • value indica la durata in secondi.
    • text contiene una rappresentazione della durata in formato leggibile.
  • arrival_time contiene l'orario di arrivo stimato per questo tratto. 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'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 come definito nel database dei fusi orari IANA, ad es. "America/New_York".
  • departure_time contiene l'orario di partenza stimato per questo tratto, specificato come oggetto Time. departure_time è disponibile solo per le indicazioni per il trasporto pubblico.
  • start_location contiene il LatLng dell'origine di questo tratto. Poiché il servizio web di indicazioni stradali 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 diversa dall'origine fornita di questo tratto se, ad esempio, una strada non si trova nelle vicinanze dell'origine.
  • end_location contiene il LatLng della destinazione di questo tratto. Poiché DirectionsService calcola le indicazioni stradali tra le località utilizzando la modalità di trasporto più vicina (di solito una strada) nei punti di partenza e di arrivo, DirectionsService potrebbe essere diversa dalla destinazione indicata per questo tratto se, ad esempio, non c'è una strada nelle vicinanze della destinazione.end_location
  • start_address contiene l'indirizzo leggibile (in genere un indirizzo stradale) dell'inizio di questo tratto.

    Questi contenuti devono essere letti così come sono. Non analizzare tramite programma l'indirizzo formato.
  • end_address contiene l'indirizzo leggibile (in genere un indirizzo stradale) della fine di questo tratto.

    Questi contenuti devono essere letti così come sono. Non analizzare tramite programma l'indirizzo formato.

Passaggi per le indicazioni stradali

Un DirectionsStep è l'unità più atomica del percorso di una direzione, contenente un singolo passaggio che descrive una singola istruzione specifica del tragitto. Ad esempio, "Svolta a sinistra in W. 4th St." Il passaggio non descrive solo l'istruzione, ma contiene anche informazioni su distanza e durata relative al rapporto tra questo passaggio e quello successivo. Ad esempio, un passaggio denominato "Inserisciti sulla I-80 ovest" potrebbe contenere una durata di "59 km" e "40 minuti", a indicare che il passaggio successivo è a 59 km/40 minuti da questo.

Quando utilizzi il servizio Percorsi per cercare indicazioni per i trasporti pubblici, l'array di passaggi includerà ulteriori informazioni specifiche sui trasporti pubblici sotto forma di oggetto transit. Se le indicazioni stradali 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 destinazione: "A piedi fino a Innes Ave e Fitch St". Questo passaggio includerà indicazioni stradali dettagliate per il percorso nell'array steps[] , ad esempio: "Vai a nord-ovest", "Svolta a sinistra in Arelious Walker" e "Svolta a sinistra in Innes Ave".

DirectionsStep è un letterale oggetto 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. (vedi la descrizione in DirectionsLeg sopra). Questo campo può essere non definito se la distanza è sconosciuta.
  • duration contiene una stima del tempo necessario per eseguire il passaggio fino al passaggio successivo come oggetto Duration. (vedi la descrizione in DirectionsLeg sopra). Questo campo può essere non definito se la durata è sconosciuta.
  • start_location contiene il valore geocodificato LatLng del punto di partenza di questo passaggio.
  • end_location contiene il LatLng del punto finale di questo passaggio.
  • polyline contiene un singolo oggetto points che contiene una rappresentazione polilinea codificata del passaggio. Questo polilinea è un percorso approssimativo (appiattito) del passaggio.
  • steps[] un literal oggetto DirectionsStep che contiene indicazioni dettagliate per i passaggi a piedi o in auto nelle indicazioni per i trasporti pubblici. I passaggi secondari sono disponibili solo per le indicazioni per i trasporti pubblici.
  • travel_mode contiene il TravelMode utilizzato in questo passaggio. Le indicazioni per i trasporti pubblici possono includere una combinazione di indicazioni a piedi e per i trasporti pubblici.
  • path contiene un array di LatLngs che descrive il corso di questo passaggio.
  • transit contiene informazioni specifiche sui trasporti pubblici, ad esempio le ore di arrivo e di partenza e il nome della linea.

Informazioni specifiche sui trasporti pubblici

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

Dettagli sui trasporti pubblici

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: "Union Square".
    • location la posizione della stazione/fermata del trasporto pubblico, 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'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 come definito nel database dei fusi orari IANA, ad es. "America/New_York".
  • departure_time contiene l'ora di partenza, specificata come oggetto Time.
  • headsign specifica la direzione di marcia su questa linea, come indicato sul veicolo o alla fermata di partenza. Spesso si tratta della stazione di destinazione.
  • headway, se disponibile, specifica il numero previsto di secondi tra le partenze dalla stessa fermata in questo momento. Ad esempio, con un valore headway pari a 600, dovresti aspettarti un'attesa di dieci minuti se dovessi perdere l'autobus.
  • line contiene un valore letterale dell'oggetto TransitLine che contiene informazioni sulla linea di trasporto pubblico utilizzata in questo passaggio. TransitLine fornisce il nome e l'operatore della riga, insieme ad altre proprietà descritte nella documentazione di riferimento di TransitLine.
  • num_stops contiene il numero di fermate in questo passaggio. Sono incluse la fermata di arrivo, ma non quella di partenza. Ad esempio, se le indicazioni stradali prevedono di partire dalla fermata A, passare per le fermate B e C e arrivare alla fermata D, num_stops restituirà 3.

Linea di trasporto pubblico

L'oggetto TransitLine espone le seguenti proprietà:

  • name contiene il nome completo della 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, tra cui 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 rendi visibili le indicazioni per i trasporti pubblici manualmente anziché utilizzare l'oggetto DirectionsRenderer, devi mostrare i nomi e gli URL delle aziende di trasporto pubblico che coprono 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 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.
  • color contiene il colore comunemente utilizzato nella segnaletica per questo servizio di 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 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 riga. Ad esempio: "Metro."
    • type contiene il tipo di veicolo utilizzato su questa linea. Per un elenco completo dei valori supportati, consulta la documentazione relativa a Tipo di veicolo.
    • 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 dei trasporti locali.

Tipo di veicolo

L'oggetto VehicleType espone le seguenti proprietà:

Valore Definizione
VehicleType.RAIL Ferrovia.
VehicleType.METRO_RAIL Metropolitana leggera.
VehicleType.SUBWAY Metropolitana leggera sotterranea.
VehicleType.TRAM Metropolitana leggera sopraelevata.
VehicleType.MONORAIL Monorotaia.
VehicleType.HEAVY_RAIL Treni pesanti.
VehicleType.COMMUTER_TRAIN Treno suburbano.
VehicleType.HIGH_SPEED_TRAIN Treno ad alta velocità.
VehicleType.BUS Autobus.
VehicleType.INTERCITY_BUS Autobus interurbano.
VehicleType.TROLLEYBUS Filobus.
VehicleType.SHARE_TAXI Il taxi condiviso è un tipo di autobus che può far scendere e salire i passeggeri ovunque lungo il percorso.
VehicleType.FERRY Traghetto.
VehicleType.CABLE_CAR Un veicolo che funziona su un cavo, di solito a terra. Le funivie possono essere di tipo VehicleType.GONDOLA_LIFT.
VehicleType.GONDOLA_LIFT Una funivia.
VehicleType.FUNICULAR Un veicolo che viene tirato su una ripida salita da un cavo. Una funicolare è costituita in genere da due vetture, ciascuna delle quali funge da contrappeso per l'altra.
VehicleType.OTHER Tutti gli altri veicoli restituiranno questo tipo.

Inspecting DirectionsResults

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

Importante: se rendi dinamicamente le indicazioni per i trasporti pubblici manualmente anziché utilizzare l'oggetto DirectionsRenderer, devi mostrare i nomi e gli URL delle aziende di trasporto pubblico che servono i risultati della corsa.

L'esempio seguente traccia le indicazioni stradali per alcune attrazioni turistiche di New York. Esaminiamo il DirectionsStep del percorso per aggiungere indicatori per ogni passaggio e alleghiamo informazioni a un InfoWindow con il testo delle istruzioni per quel passaggio.

Nota: poiché stiamo calcolando le indicazioni stradali per le passeggiate, 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

Utilizzare i waypoint in Routes

Come indicato in DirectionsRequest, puoi anche specificare waypoint (di tipo DirectionsWaypoint) quando calcolhi i percorsi utilizzando il servizio Indicazioni per le indicazioni stradali a piedi, in bicicletta o in auto. I waypoint non sono disponibili per le indicazioni per i trasporti pubblici. I waypoint ti consentono di calcolare i percorsi attraverso altre località, nel qual caso il percorso restituito passa per 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 sul percorso (true) o solo una preferenza per il percorso attraverso la località indicata (false). Per impostazione predefinita, le soste intermedie sono true.

Per impostazione predefinita, il servizio Indicazioni calcola un itinerario tramite i waypoint forniti nell'ordine specificato. Se vuoi, puoi passare optimizeWaypoints: true all'interno di DirectionsRequest per consentire al servizio Indicazioni di ottimizzare il percorso fornito riordinando le tappe in un ordine più efficiente. Questa ottimizzazione è un'applicazione del problema del commesso viaggiatore. Il tempo di percorrenza è il fattore principale ottimizzato, ma altri fattori come distanza, numero di svolte e molti altri possono essere presi in considerazione per decidere quale percorso è il più efficiente. Tutti i waypoint devono essere fermate per consentire al servizio Indicazioni di ottimizzare il percorso.

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

L'esempio seguente calcola i percorsi transcontinentali negli Stati Uniti utilizzando una serie di punti di partenza, di arrivo e di passaggio. 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 fornirci il testo del 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;
index.ts

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 waypoint consentiti quando si utilizza il servizio Percorsi nell'API Maps JavaScript è 25, oltre all'origine e alla destinazione. I limiti sono gli stessi per il servizio web API Directions (legacy).
  • Per il servizio web dell'API Directions (legacy), i clienti possono inserire 25 punti intermedi, oltre all'origine e alla destinazione.
  • I clienti con un piano Premium di Google Maps Platform possono utilizzare 25 waypoint, oltre all'origine e alla destinazione.
  • Le tappe non sono supportate per le indicazioni stradali per il trasporto pubblico.

Indicazioni stradali trascinabili

Gli utenti possono modificare le indicazioni stradali per biciclette, 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 visualizzatore consente di trascinare le indicazioni impostando la relativa proprietà draggable su true. Le indicazioni per i trasporti pubblici non possono essere trascinate.

Quando le indicazioni stradali sono trascinabili, un utente può selezionare un punto qualsiasi del percorso (o del punto di passaggio) del risultato visualizzato e spostare il componente indicato in una nuova posizione. DirectionsRenderer verrà aggiornato dinamicamente per mostrare il percorso modificato. Al momento del rilascio, alla mappa verrà aggiunto un waypoint di transizione (indicato da un piccolo indicatore bianco). La selezione e lo spostamento di un segmento del percorso modificheranno la relativa tappa, mentre la selezione e lo spostamento di un indicatore di waypoint (inclusi i punti di partenza e di arrivo) modificheranno le tappe del percorso che passano per quel waypoint.

Poiché le indicazioni stradali trascinabili vengono modificate e visualizzate lato client, ti consigliamo di 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 viaggio.

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

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

Prova Sample