Servizio indicazioni stradali

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Panoramica

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

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

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

Per cominciare

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

Per visualizzare l'elenco delle API abilitate:

  1. Vai a Google Cloud Console.
  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.
  4. Se vedi l'API nell'elenco, non devi fare altro. Se l'API non è elencata, abilitala:
    1. Nella parte superiore della pagina, seleziona ABILITA API per visualizzare la scheda Libreria. In alternativa, seleziona Raccolta dal menu laterale a sinistra.
    2. Cerca l'API Directions, quindi selezionala dall'elenco dei risultati.
    3. Seleziona ABILITA. Al termine della procedura, viene visualizzata l'API Directions nell'elenco delle API nella Dashboard.

Prezzi e norme

Prezzi

Dal 16 luglio 2018 è entrato in vigore un nuovo piano tariffario con pagamento a consumo per Maps, Routes e Places. Per scoprire di più sui nuovi prezzi e limiti di utilizzo per l'utilizzo del servizio JavaScript Directions, consulta la sezione Utilizzo e fatturazione dell'API Directions.

Norme

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

Richieste di indicazioni stradali

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

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

Il valore letterale 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 illustrati di seguito:

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

  • waypoints[] (facoltativo) specifica un array di DirectionsWaypoint. I tappe alterano un percorso instradandolo attraverso le posizioni specificate. Un Waypoint viene specificato come un valore letterale oggetto con i campi riportati di seguito:

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

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

  • optimizeWaypoints (facoltativo) specifica che il percorso che utilizza il waypoints in dotazione può essere ottimizzato riorganizzando i tappe in un ordine più efficiente. Se true, il servizio Directions restituirà waypoints riordinati in un campo waypoint_order. Per ulteriori informazioni, consulta la sezione Utilizzo dei Waypoint nelle route di seguito.
  • provideRouteAlternatives (facoltativo) se impostato su true specifica che il servizio Directions può fornire più di un'alternativa di percorso nella risposta. Tieni presente che fornire alternative di route può aumentare il tempo di risposta dal server. Questa opzione è disponibile solo per le richieste senza tappe intermedie.
  • avoidFerries (facoltativo) se impostato su true indica che i percorsi calcolati dovrebbero evitare i traghetti, se possibile.
  • avoidHighways (facoltativo) se impostato su true indica che i percorsi calcolati dovrebbero evitare le autostrade principali, se possibile.
  • avoidTolls (facoltativo) se impostato su true indica che i percorsi calcolati dovrebbero evitare le strade a pedaggio, se possibile.
  • region (facoltativo) specifica il codice regione, specificato come valore ccTLD ("dominio di primo livello") a due caratteri. Per ulteriori informazioni, consulta la sezione Differenziazione per area geografica 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 quale modalità di trasporto utilizzare. Al momento sono supportate le seguenti modalità di viaggio:

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

Nota: le indicazioni a piedi potrebbero non includere percorsi pedonali chiari, quindi le indicazioni a piedi restituiranno avvisi nella DirectionsResult che devi visualizzare se non utilizzi la DirectionsRenderer predefinita.

Opzioni di trasporto pubblico

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

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

Il valore letterale oggetto TransitOptions contiene i seguenti campi:

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

Questi campi sono illustrati di seguito:

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

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

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

Opzioni di guida

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

L'oggetto DrivingOptions contiene i seguenti campi:

{
  departureTime: Date,
  trafficModel: TrafficModel
}

Questi campi sono illustrati di seguito:

  • departureTime (obbligatorio perché il valore letterale dell'oggetto drivingOptions sia valido) specifica l'orario di partenza desiderato come oggetto Date. Il valore deve essere impostato sull'ora corrente o su un intervallo di tempo futuro. Non può essere già una data passata. L'API converte tutte le date in UTC per garantire una gestione coerente in tutti 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 comprende drivingOptions), il percorso restituito è in genere quello corretto, senza tenere conto delle condizioni del traffico.
  • trafficModel (facoltativo) specifica le ipotesi da utilizzare durante il calcolo del tempo di traffico. Questa impostazione influisce sul valore restituito nel campo duration_in_traffic della risposta, che contiene il tempo previsto nel traffico in base alle medie storiche. Il valore predefinito è bestguess. Sono consentiti i seguenti valori:
    • bestguess (valore predefinito) indica che duration_in_traffic restituito deve essere la stima migliore del tempo di percorrenza in base alle informazioni note sulle condizioni storiche del traffico e sul traffico in tempo reale. Il traffico in tempo reale è più importante man mano che si avvicina il departureTime.
    • pessimistic indica che il valore restituito duration_in_traffic dovrebbe essere più lungo del tempo di percorrenza effettivo nella maggior parte dei giorni, anche se i giorni occasionali con condizioni del traffico particolarmente scarse possono superare questo valore.
    • optimistic indica che il valore restituito duration_in_traffic dovrebbe essere più breve del tempo di percorrenza effettivo nella maggior parte dei giorni, anche se i giorni occasionali con condizioni del traffico particolarmente buone potrebbero essere più veloci di 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'
  }
}

Unità di misura

Per impostazione predefinita, le indicazioni stradali vengono calcolate e visualizzate utilizzando il sistema di unità del paese o dell'area geografica di origine. Nota: le origini espresse utilizzando le coordinate di latitudine e longitudine anziché gli indirizzi vengono sempre impostati su unità di misura per impostazione predefinita. Ad esempio, un percorso da "Chicago, IL" a "Toronto, ONT" mostrerà i risultati in miglia, mentre il percorso inverso mostrerà i risultati in chilometri. Puoi sostituire questo sistema di unità impostandone uno in modo esplicito all'interno della richiesta utilizzando uno dei seguenti valori di UnitSystem:

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

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

Differenziazione per area geografica per indicazioni stradali

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

Puoi anche impostare il servizio Directions in modo che restituisca risultati mostrati in una regione specifica utilizzando il parametro region. Questo parametro accetta un codice di regione, specificato come sottoregione Unicode di due caratteri (non numerico). Nella maggior parte dei casi, questi tag corrispondono direttamente al valore ccTLD ("dominio di primo livello") come due caratteri, 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 (ad esempio "GB" per "Gran Bretagna").

Quando utilizzi il parametro region:

  • Specifica un solo paese o una sola area geografica. Più valori vengono ignorati e potrebbero generare una richiesta non riuscita.
  • Utilizza solo sottotag di due caratteri che utilizzano la regione (formato Unicode CLDR). Tutti gli altri input generano errori.

La differenziazione delle regioni è supportata solo per i paesi e le aree geografiche che supportano le indicazioni stradali. Consulta i dettagli della copertura di Google Maps Platform per conoscere la copertura internazionale per l'API Directions.

Indicazioni stradali di rendering

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

Stato della query delle indicazioni stradali

DirectionsStatus può restituire i seguenti valori:

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

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

Visualizzazione del DirectionsResult

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

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

  1. Crea un oggetto DirectionsRenderer.
  2. Richiama setMap() sul renderer per associarlo alla mappa passata.
  3. Chiama setDirections() sul renderer, trasmettendolo DirectionsResult come indicato in precedenza. Poiché il renderer è un tipo MVCObject, rileverà automaticamente le eventuali modifiche alle sue proprietà e aggiornerà la mappa quando le indicazioni associate vengono modificate.

L'esempio seguente calcola le indicazioni stradali tra due località su Route 66, dove l'origine e la destinazione sono impostate dai valori "start" e "end" specificati negli elenchi a discesa. L'elemento DirectionsRenderer gestisce la visualizzazione della polilinea tra le posizioni indicate e il posizionamento degli indicatori all'origine, alla destinazione e agli eventuali tappe, se 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 dell'HTML:

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

Visualizza l'esempio

L'esempio seguente mostra le indicazioni stradali utilizzando diverse modalità di viaggio tra Haight-Ashbury e Ocean Beach a San Francisco, 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 dell'HTML:

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

Visualizza l'esempio

Un elemento DirectionsRenderer non solo gestisce la visualizzazione della polilinea e di eventuali indicatori associati, ma può anche gestire la visualizzazione testuale delle indicazioni stradali come una serie di passaggi. Per farlo, chiama setPanel() sul tuo DirectionsRenderer, passando il valore <div> in cui visualizzare queste informazioni. In questo modo avrai la certezza di mostrare le informazioni di copyright appropriate ed eventuali avvisi che potrebbero essere associati al risultato.

Le indicazioni testuali vengono fornite utilizzando l'impostazione della lingua preferita del browser o la lingua specificata durante il caricamento del codice JavaScript dell'API tramite il parametro language. Per ulteriori informazioni, consulta la sezione Localizzazione. Nel caso delle indicazioni per il trasporto pubblico, l'ora viene 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 dell'HTML:

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

Visualizza l'esempio

L'oggetto DirectionsResult

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

  • geocoded_waypoints[] contiene un array di oggetti DirectionsGeocodedWaypoint, ognuno con dettagli sulla geocodifica di origine, destinazione e tappe.
  • routes[] contiene un array di oggetti DirectionsRoute. Ogni percorso indica un modo per andare dall'origine alla destinazione fornita in DirectionsRequest. In genere, viene restituita una sola route per ogni richiesta, a meno che il campo provideRouteAlternatives della richiesta non sia impostato su true, in cui è possibile restituire più route.

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

Waypoint con indicazioni geocodificate

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

DirectionsGeocodedWaypoint è un valore 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 è stato restituito almeno un codice geografico.
    • "ZERO_RESULTS" indica che la geocodifica è riuscita, ma non ha restituito risultati. Questo può verificarsi se al geocodificatore viene trasmesso un elemento address inesistente.
  • partial_match indica che il geocodificatore non ha restituito una corrispondenza esatta per la richiesta originale, anche se era in grado di corrispondere a parte dell'indirizzo richiesto. Ti consigliamo di esaminare la richiesta originale di errori ortografici e/o un indirizzo incompleto.

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

  • place_idè un identificatore univoco di un luogo, che può essere utilizzato con altre API di Google. Ad esempio, potete utilizzare place_id con la libreria API di Google Places per ottenere dettagli su un'attività locale, come numero di telefono, orari di apertura, recensioni degli utenti e altro ancora. Consulta la panoramica sull'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 restituisce "politico" che indica un'entità politica.

Indicazioni stradali

Nota: l'oggetto DirectionsTrip precedente è stato rinominato DirectionsRoute. Ricorda che ora un percorso fa riferimento all'intero percorso dall'inizio alla fine, anziché a una semplice corsa di una corsa principale.

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 eventuali tappe. Inoltre, il percorso contiene informazioni sul copyright e sugli avvisi che devono essere mostrati all'utente oltre alle informazioni sul percorso.

DirectionsRoute è un valore letterale oggetto con i seguenti campi:

  • legs[] contiene un array di oggetti DirectionsLeg, ognuno dei quali contiene informazioni su una tratta della route, da due posizioni all'interno della route specificata. Sarà presente una gamba separata per ogni tappa o destinazione specificata. Una route senza tappeti conterrà esattamente un DirectionsLeg. Ogni tratto è costituito da una serie di DirectionStep.
  • waypoint_order contiene un array che indica l'ordine di tutti i tappe nella route calcolata. Questo array può contenere un ordine alterato se DirectionsRequest è stato superato optimizeWaypoints: true.
  • overview_path contiene un array di LatLng che rappresentano un percorso approssimativo (regolato) delle indicazioni stradali risultanti.
  • overview_polyline contiene un singolo oggetto points che contiene una rappresentazione polilinea codificata della route. Questa polilinea è un percorso approssimativo (protetto) delle indicazioni stradali risultanti.
  • bounds contiene un LatLngBounds che indica i limiti della polilinea lungo questo percorso.
  • copyrights contiene il testo relativo al copyright da visualizzare per questo percorso.
  • warnings[] contiene una serie di avvisi da visualizzare quando vengono mostrate queste indicazioni. Se non utilizzi l'oggetto DirectionsRenderer fornito, devi gestire e visualizzare questi avvisi personalmente.
  • fare contiene la tariffa totale (ossia i costi totali del biglietto) per questo itinerario. Questa proprietà viene restituita solo per le richieste di trasporto pubblico e solo per i percorsi in cui sono disponibili informazioni sulle tariffe per tutte le fermate del trasporto pubblico. tra cui:
    • currency: un codice valuta ISO 4217 che indica la valuta in cui è espresso l'importo.
    • value: importo totale della tariffa nella valuta specificata sopra.

Gambe indicazioni

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

Un DirectionsLeg definisce una singola tratto di un percorso dall'origine alla destinazione nel percorso calcolato. Per i percorsi che non contengono Waypoint, il percorso sarà costituito da una "linea" ma per i percorsi che definiscono uno o più tappe, il percorso sarà composto da una o più tappe, corrispondenti ai tratti specifici del percorso.

DirectionsLeg è un valore letterale oggetto con i seguenti campi:

  • steps[] contiene un array di oggetti DirectionsStep che indicano le informazioni su ciascun passaggio separato della tratta.
  • distance indica la distanza totale coperta da questa gamba, come oggetto Distance del seguente modulo:

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

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

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

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

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

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

    • La richiesta non include i tappe. In altre parole, non sono inclusi i Waypoint in cui stopover è true.
    • La richiesta riguarda specificamente le indicazioni stradali: il mode è impostato su driving.
    • departureTime è incluso nel campo drivingOptions della richiesta.
    • Sono disponibili condizioni di traffico per il percorso richiesto.

    duration_in_traffic contiene i seguenti campi:

    • value indica la durata in secondi.
    • text contiene una rappresentazione leggibile della durata.
  • arrival_time contiene l'orario di arrivo previsto per questa tratta. Questa proprietà viene restituita solo per le indicazioni di trasporto pubblico. Il risultato viene restituito come oggetto Time con tre proprietà:
    • value la durata specificata come oggetto Date di JavaScript.
    • text: l'ora specificata come stringa. L'ora viene visualizzata nel fuso orario della fermata del trasporto pubblico.
    • time_zone contiene il fuso orario di questa stazione. Il valore è il nome del fuso orario definito nel database dei fusi orari IANA , ad esempio "America/New_York".
  • departure_time contiene l'orario di partenza stimato per questa tratta, specificato come oggetto Time. Il departure_time è disponibile solo per le indicazioni di trasporto pubblico.
  • start_location contiene LatLng dell'origine di questa gamba. Dato che il servizio web di indicazioni stradali calcola le indicazioni stradali tra le varie località utilizzando l'opzione di trasporto più vicina (di solito una strada) nei punti di partenza e di arrivo, start_location potrebbe essere diverso dall'origine fornita di questo tratto se, ad esempio, una strada non è vicino all'origine.
  • end_location contiene l'elemento LatLng della destinazione di questa gamba. Dato che DirectionsService calcola le indicazioni stradali tra le varie 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 specificata di questo tratto se, ad esempio, una strada non è vicino alla destinazione.
  • start_address contiene l'indirizzo leggibile (in genere un indirizzo civico) all'inizio di questa gamba.

    Questi contenuti devono essere letti così come sono. Non analizzare l'indirizzo formattato in modo programmatico.
  • end_address contiene l'indirizzo leggibile (in genere un indirizzo civico) alla fine di questa gamba.

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

Indicazioni stradali

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

Quando si utilizza il servizio Indicazioni stradali per cercare indicazioni stradali con mezzi pubblici, l'array di passi include ulteriori informazioni specifiche sul trasporto pubblico sotto forma di oggetto transit. Se le indicazioni stradali includono più modalità di trasporto, verranno fornite indicazioni dettagliate per i percorsi a piedi o in auto in un array steps[]. Ad esempio, un passaggio a piedi includerà le indicazioni stradali dalle posizioni di partenza e di arrivo: "Cammina verso Innes Ave e Fitch St". Tale passaggio includerà indicazioni a piedi dettagliate per quel percorso nell'array di steps[], come: "Punta a nord-ovest", "Svolgi a sinistra su Arelious Walker" e "Svolgi a sinistra su Innes Ave".

DirectionsStep è un valore letterale oggetto con i seguenti campi:

  • instructions contiene le istruzioni per questo passaggio in una stringa di testo.
  • distance contiene la distanza percorsa da questo passaggio fino al passaggio successivo, come oggetto Distance. Vedi la descrizione di DirectionsLeg qui 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, come oggetto Duration. Vedi la descrizione di DirectionsLeg sopra. Questo campo potrebbe non essere definito se la durata è sconosciuta.
  • start_location contiene il LatLng geocodificato del punto iniziale 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. Questa polilinea è un percorso approssimativo (protetto) del passaggio.
  • steps[] è un valore letterale di oggetto DirectionsStep che contiene le indicazioni dettagliate per raggiungere la tua meta a piedi o in auto nelle indicazioni per il trasporto pubblico. I passaggi secondari sono disponibili solo per le indicazioni stradali relative al 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 di trasporto pubblico.
  • path contiene un array di LatLngs che descrive il corso di questo passaggio.
  • transit contiene informazioni specifiche sul trasporto pubblico, ad esempio gli orari di arrivo e di partenza e il nome della linea di trasporto pubblico.

Informazioni specifiche sul trasporto pubblico

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 sul trasporto pubblico

L'oggetto TransitDetails espone le seguenti proprietà:

  • arrival_stop contiene un oggetto TransitStop che rappresenta la stazione di arrivo/fermata con le seguenti proprietà:
    • name il nome della stazione/della fermata del trasporto pubblico. Ad esempio: "Quadrato dell'Unione".
    • location la posizione della fermata/della fermata di trasporto pubblico, rappresentata come un LatLng.
  • departure_stop contiene un oggetto TransitStop che rappresenta la stazione di partenza/fermata.
  • arrival_time contiene l'ora di arrivo, specificata come oggetto Time con tre proprietà:
    • value la durata specificata come oggetto Date di JavaScript.
    • text: l'ora specificata come stringa. L'ora viene visualizzata nel fuso orario della fermata del trasporto pubblico.
    • time_zone contiene il fuso orario di questa stazione. Il valore è il nome del fuso orario definito nel database dei fusi orari IANA , ad esempio "America/New_York".
  • departure_time contiene l'orario di partenza, specificato come oggetto Time.
  • headsign specifica la direzione in cui viaggiare su questa linea, poiché è contrassegnata sul veicolo o alla fermata di partenza. Spesso sarà la stazione terminale.
  • 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, ti aspetteresti un'attesa di dieci minuti se dovessi perdere l'autobus.
  • line contiene un valore letterale oggetto TransitLine che contiene informazioni sulla linea di trasporto pubblico utilizzata in questo passaggio. TransitLine fornisce il nome e l'operatore della riga, insieme ad altre proprietà descritte nella documentazione di riferimento di TransitLine.
  • num_stops contiene il numero di fermate in questo passaggio. Include la fermata dell'arrivo, ma non la fermata della partenza. Ad esempio, se le indicazioni stradali prevedono la partenza dalla fermata A, il passaggio tra le fermate B e C e l'arrivo alla fermata D, num_stops restituisce 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 è 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, comprese le seguenti proprietà:
    • name contiene il nome dell'azienda di trasporto pubblico.
    • phone contiene il numero di telefono dell'azienda di trasporto pubblico.
    • url contiene l'URL dell'azienda di trasporto pubblico.

    Nota: se esegui manualmente il rendering delle indicazioni per il trasporto pubblico anziché utilizzare l'oggetto DirectionsRenderer, devi visualizzare i nomi e gli URL delle aziende di trasporto pubblico al servizio dei risultati delle corse.

  • url contiene un URL per questa linea di trasporto pubblico come fornito dall'azienda di trasporto pubblico.
  • icon contiene un URL per l'icona associata a questa riga. La maggior parte delle città utilizza icone generiche che variano in base al tipo di veicolo. Alcune linee di trasporto pubblico, come la metropolitana di New York, hanno icone specifiche per ciascuna linea.
  • color contiene il colore comunemente utilizzato per la segnaletica di 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 riga. Il colore verrà specificato come stringa esadecimale.
  • vehicle contiene un oggetto Vehicle che include le seguenti proprietà:
    • name contiene il nome del veicolo su questa linea. Ad esempio: " Metropolitana"
    • 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 per i 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.
VehicleType.TRAM Metropolitana leggera sopra il suolo.
VehicleType.MONORAIL Monorotaia.
VehicleType.HEAVY_RAIL Treni pesanti.
VehicleType.COMMUTER_TRAIN Treni suburbani.
VehicleType.HIGH_SPEED_TRAIN Treno ad alta velocità.
VehicleType.BUS Autobus.
VehicleType.INTERCITY_BUS Autobus interurbano.
VehicleType.TROLLEYBUS Filobus.
VehicleType.SHARE_TAXI Il servizio di taxi condiviso è una sorta di autobus con la possibilità di scendere e prendere i passeggeri ovunque sul percorso.
VehicleType.FERRY Traghetto.
VehicleType.CABLE_CAR Un veicolo che funziona su un cavo, solitamente a terra. Le funivie aeree possono essere del tipo VehicleType.GONDOLA_LIFT.
VehicleType.GONDOLA_LIFT Una funivia.
VehicleType.FUNICULAR Veicolo in salita su una pendenza tramite un cavo. Una funicolare è composta in genere da due auto, ciascuna delle quali funge da contrappeso per l'altra.
VehicleType.OTHER Tutti gli altri veicoli restituiranno questo tipo.

Ispezione DirectionsResults

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

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

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

Nota: poiché calcoliamo le indicazioni a piedi, mostriamo anche eventuali avvisi all'utente in un riquadro <div> separato.

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

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

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

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

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

function calcRoute() {

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

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

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

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

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

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

Nel corpo dell'HTML:

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

Visualizza l'esempio

Utilizzo dei Waypoint nei percorsi

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 di trasporto pubblico. I Waypoint consentono di calcolare i percorsi mediante luoghi aggiuntivi, 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 tappe è una fermata effettiva sul percorso (true) o solo una preferenza per percorrere la località specificata (false). Gli scali sono true per impostazione predefinita.

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

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

L'esempio seguente calcola i percorsi per più paesi negli Stati Uniti utilizzando una serie di punti di partenza, punti di arrivo e tappe. Per selezionare più tappe, premi Ctrl e fai clic quando selezioni elementi nell'elenco. Tieni presente che esaminiamo routes.start_address e routes.end_address per fornire il testo per i punti di partenza e di arrivo di ciascun 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 relativi ai tappe

Si applicano i seguenti limiti e limiti di utilizzo:

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

Indicazioni trascinabili

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

Se le indicazioni stradali sono trascinabili, un utente può selezionare un punto del percorso (o un Waypoint) del risultato visualizzato e spostare il componente indicato in una nuova posizione. DirectionsRenderer si aggiornerà in modo dinamico per mostrare il percorso modificato. Dopo il rilascio, verrà aggiunto alla mappa un Waypoint di transizione (indicato da un piccolo indicatore bianco). La selezione e lo spostamento di un tratto di percorso altera il percorso del percorso, mentre la selezione e lo spostamento di un indicatore di percorso (inclusi i punti di partenza e di arrivo) alterano le parti del percorso che attraversano tale punto.

Poiché le direzioni trascinabili sono 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 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 tratte 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 l'esempio

Prova Esempio