Servizio di matrice delle distanze

Panoramica

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

Questo servizio non restituisce informazioni dettagliate sul percorso. Per ottenere le informazioni sul percorso, comprese polilinee e indicazioni testuali, è possibile trasmettere al servizio indicazioni stradali la singola origine e la destinazione desiderate.

Per iniziare

Prima di utilizzare il servizio Distance Matrix nell'API Maps JavaScript, assicurati che l'API Distance 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, 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 l'API Distance Matrix.
  4. Se vedi l'API nell'elenco, non devi eseguire altre operazioni. Se l'API non è elencata, abilitala:
    1. Nella parte superiore della pagina, seleziona ABILITA API per visualizzare la scheda Libreria. In alternativa, nel menu a sinistra, seleziona Raccolta.
    2. Cerca API Distance Matrix, poi selezionala dall'elenco dei risultati.
    3. Seleziona ABILITA. Al termine del processo, l'API Distance Matrix viene visualizzata nell'elenco delle API nella Dashboard.

Prezzi e norme

Prezzi

A partire dal 16 luglio 2018, è entrato in vigore un nuovo piano tariffario con pagamento a consumo per Maps, Routes e Places. Per ulteriori informazioni sui nuovi prezzi e i limiti di utilizzo per l'utilizzo del servizio JavaScript Distance Matrix, consulta Utilizzo e fatturazione per l'API Distance Matrix.

Nota: ogni query inviata al servizio Distance Matrix è limitata dal numero di elementi consentiti, dove il numero di elementi è definito dal numero di origini moltiplicate per il numero di destinazioni.

Criteri

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

Richieste di matrice delle distanze

L'accesso al servizio Distance Matrix è asincrono, poiché l'API Google Maps deve effettuare una chiamata a un server esterno. Per questo motivo, devi passare un metodo di callback da eseguire al completamento della richiesta, per elaborare i risultati.

Puoi accedere al servizio Distance Matrix all'interno del tuo codice tramite l'oggetto costruttore google.maps.DistanceMatrixService. Il metodo DistanceMatrixService.getDistanceMatrix() avvia una richiesta al servizio Distance Matrix, passando un valore letterale oggetto DistanceMatrixRequest contenente le origini, le destinazioni e la modalità di viaggio, nonché un metodo di callback da eseguire al ricevimento 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:

  • (Obbligatorio) origins: un array contenente una o più stringhe di indirizzi, oggetti google.maps.LatLng o oggetti Posiziona da cui calcolare distanza e tempo.
  • (Obbligatorio) destinations: un array contenente una o più stringhe di indirizzi, oggetti google.maps.LatLng o oggetti Place in cui calcolare distanza e tempo.
  • (Facoltativo) travelMode: 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 sulle 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 su 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 il luogo di partenza e le destinazioni verranno calcolati in modo da evitare le autostrade ove possibile.
  • avoidTolls (facoltativo): se true, le indicazioni stradali tra punti verranno calcolate utilizzando percorsi non a pedaggio, ove possibile.

Modalità di viaggio

Quando calcoli i tempi e le distanze, puoi specificare quale modalità di trasporto utilizzare. Al momento sono supportate le seguenti modalità di viaggio:

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

Opzioni di trasporto pubblico

Il servizio di trasporto pubblico è attualmente "sperimentale". In questa fase, implementeremo i limiti di frequenza per prevenire l'uso illecito delle API. Alla fine applicheremo un limite alle query totali per caricamento mappa, in base al fair use dell'API.

Le opzioni disponibili per una richiesta di matrice delle distanze variano a seconda della modalità di viaggio. Per le richieste di trasporto pubblico, le opzioni avoidHighways e avoidTolls vengono ignorate. Puoi specificare 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 periodi futuri.

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

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

Questi campi sono descritti di seguito:

  • arrivalTime (facoltativo) specifica l'orario di arrivo desiderato come oggetto Date. Se l'ora di arrivo è specificata, quest'ultima viene ignorata.
  • departureTime (facoltativo) specifica l'orario di partenza desiderato come oggetto Date. Il departureTime verrà ignorato se viene specificato arrivalTime. Se non viene specificato alcun valore per departureTime o arrivalTime, il valore predefinito è ora (ovvero l'ora attuale).
  • modes (facoltativo) è un array contenente uno o più valori letterali oggetto TransitMode. Questo campo può essere incluso solo se la richiesta include una chiave API. Ogni TransitMode specifica una modalità di transito preferita. Sono consentiti i seguenti valori:
    • BUS indica che il percorso calcolato dovrebbe preferire i viaggi in autobus.
    • RAIL indica che il percorso calcolato dovrebbe preferire 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 i viaggi 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 di trasporto pubblico. Utilizzando questa opzione, puoi differenziare le opzioni restituite, anziché accettare la migliore route predefinita scelta dall'API. Questo campo può essere specificato solo se la richiesta include una chiave API. Sono consentiti i seguenti valori:
    • FEWER_TRANSFERS indica che il percorso calcolato deve preferire un numero limitato di cambi.
    • LESS_WALKING indica che il percorso calcolato dovrebbe preferire un numero limitato di tratti a piedi.

Opzioni di guida

Utilizza l'oggetto drivingOptions per specificare un orario di partenza per calcolare il percorso migliore per raggiungere la tua destinazione in base alle condizioni del traffico previste. Puoi anche specificare se vuoi che il tempo stimato nel traffico sia pessimista, ottimista o la stima migliore 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 descritti di seguito:

  • departureTime (obbligatorio perché il valore letterale dell'oggetto drivingOptions sia valido) specifica l'ora di partenza desiderata come oggetto Date. Il valore deve essere impostato sull'ora attuale o su un'ora futura. Non può essere nel passato. L'API converte tutte le date in UTC per garantire una gestione coerente tra i diversi fusi orari. Se includi departureTime nella richiesta, l'API restituisce il percorso migliore in base alle condizioni di traffico previste al momento e include nella risposta il tempo previsto nel traffico (duration_in_traffic). Se non specifichi un orario di partenza (ovvero se la richiesta non include drivingOptions), il percorso restituito è generalmente un buon percorso senza tenere conto delle condizioni del traffico.
  • trafficModel (facoltativo) specifica le ipotesi da utilizzare per calcolare il tempo trascorso 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 è best_guess. 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 sia sulle condizioni storiche del traffico sia sul traffico in tempo reale. Il traffico in tempo reale diventa più importante più si avvicina all'attuale departureTime.
    • pessimistic indica che l'importo duration_in_traffic restituito dovrebbe essere più lungo del tempo di percorrenza effettivo nella maggior parte dei giorni, anche se i giorni occasionali con condizioni di traffico particolarmente gravi possono superare questo valore.
    • optimistic indica che il valore duration_in_traffic restituito dovrebbe essere più breve del tempo di percorrenza effettivo nella maggior parte dei giorni, anche se i giorni occasionali con condizioni di traffico particolarmente favorevoli potrebbero essere più veloci di questo valore.

Di seguito è riportato un esempio di DistanceMatrixRequest per i percorsi in auto, che include un orario di partenza e un 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 Distance Matrix restituisce un oggetto DistanceMatrixResponse e un oggetto DistanceMatrixStatus. Questi vengono passati alla funzione callback specificata nella richiesta.

L'oggetto DistanceMatrixResponse contiene informazioni su distanza e durata per ogni coppia origine/destinazione per cui è stato possibile calcolare un percorso.

{
  "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à trasmesse nel campo origins della richiesta Distance Matrix. 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 origine/destinazione.
  • Ogni element contiene i seguenti campi:
    • status: consulta la sezione Codici di stato per un elenco di possibili codici di stato.
    • duration: il tempo necessario per percorrere questo percorso, espresso in secondi (il campo value) e in text. Il valore testuale viene formattato in base a unitSystem specificato nella richiesta (o in una metrica, se non è stata fornita nessuna preferenza).
    • duration_in_traffic: il tempo necessario per percorrere questo percorso tenendo conto delle condizioni del traffico attuali, espresso in secondi (il campo value) e in text. Il valore testuale viene formattato in base a unitSystem specificato nella richiesta (o in una metrica, se non è stata fornita nessuna preferenza). duration_in_traffic viene restituito solo se sono disponibili dati sul traffico, mode è impostato su driving e departureTime è incluso nel campo distanceMatrixOptions della richiesta.
    • distance: la distanza totale del percorso, espressa in metri (value) e in text. Il valore testuale viene formattato in base al valore unitSystem specificato nella richiesta (o in una metrica, se non è stata fornita nessuna preferenza).
    • fare: contiene la tariffa totale (ovvero i costi totali dei biglietti) per questo percorso. Questa proprietà viene restituita solo per le richieste di trasporto pubblico e solo per le aziende di trasporto pubblico per cui sono disponibili informazioni sulle tariffe. Queste 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 Distance Matrix include un codice di stato per la risposta nel suo complesso e uno stato per ogni elemento.

Codici di stato della risposta

I codici di stato applicabili 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. Per informazioni sullo stato a livello di elemento, consulta Codici di stato elemento.
  • INVALID_REQUEST: la richiesta fornita non è valida. Questo è spesso dovuto alla mancanza di campi obbligatori. Consulta l'elenco dei campi supportati 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. La richiesta dovrebbe andare a buon fine se riprovi dopo un periodo di tempo ragionevole.
  • REQUEST_DENIED: il servizio ha negato l'uso del servizio Distance Matrix da parte della tua pagina web.
  • UNKNOWN_ERROR: non è stato possibile elaborare una richiesta Distance Matrix a causa di un errore del server. Riprova.

Codici di stato dell'elemento

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 è stato trovato alcun percorso tra il luogo di partenza 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 di quell'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];
      }
    }
  }
}