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 lavorare con i servizi web di Google Maps sul tuo server, consulta il Client Node.js per i servizi Google Maps. La pagina con questo link presenta anche il client Java, il client Python e il client Go per i servizi Google Maps.

Panoramica

Vedi anche il riferimento API Maps JavaScript: Matrice delle distanze

Il servizio DIST 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 le polilinee e le indicazioni testuali, possono essere ottenute passando la singola origine e la destinazione desiderate al servizio Directions.

Per cominciare

Prima di utilizzare il servizio Matrice delle distanze nell'API Maps JavaScript, assicurati che l'API DIST Matrix 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 scegli 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 Array Matrix.
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 Equal Matrix, quindi selezionala dall'elenco dei risultati.
   3. Seleziona ABILITA. Al termine del processo, viene visualizzata l'API Array Matrix nell'elenco delle API sulla 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 Array Matrix, consulta Utilizzo e fatturazione per l'API DIST 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.

Norme

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

Richieste di matrici di distanze

L'accesso al servizio Array Matrix è asincrono, dal momento che 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 completamento della richiesta, per elaborare i risultati.

Accedi al servizio Matrice delle distanze all'interno del tuo codice tramite l'oggetto costruttore google.maps.DistanceMatrixService. Il metodo DistanceMatrixService.getDistanceMatrix() avvia una richiesta al servizio Array Matrix, passando un valore letterale di 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 l'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 la distanza e il tempo.
• destinations (obbligatorio): un array contenente una o più stringhe di indirizzo, oggetti google.maps.LatLng o oggetti Place a cui calcolare la distanza e il 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 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 Opzioni di guida.
• unitSystem (facoltativo): il sistema di unità da utilizzare quando si visualizza la distanza. I valori accettati sono:
  • google.maps.UnitSystem.METRIC (valore predefinito)
  • google.maps.UnitSystem.IMPERIAL
• avoidHighways (facoltativo): se true, i percorsi tra origini e destinazioni vengono calcolati per evitare autostrade ove possibile.
• avoidTolls (facoltativo): se true, le indicazioni stradali tra i punti vengono calcolate utilizzando percorsi non a pedaggio, ove possibile.

Nota: il campo durationInTraffic è ora deprecato. In precedenza, era il metodo consigliato ai clienti di Google Maps Platform Premium Plan per specificare se il risultato deve includere una durata che tiene conto delle condizioni del traffico attuali. Ora dovresti usare il campo drivingOptions.

Modalità di viaggio

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

• BICYCLING richiede indicazioni in bicicletta tramite piste ciclabili e strade preferite (attualmente disponibile solo negli Stati Uniti e in alcune città canadesi).
• DRIVING (predefinita) indica le indicazioni stradali standard che utilizzano la rete stradale.
• TRANSIT richiede le indicazioni stradali tramite percorsi 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 informazioni sulle opzioni disponibili in 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". Durante questa fase, implementeremo i limiti di frequenza per impedire utilizzi illeciti dell'API. Applicheremo un limite al totale delle query per caricamento mappa in base al fair use dell'API.

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

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

Il valore letterale oggetto TransitOptions contiene i seguenti campi:

{
  arrivalTime: Date,
  departureTime: Date,
  modes: [transitMode1, transitMode2]
  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.

Opzioni di guida

Utilizza l'oggetto drivingOptions per specificare un orario di partenza per 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 pessimistico, ottimista o la stima migliore basata sulle condizioni del traffico storico e sul traffico in tempo reale.

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. 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.

  Nota: se l'orario di partenza non è specificato, la scelta di percorso e durata si basa sulla rete stradale e su condizioni medie del traffico indipendenti dal tempo. I risultati di una determinata richiesta possono variare nel tempo a causa di cambiamenti nella rete stradale, di condizioni di traffico medie aggiornate e della natura distribuita del servizio. I risultati possono anche variare tra percorsi quasi equivalenti in qualsiasi momento o frequenza.

• 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 è best_guess. 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 DistanceMatrixRequest per i percorsi in auto, inclusi l'orario di partenza e il modello del 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 a matrice di distanza

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

L'oggetto DistanceMatrixResponse contiene informazioni sulla distanza e sulla durata per ogni coppia di origine/destinazione per cui è 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 matrice di distanza

I campi supportati in una risposta sono spiegati di seguito.

• originAddresses è un array che contiene le località passate nel campo origins della richiesta Matrice della distanza. Gli indirizzi vengono restituiti così come sono formattati dal geocodificatore.
• destinationAddresses è un array che contiene le località passate nel campo destinations, nel formato restituito dal geocodificatore.
• rows è un array di oggetti DistanceMatrixResponseRow e ogni riga corrisponde a un'origine.
• elements sono figli di rows e corrispondono a una coppia di origini della riga con ciascuna destinazione. Contengono informazioni su stato, durata, distanza e tariffe (se disponibili) per ogni coppia origine/destinazione.
• Ogni element contiene i seguenti campi:
  • status: consulta Codici di stato per un elenco di codici di stato possibili.
  • duration: il tempo necessario per viaggiare su questo percorso, espresso in secondi (il 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 viaggiare su questo percorso tenendo conto delle condizioni del traffico attuali, espresse in secondi (il 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 viene restituito solo ai clienti del piano Premium di Google Maps Platform, dove sono disponibili i dati sul traffico, il mode è impostato su driving e departureTime è incluso nel campo distanceMatrixOptions della richiesta.
  • distance: la distanza totale di questo percorso, espressa in metri (value) e 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 (ossia i costi totali del biglietto) per questo itinerario. Questa proprietà viene restituita solo per le richieste di trasporto pubblico e solo per i fornitori di servizi di trasporto in cui sono disponibili informazioni sulle tariffe. 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.

Codici di stato

La risposta della matrice della distanza include un codice di stato per la risposta nel suo complesso, nonché uno stato per ciascun 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 è stata trovata alcuna 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. Questo problema è 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: l'applicazione ha richiesto troppi elementi nel periodo di tempo consentito. La richiesta dovrebbe avere esito positivo se riproviamo dopo un certo periodo di tempo.
• REQUEST_DENIED: il servizio ha negato l'utilizzo del servizio matrice di distanza dalla tua pagina web.
• UNKNOWN_ERROR: non è stato possibile elaborare una richiesta di Matrice della distanza a causa di un errore del server. La richiesta potrebbe avere esito positivo se riprova.

Codici di stato 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 questa associazione.
• OK: la risposta contiene un risultato valido.
• ZERO_RESULTS: non è stato trovato alcun percorso 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 associazione 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];
      }
    }
  }
}