Servizio di matrice delle distanze

Nota: librerie lato server

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

Panoramica

Consulta anche il riferimento per l'API Maps JavaScript: Matrice delle distanze

Il servizio Distance Matrix di Google calcola la distanza e la durata del viaggio tra più origini e destinazioni utilizzando una determinata modalità di viaggio.

Questo servizio non restituisce informazioni dettagliate sul percorso. Le informazioni sul percorso, comprese polilinee e indicazioni testuali, possono essere ottenute passando l'origine e la destinazione desiderate al Directions Service.

Come iniziare

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

Per visualizzare l'elenco delle API abilitate:

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

Prezzi e norme

Prezzi

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

Nota: ogni query inviata al servizio Matrice delle distanze è limitata dal numero di elementi consentiti, dove il numero di origini moltiplicato per il numero di destinazioni definisce il numero di elementi.

Criteri

L'utilizzo del servizio Distanza Matrix deve essere conforme ai criteri descritti per l'API Distanza Matrix.

Richieste della matrice delle distanze

L'accesso al servizio Distanza Matrix è asincrono, in quanto l'API di Google Maps deve effettuare una chiamata a un server esterno. Per questo motivo, devi passare un metodo di callback da eseguire al termine della richiesta ed elaborare i risultati.

Puoi accedere al servizio Distanza Matrix all'interno del tuo codice tramite l'oggetto del costruttore google.maps.DistanceMatrixService. Il metodo DistanceMatrixService.getDistanceMatrix() avvia una richiesta al servizio Matrice delle distanze, passandogli un valore letterale oggetto DistanceMatrixRequest contenente le origini, le destinazioni e la modalità di viaggio, nonché un metodo di callback da eseguire alla ricezione della risposta.

var origin1 = new google.maps.LatLng(55.930385, -3.118425);
var origin2 = 'Greenwich, England';
var destinationA = 'Stockholm, Sweden';
var destinationB = new google.maps.LatLng(50.087692, 14.421150);

var service = new google.maps.DistanceMatrixService();
service.getDistanceMatrix(
  {
    origins: [origin1, origin2],
    destinations: [destinationA, destinationB],
    travelMode: 'DRIVING',
    transitOptions: TransitOptions,
    drivingOptions: DrivingOptions,
    unitSystem: UnitSystem,
    avoidHighways: Boolean,
    avoidTolls: Boolean,
  }, callback);

function callback(response, status) {
  // See Parsing the Results for
  // the basics of a callback function.
}

Visualizza esempio

DistanceMatrixRequest contiene i seguenti campi:

• origins (obbligatorio): un array contenente una o più stringhe di indirizzo, oggetti google.maps.LatLng o oggetti Place da cui calcolare distanza e tempo.
• destinations (obbligatorio): un array contenente una o più stringhe di indirizzo, oggetti google.maps.LatLng o oggetti Place in cui calcolare distanza e tempo.
• travelMode (facoltativo): la modalità di trasporto da utilizzare per il calcolo delle indicazioni stradali. Consulta la sezione sulle modalità di viaggio.
• transitOptions (facoltativo): opzioni che si applicano solo alle richieste in cui travelMode è TRANSIT. I valori validi sono descritti nella sezione relativa alle opzioni di trasporto pubblico.
• drivingOptions (facoltativo) specifica i valori che si applicano solo alle richieste in cui travelMode è DRIVING. I valori validi sono descritti nella sezione Opzioni di guida.
• unitSystem (facoltativo): il sistema di unità da utilizzare per visualizzare la distanza. I valori accettati sono:
  • google.maps.UnitSystem.METRIC (valore predefinito)
  • google.maps.UnitSystem.IMPERIAL
• avoidHighways (facoltativo): se true, i percorsi tra le origini e le destinazioni verranno calcolati in modo da evitare le autostrade, ove possibile.
• avoidTolls (facoltativo): se true, le indicazioni stradali tra i punti verranno calcolate utilizzando percorsi che non prevedono pedaggi, se possibile.

Nota: il campo durationInTraffic è ora ritirato. In precedenza, per i clienti con un piano premium di Google Maps Platform era consigliato specificare se il risultato avrebbe dovuto includere una durata che tenga conto delle condizioni del traffico attuali. Ora dovresti utilizzare invece il campo drivingOptions.

Modalità di viaggio

Nel calcolo di tempi e distanze, puoi specificare la modalità di trasporto da utilizzare. Al momento sono supportate le seguenti modalità di viaggio:

• BICYCLING richiede le indicazioni in bicicletta attraverso le piste ciclabili e le strade preferite (attualmente disponibile solo negli Stati Uniti e in alcune città canadesi).
• DRIVING (predefinito) indica indicazioni stradali standard utilizzando la rete stradale.
• TRANSIT richiede indicazioni stradali tramite percorsi di trasporto pubblico. Questa opzione può essere specificata solo se la richiesta include una chiave API. Consulta la sezione relativa alle opzioni per il trasporto pubblico per conoscere le opzioni disponibili per questo tipo di richiesta.
• WALKING richiede indicazioni a piedi tramite percorsi pedonali e marciapiedi (se disponibili).

Opzioni di trasporto pubblico

Al momento, il servizio di trasporto pubblico è "sperimentale". In questa fase, implementeremo limiti di frequenza per prevenire l'abuso delle API. Alla fine applicheremo un limite al totale delle query per caricamento mappa in base al fair use dell'API.

Le opzioni disponibili per una richiesta della matrice di distanza variano in base alla modalità di viaggio. Nelle richieste di transito, le opzioni avoidHighways e avoidTolls vengono ignorate. Puoi specificare le opzioni di routing specifiche per il trasporto pubblico tramite il valore letterale dell'oggetto TransitOptions.

Le richieste di trasporto pubblico sono sensibili al tempo. I calcoli verranno restituiti solo per i tempi futuri.

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

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

Questi campi sono spiegati di seguito:

• arrivalTime (facoltativo) specifica l'orario di arrivo desiderato come oggetto Date. Se l'ora di arrivo è specificata, quella di partenza viene ignorata.
• departureTime (facoltativo) specifica l'orario di partenza desiderato come oggetto Date. departureTime verrà ignorato se viene specificato arrivalTime. Il valore predefinito è adesso (ossia l'ora attuale) se non viene specificato alcun valore per departureTime o arrivalTime.
• modes (facoltativo) è un array contenente uno o più valori letterali degli oggetti TransitMode. Questo campo può essere incluso solo se la richiesta include una chiave API. Ogni TransitMode specifica una modalità di trasporto pubblico preferita. Sono consentiti i seguenti valori:
  • BUS indica che il percorso calcolato dovrebbe preferire l'autobus.
  • RAIL indica che il percorso calcolato dovrebbe preferire treno, tram, metropolitana leggera e metropolitana.
  • SUBWAY indica che il percorso calcolato dovrebbe preferire la metropolitana.
  • TRAIN indica che il percorso calcolato dovrebbe preferire il treno.
  • TRAM indica che il percorso calcolato dovrebbe preferire il tram e la metropolitana leggera.
• routingPreference (facoltativo) specifica le preferenze per le route di trasporto pubblico. Utilizzando questa opzione, puoi differenziare le opzioni restituite, anziché accettare il percorso migliore 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 dovrebbe preferire un numero limitato di trasferimenti.
  • LESS_WALKING indica che il percorso calcolato dovrebbe preferire quantità di camminata limitate.

Opzioni di guida

Utilizza l'oggetto drivingOptions per specificare un orario di partenza in modo da calcolare il percorso migliore verso la tua destinazione in base alle condizioni del traffico previste. Puoi anche specificare se vuoi che il tempo stimato nel traffico sia pessimista, ottimistico o la migliore stima in base alle condizioni storiche del traffico e al traffico in tempo reale.

L'oggetto drivingOptions contiene i seguenti campi:

{
  departureTime: Date,
  trafficModel: TrafficModel
}

Questi campi sono spiegati di seguito:

• departureTime (obbligatorio affinché il valore letterale dell'oggetto drivingOptions sia valido) specifica l'orario di partenza desiderato come oggetto Date. Il valore deve essere impostato sull'ora attuale o su una data futura. Non può essere nel passato. (L'API converte tutte le date nel fuso orario UTC per garantire una gestione coerente nei vari fusi orari.) Se includi departureTime nella richiesta, l'API restituisce la route migliore in base alle condizioni di traffico previste in quel momento e include il tempo previsto nel traffico (duration_in_traffic) nella risposta. Se non specifichi un orario di partenza (ovvero, se la richiesta non include drivingOptions), il percorso restituito è un percorso generalmente valido, senza tenere conto delle condizioni del traffico.
  Attenzione: se non specifichi un orario di partenza, il percorso e la durata scelti si basano sulla rete stradale e sulle condizioni medie del traffico dipendenti dal tempo, non sulle condizioni attuali della strada. Di conseguenza, i percorsi possono includere strade temporaneamente chiuse. I risultati di una determinata richiesta possono variare nel tempo a causa di cambiamenti della rete stradale, condizioni medie del traffico aggiornate e natura distribuita del servizio. I risultati possono anche variare tra route quasi equivalenti in qualsiasi momento o frequenza.
• trafficModel (facoltativo) specifica le ipotesi da utilizzare per il calcolo del tempo nel traffico. Questa impostazione influisce sul valore restituito nel campo duration_in_traffic nella risposta, che contiene il tempo previsto nel traffico in base alle medie storiche. Il valore predefinito è best_guess. Sono consentiti i seguenti valori:
  • bestguess (valore predefinito) indica che duration_in_traffic restituito dovrebbe essere la migliore stima del tempo di percorrenza in base alle informazioni note sia sulle condizioni del traffico storico sia sul traffico in tempo reale. Il traffico in tempo reale diventa più importante man mano che si avvicina l'obiettivo departureTime.
  • pessimistic indica che il valore duration_in_traffic restituito deve essere più lungo del tempo di percorrenza effettivo nella maggior parte dei giorni, anche se occasionalmente giorni con condizioni di traffico particolarmente pessime possono superare questo valore.
  • optimistic indica che il valore duration_in_traffic restituito deve essere più breve del tempo di percorrenza effettivo nella maggior parte dei giorni, sebbene giornate occasionali con condizioni di traffico particolarmente buone possono essere più veloci di questo valore.

Di seguito è riportato un esempio di DistanceMatrixRequest per gli itinerari in auto, inclusi l'orario di partenza e il modello di traffico:

{
  origins: [{lat: 55.93, lng: -3.118}, 'Greenwich, England'],
  destinations: ['Stockholm, Sweden', {lat: 50.087, lng: 14.421}],
  travelMode: 'DRIVING',
  drivingOptions: {
    departureTime: new Date(Date.now() + N),  // for the time N milliseconds from now.
    trafficModel: 'optimistic'
  }
}

Risposte della matrice delle distanze

Una chiamata riuscita al servizio Matrice delle distanze restituisce un oggetto DistanceMatrixResponse e un oggetto DistanceMatrixStatus. Questi vengono passati alla funzione di callback specificata nella richiesta.

L'oggetto DistanceMatrixResponse contiene informazioni sulla distanza e sulla durata per ogni coppia di origine/destinazione per la quale è possibile calcolare una route.

{
  "originAddresses": [ "Greenwich, Greater London, UK", "13 Great Carleton Square, Edinburgh, City of Edinburgh EH16 4, UK" ],
  "destinationAddresses": [ "Stockholm County, Sweden", "Dlouhá 609/2, 110 00 Praha-Staré Město, Česká republika" ],
  "rows": [ {
    "elements": [ {
      "status": "OK",
      "duration": {
        "value": 70778,
        "text": "19 hours 40 mins"
      },
      "distance": {
        "value": 1887508,
        "text": "1173 mi"
      }
    }, {
      "status": "OK",
      "duration": {
        "value": 44476,
        "text": "12 hours 21 mins"
      },
      "distance": {
        "value": 1262780,
        "text": "785 mi"
      }
    } ]
  }, {
    "elements": [ {
      "status": "OK",
      "duration": {
        "value": 96000,
        "text": "1 day 3 hours"
      },
      "distance": {
        "value": 2566737,
        "text": "1595 mi"
      }
    }, {
      "status": "OK",
      "duration": {
        "value": 69698,
        "text": "19 hours 22 mins"
      },
      "distance": {
        "value": 1942009,
        "text": "1207 mi"
      }
    } ]
  } ]
}

Risultati della matrice delle distanze

I campi supportati in una risposta sono spiegati di seguito.

• originAddresses è un array contenente le località passate nel campo origins della richiesta della matrice delle distanze. Gli indirizzi vengono restituiti così come sono formattati dal geocodificatore.
• destinationAddresses è un array contenente le località passate nel campo destinations, nel formato restituito dal geocodificatore.
• rows è un array di oggetti DistanceMatrixResponseRow, con ogni riga corrispondente a un'origine.
• elements sono elementi secondari di rows e corrispondono a un accoppiamento dell'origine della riga con ogni destinazione. Contengono informazioni su stato, durata, distanza e tariffe (se disponibili) per ogni coppia di origine/destinazione.
• Ogni element contiene i seguenti campi:
  • status: consulta i codici di stato per un elenco di possibili codici di stato.
  • duration: il tempo necessario per percorrere questo percorso, espresso in secondi (campo value) e come text. Il valore testuale è formattato in base al unitSystem specificato nella richiesta (o in metrica, se non è stata specificata alcuna preferenza).
  • duration_in_traffic: il tempo necessario per percorrere questo percorso tenendo conto delle condizioni del traffico attuali, espresso in secondi (campo value) e text. Il valore testuale è formattato in base al unitSystem specificato nella richiesta (o in metrica, se non è stata specificata alcuna preferenza). duration_in_traffic viene restituito solo ai clienti del piano premium di Google Maps Platform se sono disponibili dati sul traffico, mode è impostato su driving e departureTime è incluso nel campo distanceMatrixOptions della richiesta.
  • distance: la distanza totale di questo percorso, espressa in metri (value) e come text. Il valore testuale è formattato in base al unitSystem specificato nella richiesta (o in metrica, se non è stata fornita alcuna preferenza).
  • fare: contiene la tariffa totale (ovvero i costi totali del biglietto) per questo itinerario. Questa proprietà viene restituita solo per le richieste relative al trasporto pubblico e solo per i fornitori di servizi di trasporto pubblico per cui sono disponibili informazioni sulle tariffe. 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.

Codici di stato

La risposta della matrice delle distanze include un codice di stato per la risposta nel suo complesso, nonché uno stato per ogni elemento.

Codici di stato risposta

I codici di stato che si applicano a DistanceMatrixResponse vengono passati nell'oggetto DistanceMatrixStatus e includono:

• OK: la richiesta è valida. Questo stato può essere restituito anche se non sono state trovate route tra le origini e le destinazioni. Consulta la sezione Codici di stato degli elementi per informazioni sullo stato a livello di elemento.
• INVALID_REQUEST: la richiesta fornita non è valida. Spesso questo è dovuto alla mancanza di campi obbligatori. Consulta l'elenco dei campi supportati qui sopra.
• MAX_ELEMENTS_EXCEEDED: il prodotto di origini e destinazioni supera il limite per query.
• MAX_DIMENSIONS_EXCEEDED - La tua richiesta conteneva più di 25 origini o più di 25 destinazioni.
• OVER_QUERY_LIMIT - La tua applicazione ha richiesto troppi elementi nel periodo di tempo consentito. Se riprovi dopo un periodo di tempo ragionevole, la richiesta dovrebbe andare a buon fine.
• REQUEST_DENIED - Il servizio ha negato l'utilizzo del servizio Matrice delle distanze dalla tua pagina web.
• UNKNOWN_ERROR: non è stato possibile elaborare una richiesta della matrice delle distanze a causa di un errore del server. Se riprovi, la richiesta potrebbe andare a buon fine.

Codici di stato degli elementi

I seguenti codici di stato si applicano a oggetti DistanceMatrixElement specifici:

• NOT_FOUND: non è stato possibile geocodificare l'origine e/o la destinazione di questo accoppiamento.
• OK: la risposta contiene un risultato valido.
• ZERO_RESULTS: non è stata trovata alcuna route tra l'origine e la destinazione.

Analisi dei risultati

L'oggetto DistanceMatrixResponse contiene un row per ogni origine passata nella richiesta. Ogni riga contiene un campo element per ogni accoppiamento dell'origine con le destinazioni fornite.

function callback(response, status) {
  if (status == 'OK') {
    var origins = response.originAddresses;
    var destinations = response.destinationAddresses;

    for (var i = 0; i < origins.length; i++) {
      var results = response.rows[i].elements;
      for (var j = 0; j < results.length; j++) {
        var element = results[j];
        var distance = element.distance.text;
        var duration = element.duration.text;
        var from = origins[i];
        var to = destinations[j];
      }
    }
  }
}