Servizio Distance Matrix

Panoramica

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 sui percorsi, tra cui polilinee e indicazioni stradali testuali, possono essere ottenute passando la singola origine e destinazione desiderate al servizio di indicazioni stradali.

Per iniziare

Prima di utilizzare il servizio Distance Matrix nell'API Maps JavaScript, assicurati innanzitutto che l'API Distance Matrix sia attivata 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 configurato per l'API Maps JavaScript e fai clic su Apri.
3. Nell'elenco delle API nella dashboard, cerca API Distance Matrix.
4. Se vedi l'API nell'elenco, non devi fare altro. Se l'API non è presente nell'elenco, attivala:
   1. Nella parte superiore della pagina, seleziona ABILITA API per visualizzare la scheda Raccolta. In alternativa, nel menu a sinistra, seleziona Raccolta.
   2. Cerca API Distance Matrix e selezionala dall'elenco dei risultati.
   3. Seleziona ATTIVA. Al termine del processo, Distance Matrix API 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 di pagamento a consumo per Maps, Routes e Places. Per scoprire di più sui nuovi prezzi e sui limiti di utilizzo per l'utilizzo del servizio Distance Matrix JavaScript, 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 origini moltiplicato per il numero di destinazioni definisce il numero di elementi.

Norme

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

Richieste di Distance Matrix

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 callback da eseguire al termine della richiesta per elaborare i risultati.

Accedi al servizio Matrice delle distanze all'interno del codice tramite l'oggetto del costruttore google.maps.DistanceMatrixService. Il metodo DistanceMatrixService.getDistanceMatrix() avvia una richiesta al servizio Distance Matrix, passando un valore letterale dell'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:

• origins (obbligatorio) - Un array contenente una o più stringhe di indirizzi, oggetti google.maps.LatLng o oggetti Place da cui calcolare la distanza e il tempo.
• destinations (obbligatorio) - Una matrice contenente una o più stringhe di indirizzi, oggetti google.maps.LatLng o oggetti Place per i quali calcolare la distanza e il tempo.
• travelMode (facoltativo): la modalità di trasporto da utilizzare per calcolare le 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 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 usare per visualizzare la distanza. I valori accettati sono:
  • google.maps.UnitSystem.METRIC (valore predefinito)
  • google.maps.UnitSystem.IMPERIAL
• avoidHighways (facoltativo): se impostato su true, i percorsi tra le origini e le destinazioni verranno calcolati in modo da evitare le autostrade, se possibile.
• avoidTolls (facoltativo): se impostato su true, le indicazioni stradali tra i punti verranno calcolate utilizzando i percorsi senza pedaggio, ove possibile.

Modalità di viaggio

Quando calcoli tempi e distanze, puoi specificare la modalità di trasporto da 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 (valore predefinito) indica le indicazioni stradali standard che utilizzano la rete stradale.
• TRANSIT richiede indicazioni stradali tramite linee di trasporto pubblico. Questa opzione può essere specificata solo se la richiesta include una chiave API. Consulta la sezione sulle opzioni di trasporto pubblico per conoscere le opzioni disponibili per questo tipo di richiesta.
• WALKING richiede indicazioni stradali per raggiungere la destinazione a piedi tramite percorsi pedonali e marciapiedi (se disponibili).

Opzioni di trasporto pubblico

Il servizio di trasporto pubblico è attualmente "sperimentale". Durante questa fase, implementeremo limiti di frequenza per prevenire abusi dell'API. Alla fine imposteremo un limite alle query totali per caricamento della mappa in base a un utilizzo equo dell'API.

Le opzioni disponibili per una richiesta di matrice di distanza variano in base alle modalità di viaggio. Nelle richieste relative ai trasporti pubblici, le opzioni avoidHighways e avoidTolls vengono ignorate. Puoi specificare opzioni di routing specifiche per i trasporti pubblici tramite il valore letterale dell'oggetto TransitOptions.

Le richieste relative ai trasporti pubblici sono urgenti. I calcoli verranno restituiti solo per i 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'ora di arrivo preferita come oggetto Date. Se viene specificato l'orario di arrivo, l'orario di partenza viene ignorato.
• departureTime (facoltativo) specifica l'ora di partenza preferita come oggetto Date. Il valore departureTime verrà ignorato se viene specificato arrivalTime. Il valore predefinito è la data e l'ora attuali se non viene specificato alcun valore per departureTime o arrivalTime.
• modes (facoltativo) è un array contenente uno o più literali oggetto TransitMode. Questo campo può essere incluso solo se la richiesta include una chiave API. Ogni TransitMode specifica una modalità di trasporto pubblico preferita. Sono consentiti i seguenti valori:
  • BUS indica che il percorso calcolato deve privilegiare i viaggi in autobus.
  • RAIL indica che il percorso calcolato deve privilegiare i viaggi in treno, tram, metropolitana leggera e metropolitana.
  • SUBWAY indica che il percorso calcolato deve privilegiare i viaggi in metropolitana.
  • TRAIN indica che il percorso calcolato deve privilegiare i viaggi in treno.
  • TRAM indica che il percorso calcolato deve privilegiare i viaggi in tram e metropolitana leggera.
• routingPreference (facoltativo) specifica le preferenze per i percorsi con il trasporto pubblico. Con questa opzione, puoi influenzare le opzioni restituite, anziché accettare il percorso migliore predefinito scelto dall'API. Questo campo può essere specificato solo se la richiesta include una chiave API. Sono consentiti i seguenti valori:
  • FEWER_TRANSFERS indica che il percorso calcolato deve preferire un numero limitato di trasferimenti.
  • LESS_WALKING indica che il percorso calcolato deve preferire tratti a piedi contenuti.

Opzioni di guida

Utilizza l'oggetto drivingOptions per specificare un'ora di partenza per calcolare il percorso migliore per raggiungere la tua destinazione in base alle condizioni di traffico previste. Puoi anche specificare se il tempo stimato nel traffico deve essere pessimistico, ottimistico o la stima migliore in base alle condizioni di traffico storiche 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 per la validità del literale dell'oggetto drivingOptions) specifica l'ora di partenza desiderata come oggetto Date. Il valore deve essere impostato sull'ora corrente o su un momento futuro. Non può essere nel passato. L'API converte tutte le date in UTC per garantire un'elaborazione coerente tra i fusi orari. Se includi departureTime nella richiesta, l'API restituisce il percorso migliore in base alle condizioni di traffico previste al momento e include il tempo previsto nel traffico (duration_in_traffic) nella risposta. Se non specifichi un'ora di partenza (ovvero se la richiesta non include drivingOptions), il percorso restituito è in genere buono, ma non tiene conto delle condizioni del traffico.
• trafficModel (facoltativo) specifica le ipotesi da utilizzare per calcolare il tempo nel traffico. Questa impostazione influisce sul valore restituito nel campo duration_in_traffic della risposta, che contiene il tempo previsto nel traffico in base alle medie storiche. Il valore predefinito è 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 sulle condizioni del traffico storiche e in tempo reale. Il traffico in tempo reale diventa più importante quanto più departureTime è vicino al momento attuale.
  • pessimistic indica che il valore duration_in_traffic restituito deve essere più lungo del tempo di percorrenza effettivo nella maggior parte dei giorni, anche se in alcuni giorni con condizioni di traffico particolarmente difficili questo valore può essere superato.
  • optimistic indica che il valore duration_in_traffic restituito deve essere inferiore al tempo di percorrenza effettivo nella maggior parte dei giorni, anche se in alcuni giorni con condizioni di traffico particolarmente buone il tempo di percorrenza può essere inferiore a questo valore.

Di seguito è riportato un DistanceMatrixRequest di esempio per i percorsi in auto, incluso un modello di traffico e un'ora di partenza:

{
  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 di Distance Matrix

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

L'oggetto DistanceMatrixResponse contiene informazioni su distanza e durata per ogni coppia di origine/destinazione per la quale è 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 di Distance Matrix

I campi supportati in una risposta sono spiegati di seguito.

• originAddresses è un array contenente le località passate nel campo origins della richiesta della matrice di distanza. Gli indirizzi vengono restituiti così come sono formattati dal geocodificatore.
• destinationAddresses è un array contenente le località trasmesse nel campo destinations, nel formato restituito dal geocodificatore.
• rows è un array di oggetti DistanceMatrixResponseRow in cui ogni riga corrisponde 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 tariffa (se disponibili) per ogni coppia di origine/destinazione.
• Ogni element contiene i seguenti campi:
  • status: consulta 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 di testo viene formattato in base al valore unitSystem specificato nella richiesta (o in metrica, se non è stata fornita alcuna preferenza).
  • duration_in_traffic: il tempo necessario per percorrere questo percorso tenendo conto delle condizioni di traffico attuali, espresso in secondi (campo value) e come text. Il valore di testo viene formattato in base al valore unitSystem specificato nella richiesta (o in metrica, se non è stata fornita alcuna 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 come text. Il valore di testo viene formattato in base al valore unitSystem specificato nella richiesta (o in metrica, se non è stata fornita alcuna 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 i fornitori di servizi di trasporto pubblico per i quali 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 di distanza include un codice di stato per la risposta nel suo insieme, nonché uno stato per ogni elemento.

Codici di stato di 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 stati trovati percorsi tra le varie origini e destinazioni. Per informazioni sullo stato a livello di elemento, consulta Codici stato elemento.
• INVALID_REQUEST: la richiesta fornita non è valida. Ciò è spesso dovuto alla mancata indicazione dei 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. La richiesta dovrebbe essere completata se riprovi dopo un periodo di tempo ragionevole.
• REQUEST_DENIED: il servizio ha negato l'utilizzo del servizio Distance Matrix da parte della tua pagina web.
• UNKNOWN_ERROR - Impossibile elaborare una richiesta di matrice di distanza a causa di un errore del server. La richiesta potrebbe andare a buon fine se provi nuovamente.

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 pairing.
• OK: la risposta contiene un risultato valido.
• ZERO_RESULTS: non è stato possibile trovare un percorso tra la 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 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];
      }
    }
  }
}