Servizio di matrice delle distanze

Panoramica

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

Questo servizio non restituisce informazioni dettagliate sul percorso. Informazioni sul percorso, incluse le polilinee e le direzioni testuali, si ottiene passando il di partenza e destinazione desiderate Servizio indicazioni stradali.

Per iniziare

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

Per visualizzare l'elenco delle API abilitate:

  1. Vai alla sezione 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 sulla Dashboard, cerca 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 lo stato Scheda Raccolta. In alternativa, dal menu laterale a sinistra, Seleziona Libreria.
    2. Cerca l'API Distance Matrix e selezionala dall'elenco dei risultati.
    3. Seleziona ABILITA. Al termine del processo, L'API Distance Matrix appare 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 saperne di più sui nuovi prezzi e limiti di utilizzo del servizio JavaScript Distance Matrix, consulta Utilizzo e fatturazione per l'API Distance Matrix.

Nota: ogni query inviata al servizio Distance Matrix è limitata in base al numero di elementi consentiti, ovvero il numero di origini moltiplicate per "number of destinations" 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 matrice delle distanze

L'accesso al servizio Distance Matrix è asincrono, poiché L'API di Google Maps deve effettuare una chiamata a un server esterno. Per questo motivo, devono passare un metodo di callback da eseguire una volta completata la 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 una DistanceMatrixRequest letterale oggetto contenente le origini, destinazioni e modalità di viaggio, nonché un metodo di callback da eseguire la 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 uno o più stringhe di indirizzi, google.maps.LatLng oggetti o Place oggetti da cui calcolare distanza e tempo.
  • destinations (obbligatorio): un array contenente uno o più stringhe di indirizzi, google.maps.LatLng oggetti o Place gli oggetti a cui calcolare la distanza e il tempo.
  • travelMode (facoltativo): la modalità 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 valori applicabili solo alle richieste in cui travelMode è DRIVING. I valori validi sono descritti della sezione Opzioni di guida.
  • unitSystem (facoltativo): il sistema di unità da 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 saranno in modo da evitare le autostrade, ove possibile.
  • avoidTolls (facoltativo): se true, le indicazioni stradali tra i punti saranno calcolate utilizzando che non sono a pedaggio, ove possibile.
di Gemini Advanced.

Modalità di viaggio

Nel calcolo di tempi e distanze, puoi specificare quale modalità di trasporto utilizzare. Il seguente viaggio sono attualmente supportate:

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

Opzioni di trasporto pubblico

Il servizio di trasporto pubblico è attualmente "sperimentale". Durante questo , implementeremo i limiti di frequenza per prevenire l'abuso delle API. Lo faremo alla fine applicare un limite alle query totali per caricamento mappa in base al fair use l'API.

Le opzioni disponibili per una richiesta di matrice delle distanze variano a seconda della modalità di viaggio. Per le richieste in transito, avoidHighways e avoidTolls opzioni vengono ignorate. Puoi specificare specifiche per il trasporto pubblico, tramite TransitOptions oggetto letterale.

Le richieste di trasporto pubblico sono sensibili al tempo. I calcoli verranno restituiti solo per in futuro.

Il valore letterale dell'oggetto TransitOptions contiene quanto segue campi:

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

Questi campi sono descritti di seguito:

  • arrivalTime (facoltativo) specifica la classe ora di arrivo come oggetto Date. Se l'ora di arrivo è specificato, l'ora di partenza viene ignorata.
  • departureTime (facoltativo) specifica la classe orario di partenza come oggetto Date. La departureTime verrà ignorato se arrivalTime è specificato. Il valore predefinito è ora (ora corrente), se non è presente alcun valore specificato per departureTime o arrivalTime.
  • modes (facoltativo) è un array contenente uno o altri valori letterali oggetto TransitMode. Questo campo può essere se la richiesta include una chiave API. Ogni TransitMode specifica una modalità di transito preferita. Sono consentiti i seguenti valori:
    • BUS indica che nell'itinerario calcolato dovrebbe preferire i viaggi in autobus.
    • RAIL indica che calcolo dell'itinerario dovrebbe preferire i viaggi in treno, tram, metropolitana leggera e metropolitana.
    • SUBWAY indica che per il percorso calcolato dovrebbe preferire i viaggi in metropolitana.
    • TRAIN indica che per il percorso calcolato dovrebbe preferire i viaggi in treno.
    • TRAM indica che percorso calcolato predilige i tram e la metropolitana leggera.
  • routingPreference (facoltativo) specifica le preferenze per i percorsi con il trasporto pubblico. Utilizzando questa opzione, puoi differenziare le opzioni restituite, anziché accettare il percorso migliore predefinito scelto dall'API. Questo campo può essere specificato solo se la richiesta include un 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 dovrebbe preferire una quantità limitata di camminando.

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 specificare anche se desideri che il tempo stimato nel traffico sia pessimista, ottimista o la stima migliore basata sulle condizioni storiche del traffico e sul traffico in tempo reale.

L'oggetto drivingOptions contiene i seguenti campi:

{
  departureTime: Date,
  trafficModel: TrafficModel
}

Questi campi sono descritti di seguito:

  • departureTime (obbligatorio per drivingOptions oggetto letterale da essere valido) specifica la orario di partenza desiderato come oggetto Date. Il valore deve essere impostata sull'ora attuale o su un orario futuro. Non può essere nel in passato. L'API converte tutte le date in UTC per garantire una gestione coerente tra fusi orari diversi). 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 (ossia, se la richiesta non include drivingOptions), il percorso restituito è un percorso generalmente buono senza tenere conto delle condizioni del traffico.
  • trafficModel (facoltativo) specifica i presupposti per da utilizzare per calcolare il tempo nel traffico. Questa impostazione influisce sul valore 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 (predefinito) indica che l'oggetto restituito duration_in_traffic dovrebbe essere la stima migliore del viaggio in base a ciò che è noto sulle condizioni storiche del traffico e traffico in tempo reale. Il traffico in tempo reale diventa più importante più si avvicina departureTime è fino a ora...
    • pessimistic indica che l'oggetto restituito duration_in_traffic deve essere più lungo del viaggio effettivo tempo nella maggior parte dei giorni, anche se occasionalmente i giorni con traffico particolarmente intenso possono superare questo valore.
    • optimistic indica che l'oggetto restituito duration_in_traffic deve essere più breve del valore effettivo tempo di percorrenza quasi tutti i giorni, anche se occasionalmente i giorni in cui si registrano condizioni del traffico possono essere più veloci di questo valore.

Di seguito è riportato un esempio di DistanceMatrixRequest per i percorsi in auto, includendo 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 DistanceMatrixResponse oggetto e un Oggetto DistanceMatrixStatus. Questi vengono passati al callback specificata nella richiesta.

L'oggetto DistanceMatrixResponse contiene distanza e informazioni sulla durata per ogni coppia origine/destinazione per cui un percorso potrebbe essere calcolato.

{
  "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à nel campo origins della richiesta di matrice delle distanze. Gli indirizzi vengono restituiti così come sono formattati dal geocodificatore.
  • destinationAddresses è un array contenente località trasmesse nel campo destinations, nel formato restituito dal geocodificatore.
  • rows è un array di DistanceMatrixResponseRow di oggetti, con ogni riga corrispondente a un'origine.
  • elements sono figli 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 ciascuno origine/destinazione.
  • Ogni element contiene i seguenti campi:
    • status: visualizza Codici di stato per un elenco di possibili codici di stato.
    • duration: il tempo necessario per percorrere questo luogo route, espressa in secondi (il campo value) e come text. Il valore testuale viene formattato in base alla unitSystem specificato nella richiesta (o nella metrica, se non è presente) è stata specificata).
    • duration_in_traffic: il tempo necessario per percorri questo itinerario tenendo conto delle condizioni del traffico attuali, espresso in secondi (il campo value) e come text. Il valore testuale viene formattato in base alla unitSystem specificato nella richiesta (o nella metrica, se non è presente) è stata specificata). La duration_in_traffic viene restituito solo se sono disponibili dati sul traffico, Il campo mode è impostato su driving e departureTime è incluso in distanceMatrixOptions nella richiesta.
    • distance: la distanza totale del percorso, espressa in metri (value) e come text. Il valore testuale sia formattato in base al valore unitSystem specificato in richiesta (o nella metrica, se non è stata fornita nessuna preferenza).
    • fare: contiene la tariffa totale (ossia il totale costi dei biglietti) su questo percorso. Questa proprietà viene restituita solo per il trasporto pubblico ed esclusivamente per i fornitori di servizi di trasporto pubblico per i quali le informazioni relative alle tariffe disponibili. Le informazioni includono:
      • currency: un Valuta ISO 4217 che indica la valuta in cui è espresso l'importo.
      • value: importo totale della tariffa, nella valuta specificata in alto.

Codici di stato

La risposta Distance Matrix include un codice di stato per la risposta come nonché lo stato di ogni elemento.

Codici di stato della risposta

I codici di stato che si applicano all'DistanceMatrixResponse sono passati all'oggetto DistanceMatrixStatus e includono:

  • OK - La richiesta è valida. Questo stato può essere anche se non sono state trovate route tra le origini e destinazioni. Vedi Elemento Codici di stato per le informazioni sullo stato a livello di elemento.
  • INVALID_REQUEST: la richiesta fornita era non valido. Questo è spesso dovuto alla mancanza di campi obbligatori. Consulta le elenco dei campi supportati riportato sopra.
  • MAX_ELEMENTS_EXCEEDED: il prodotto di origine e di destinazione supera il limite per query.
  • MAX_DIMENSIONS_EXCEEDED - La tua richiesta conteneva ulteriori informazioni oltre 25 origini o più di 25 destinazioni.
  • OVER_QUERY_LIMIT - La tua richiesta ha richiesto troppi elementi nel periodo di tempo consentito. La richiesta dovrebbe avrà esito positivo se riprovi dopo un periodo di tempo ragionevole.
  • REQUEST_DENIED: il servizio ha negato l'uso dell'elemento servizio Distance Matrix della tua pagina web.
  • UNKNOWN_ERROR: impossibile eseguire una richiesta di Distance Matrix a causa di un errore del server. La richiesta potrebbe avere esito positivo se provi di nuovo.

Codici di stato dell'elemento

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

  • NOT_FOUND: l'origine e/o la destinazione di questo impossibile geocodificare l'accoppiamento.
  • OK: la risposta contiene un risultato valido.
  • ZERO_RESULTS: non è stato trovato alcun percorso tra le origine e destinazione.

Analisi dei risultati

L'oggetto DistanceMatrixResponse contiene uno 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];
      }
    }
  }
}