Introduzione

L’API Distance Matrix è un servizio che fornisce la distanza e il tempo di percorrenza per una matrice di origini e destinazioni. L’API restituisce informazioni in base al percorso consigliato tra i punti di inizio e di fine, come calcolato dall’API di Google Maps, ed è costituito da righe contenenti duration e distance valori per ogni coppia.

Nota: Questo servizio non restituisce informazioni dettagliate sul percorso. Le informazioni sul percorso possono essere ottenute passando la singola origine e destinazione desiderata all’API Directions.

Prima di iniziare

Questo documento è destinato agli sviluppatori che desiderano calcolare la distanza e il tempo di percorrenza tra un numero di punti all’interno delle mappe fornite da una delle API di Google Maps. Fornisce un’introduzione all’utilizzo dell’API e del materiale di riferimento sui parametri disponibili.

Prima di iniziare lo sviluppo con l’API Distance Matrix, esaminare i requisiti di autenticazione (è necessaria una chiave API) e le informazioni di utilizzo e fatturazione dell’API (è necessario abilitare la fatturazione sul progetto).

Matrice di Distanza richieste

Una Matrice di Distanza API richiesta assume la seguente forma:

dove outputFormat può essere uno dei seguenti valori:

• json (consigliato), indica l’uscita in JavaScript Object Notation (JSON); o
• xml, indica l’output in formato XML.

Nota: gli URL devono essere codificati correttamente per essere validi e sono limitati a 8192 caratteri per tutti i servizi web. Tieni presente questo limite quando costruisci i tuoi URL. Si noti che diversi browser, proxy e server possono avere limiti di caratteri URL diversi.

HTTPS o HTTP

La sicurezza è importante e HTTPS è raccomandato quando possibile, in particolare per le applicazioni che includono dati sensibili dell’utente, come la posizione di un utente, nelle richieste. L’utilizzo della crittografia HTTPS rende l’applicazione più sicura e più resistente a snooping o manomissioni.

Se HTTPS non è possibile, per accedere all’API della matrice di distanza su HTTP, utilizzare:

Parametri di richiesta

Alcuni parametri sono richiesti mentre altri sono facoltativi. Come è standard negli URL, tutti i parametri sono separati usando il carattere e commerciale (&). Tutti i caratteri riservati (ad esempio il segno più “+”) devono essere codificati URL.L’elenco dei parametri e dei loro possibili valori sono elencati di seguito.

Parametri richiesti

• origins — Il punto di partenza per il calcolo della distanza e del tempo di percorrenza. È possibile fornire una o più posizioni separate dal carattere pipe (|), sotto forma di un ID luogo, un indirizzo o coordinate di latitudine/longitudine:
  • Se si fornisce un ID luogo, è necessario prefiggerlo con place_id:. Puoi specificare un ID luogo solo se la richiesta include una chiave API o un ID client del piano Premium di Google Maps Platform. È possibile recuperare gli ID luogo dall’API Geocoding e dall’API Places (incluso il completamento automatico del luogo). Per un esempio di utilizzo degli ID luogo da Completamento automatico luogo, vedere Completamento automatico luogo e indicazioni. Per ulteriori informazioni sugli ID luogo, vedere Panoramica ID luogo.
  • Se si passa un indirizzo, il servizio geocodifica la stringa e la converte in una coordinata latitudine/longitudine per calcolare la distanza. Questa coordinata può essere diversa da quella restituita dall’API di Geocodifica, ad esempio un ingresso dell’edificio piuttosto che il suo centro.

    origins=Bobcaygeon+ON|24+Sussex+Drive+Ottawa+ON

    Nota: l’utilizzo degli ID luogo è preferito rispetto all’utilizzo degli indirizzi o delle coordinate di latitudine/longitudine. L’utilizzo delle coordinate comporterà sempre lo snap del punto alla strada più vicina a quelle coordinate, che potrebbe non essere un punto di accesso alla proprietà o anche una strada che porterà rapidamente o in modo sicuro alla destinazione.
  • Se si passano le coordinate di latitudine / longitudine, si agganceranno alla strada più vicina. Il passaggio di un ID luogo è preferito. Se si passano le coordinate, assicurarsi che non esista spazio tra i valori di latitudine e longitudine.

    origins=41.43206,-81.38992|-33.86748,151.20699

    origins=place_id:ChIJ3S-JXmauEmsRUcIaWtf4MzE

  • I codici Plus devono essere formattati come un codice globale o un codice composto. Formato più codici come mostrato qui (i segni più sono url-escape a %2Be gli spazi sono url-escape a %20):
    • il codice globale è un prefisso di 4 caratteri e un codice locale di 6 caratteri o più (849VCWC8+R9 è 849VCWC8%2BR9).
    • il codice composto è un codice locale di 6 caratteri o più con una posizione esplicita (CWC8 + R9 Mountain View, CA, USA è CWC8%2BR9%20Mountain%20View%20CA%20USA).
  • In alternativa, è possibile fornire un insieme codificato di coordinate utilizzando l’algoritmo polilinea codificato. Ciò è particolarmente utile se si dispone di un numero elevato di punti di origine, poiché l’URL è significativamente più breve quando si utilizza una polilinea codificata.
    • Le polilinee codificate devono essere precedute da enc:e seguite da due punti (:).Ad esempio: origins=enc:gfo}EtohhU:
    • Puoi anche includere più polilinee codificate, separate dal carattere pipe (|). Biru: origins=enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:|enc:udymA{~bxM:
• destinations — Una o più posizioni da utilizzare come punto di arrivo per il calcolo della distanza e del tempo di percorrenza. Le opzioni per il parametrodestinations sono le stesse del parametroorigins, descritto sopra.
• key — La chiave API dell’applicazione. Questa chiave identifica l’applicazione ai fini della gestione delle quote. Impara come ottenere una chiave.

  Nota: I clienti del piano Premium di Google Maps Platform possono utilizzare una chiave API o un ID client valido e una firma digitale nelle richieste della matrice di distanza. Ottieni maggiori informazioni sui parametri di autenticazione per i clienti del piano Premium.

Il seguente esempio utilizza le coordinate di latitudine / longitudine per specificare le coordinate di destinazione:

Il seguente esempio utilizza più codici per specificare le coordinate di destinazione:

Il seguente esempio mostra la stessa richiesta utilizzando una polilinea codificata:

Parametri opzionali

• mode(il valore predefinito èdriving) — Specifica la modalità di trasporto da utilizzare per calcolare la distanza. I valori validi e altri dettagli della richiesta sono specificati nella sezione Modalità di viaggio di questo documento.
• language — La lingua in cui restituire i risultati.
  • Vedere l’elenco delle lingue supportate. Google aggiorna spesso le lingue supportate, quindi questo elenco potrebbe non essere esaustivo.
  • Se language non viene fornito, l’API tenta di utilizzare la lingua preferita come specificato nell’intestazione Accept-Language o la lingua madre del dominio da cui viene inviata la richiesta.
  • L’API fa del suo meglio per fornire un indirizzo che sia leggibile sia per l’utente che per la gente del posto. Per raggiungere tale obiettivo, restituisce gli indirizzi stradali nella lingua locale, traslitterati in uno script leggibile dall’utente se necessario, osservando la lingua preferita. Tutti gli altri indirizzi vengono restituiti nella lingua preferita. I componenti dell’indirizzo vengono tutti restituiti nella stessa lingua, che viene scelta dal primo componente.
  • Se un nome non è disponibile nella lingua preferita, l’API utilizza la corrispondenza più vicina.
  • La lingua preferita ha una piccola influenza sull’insieme di risultati che l’API sceglie di restituire e sull’ordine in cui vengono restituiti. Il geocoder interpreta le abbreviazioni in modo diverso a seconda della lingua, ad esempio le abbreviazioni per i tipi di strada o i sinonimi che possono essere validi in una lingua ma non in un’altra. Ad esempio, utca e tér sono sinonimi di strada in ungherese.
• region — Il codice regionale, specificato come ccTLD (country code top-level domain) valore a due caratteri. La maggior parte dei codici ccTLD sono identici ai codici ISO 3166-1, con alcune eccezioni. Questo parametro influenzerà solo, non limiterà completamente, i risultati del geocoder. Se i risultati più rilevanti esistono al di fuori della regione specificata, possono essere inclusi.
• avoid — Introduce restrizioni al percorso. I valori validi sono specificati nella sezione Restrizioni di questo documento. È possibile specificare solo una restrizione.
• units — Specifica il sistema di unità da utilizzare quando si esprime la distanza come testo. Vedere la sezione Sistemi di unità di questo documento per ulteriori informazioni.
• arrival_time — Specifica l’orario di arrivo desiderato per le richieste di transito, in secondi dalla mezzanotte del 1 gennaio 1970 UTC. È possibile specificare departure_timeoarrival_time, ma non entrambi. Si noti che arrival_time deve essere specificato come un numero intero.
• departure_time — L’ora di partenza desiderata. È possibile specificare l’ora come numero intero in secondi dalla mezzanotte del 1 gennaio 1970 UTC. Se un departure_time oltre 9999-12-31T23:59:59.999999999 Z è specificato, l’API tornerà il departure_time per 9999-12-31T23:59:59.999999999 Z. in Alternativa, è possibile specificare un valore di now, che imposta l’orario di partenza per l’ora corrente (corretto al secondo più vicino). L’orario di partenza può essere specificato in due casi:
  • Per le richieste in cui la modalità di viaggio è transit: È possibile specificare opzionalmente uno dei departure_timeoarrival_time. Se non viene specificata nessuna delle due ore, il departure_time è impostato su now (ovvero, l’ora di partenza è impostata sull’ora corrente).
  • Per le richieste in cui è attiva la modalità di viaggio: è possibile specificaredeparture_time per ricevere un percorso e una durata del viaggio (campo di risposta:duration_in_traffic) che tengano conto delle condizioni del traffico. Questa opzione è disponibile solo se la richiesta contiene una chiave API valida o un ID client e una firma del piano Premium di Google Maps Platform validi. Il departure_time deve essere impostato sull’ora corrente o su un po ‘ di tempo in futuro. Non può essere nel passato.

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

    Nota: le richieste della matrice di distanza che specificanodeparture_time quandomode=driving sono limitate a un massimo di 100 elementi per richiesta. Il numero di origini per il numero di destinazioni definisce il numero di elementi.

• traffic_model (il valore predefinito èbest_guess) — Specifica le ipotesi da utilizzare per calcolare il 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 parametrotraffic_model può essere specificato solo per le richieste in cui la modalità di viaggio èdriving e in cui la richiesta include undeparture_time e solo se la richiesta include una chiave API o un ID client del piano Premium di Google Maps Platform. I valori disponibili per questo parametro sono:
  • best_guess(default) indica che ilduration_in_traffic restituito deve essere la migliore stima del tempo di percorrenza dato ciò che è noto sia sulle condizioni storiche del traffico che sul traffico in tempo reale. Il traffico in tempo reale diventa più importante quanto più vicino è departure_time.
  • pessimistic indica che ilduration_in_traffic restituito deve essere più lungo del tempo di percorrenza effettivo nella maggior parte dei giorni, anche se i giorni occasionali con condizioni di traffico particolarmente avverse possono superare questo valore.
  • optimistic indica che ilduration_in_traffic restituito deve essere più breve del tempo di percorrenza effettivo nella maggior parte dei giorni, anche se i giorni occasionali con condizioni di traffico particolarmente buone possono essere più veloci di questo valore.
• transit_mode — Specifica una o più modalità di transito preferite. Questo parametro può essere specificato solo per le richieste in cui modetransit. Il parametro supporta i seguenti argomenti:
  • bus indica che il percorso calcolato dovrebbe preferire il viaggio in autobus.
  • subway indica che il percorso calcolato dovrebbe preferire viaggiare in metropolitana.
  • train indica che il percorso calcolato dovrebbe preferire viaggiare in treno.
  • tram indica che il percorso calcolato dovrebbe preferire il viaggio in tram e metropolitana leggera.
  • rail indica che il percorso calcolato dovrebbe preferire viaggiare in treno, tram, metropolitana leggera e metropolitana. Questo è equivalente a transit_mode=train|tram|subway.
• transit_routing_preference — Specifica le preferenze per le richieste di transito. Utilizzando questo parametro, è possibile modificare le opzioni restituite, piuttosto che accettare il percorso migliore predefinito scelto dall’API. Questo parametro può essere specificato solo per le richieste in cui modetransit. Il parametro supporta i seguenti argomenti:
  • less_walking indica che il percorso calcolato dovrebbe preferire quantità limitate di camminare.
  • fewer_transfers indica che il percorso calcolato dovrebbe preferire un numero limitato di trasferimenti.

Modalità di viaggio

Per il calcolo delle distanze, è possibile specificare il trasportomode da utilizzare. Per impostazione predefinita, le distanze vengono calcolate per la modalità di guida. Sono supportate le seguenti modalità di viaggio:

• driving (default) indica il calcolo della distanza utilizzando la rete stradale.
• walking richiede il calcolo della distanza per camminare attraverso percorsi pedonali & marciapiedi (dove disponibili).
• bicycling richiede il calcolo della distanza per andare in bicicletta tramite piste ciclabili& strade preferite (se disponibili).
• transit richiede il calcolo della distanza tramite percorsi di trasporto pubblico (se disponibile). Questo valore può essere specificato solo se la richiesta include una chiave API o un ID client del piano Premium di Google Maps Platform. Se si imposta la modalità sutransit è possibile specificare opzionalmente undeparture_time o unarrival_time. Se non viene specificata nessuna delle due ore, il departure_time è impostato su now (ovvero, l’ora di partenza è impostata sull’ora corrente). È anche possibile includere opzionalmente untransit_mode e/o untransit_routing_preference.

informazioni sul Traffico

informazioni sul Traffico è utilizzato quando tutte le seguenti condizioni (sono queste le condizioni necessarie per ricevere il duration_in_traffic campo nella Matrice di Distanza la risposta):

• viaggio mode parametro driving o non è specificato (driving è l’impostazione predefinita della modalità di viaggio).
• La richiesta include un parametro departure_time valido. Il departure_time può essere impostato per l’ora corrente o un po ‘ di tempo in futuro. Non può essere nel passato.

Facoltativamente, è possibile includere il parametrotraffic_model nella richiesta per specificare le ipotesi da utilizzare nel calcolo del tempo nel traffico.

Il seguente URL avvia una richiesta di matrice di distanza per le distanze di guida tra Boston, MA o Charlestown, MA e Lexington, MA e Concord, MA. La richiesta include un orario di partenza, che soddisfa tutti i requisiti per restituire il campo duration_in_traffic nella risposta della matrice di distanza.

Restrizioni

Le distanze possono essere calcolate rispettando determinate restrizioni. Le restrizioni sono indicate dall’uso del parametroavoid e un argomento a tale parametro che indica la restrizione da evitare. Le seguenti restrizioni sono supportati:

• avoid=tolls
• avoid=highways
• avoid=ferries
• avoid=indoor

* Nota: l’aggiunta di restrizioni non preclude itinerari che includono il limitato funzione di pregiudizi il risultato più favorevole percorsi.

Sistemi di unità

I risultati della matrice di distanza contengonotext all’interno didistance campi per indicare la distanza del percorso calcolato. Il sistema di unità da utilizzare può essere specificato:

• units=metric (default) restituisce distanze in chilometri e metri.
• units=imperial restituisce distanze in miglia e piedi.

* Nota: questa impostazione del sistema di unità influisce solo sui campitext visualizzati all’interno didistance. I campidistance contengono anchevalues che sono sempre espressi in metri.

Risposte della matrice di distanza

Le risposte alle query API della matrice di distanza vengono restituite nel formato indicato dal flagoutput all’interno del percorso della richiesta URL.

Di seguito sono riportate due richieste HTTP di esempio, che richiedono distanza e durata da Vancouver, BC, Canada e da Seattle, WA, USA, a San Francisco, CA, USA e a Victoria, BC, Canada.

Questa richiesta dimostra l’utilizzo del flag JSON output :

Questa richiesta viene illustrato l’utilizzo di XML output bandiera:

con la richiesta di restituire quattro elementi – due origini volte due destinazioni:

i Risultati sono restituiti in righe, ogni riga contiene un origine accoppiato con ogni destinazione.

Puoi testarlo inserendo l’URL nel tuo browser web (assicurati di sostituire YOUR_API_KEY con la tua chiave API effettiva).

Selezionare le schede sottostanti per visualizzare le risposte JSON e XML di esempio.

Il resto di questa documentazione utilizzerà la sintassi JSON.

Gli elementi di risposta della matrice di distanza

Le risposte della matrice di distanza contengono i seguenti elementi radice:

• status contiene metadati sulla richiesta. Vedere i codici di stato di seguito.
• origin_addresses contiene un array di indirizzi restituiti dall’API dalla richiesta originale. Questi sono formattati dal geocoder e localizzati in base al parametrolanguage passato con la richiesta.
• destination_addresses contiene un array di indirizzi restituiti dall’API dalla richiesta originale. Come con origin_addresses, questi sono localizzati se appropriato.
• rows contiene un array di elements, che a sua volta contengono ciascuno un statusduration e distance elemento.

Codici di stato

I campistatus all’interno dell’oggetto response contengono lo stato della richiesta e possono contenere utili informazioni di debug. L’API Distance Matrix restituisce un campo di stato di primo livello, con informazioni sulla richiesta in generale, nonché un campo di stato per ogni campo elemento, con informazioni su quel particolare accoppiamento origine-destinazione.

Codici di stato di primo livello

• OKindica che la risposta contiene unresult valido.
• INVALID_REQUEST indica che la richiesta fornita non era valida.
• MAX_ELEMENTS_EXCEEDED indica che il prodotto di origini e destinazioni supera il limite per query.
• MAX_DIMENSIONS_EXCEEDED indica che il numero di origini o destinazioni supera il limite per query.
• OVER_DAILY_LIMIT indica uno dei seguenti elementi:
  • La chiave API è mancante o non valida.
  • La fatturazione non è stata abilitata sul tuo account.
  • È stato superato un limite di utilizzo autoimposto.
  • Il metodo di pagamento fornito non è più valido (ad esempio, una carta di credito è scaduta).

  Vedere le mappe FAQ per imparare a risolvere questo problema.

• OVER_QUERY_LIMIT indica che il servizio ha ricevuto troppe richieste dall’applicazione entro il periodo di tempo consentito.
• REQUEST_DENIED indica che il servizio ha negato l’uso del servizio Matrice di distanza dall’applicazione.
• UNKNOWN_ERROR indica che una richiesta della matrice di distanza non può essere elaborata a causa di un errore del server. La richiesta potrebbe avere esito positivo se si riprova.

Codici di stato a livello di elemento

• OKindica che la risposta contiene unresult valido.
• NOT_FOUND indica che l’origine e / o la destinazione di questa associazione non possono essere geocodificate.
• ZERO_RESULTS indica che non è stato trovato alcun percorso tra l’origine e la destinazione.
• MAX_ROUTE_LENGTH_EXCEEDED indica che il percorso richiesto è troppo lungo e non può essere elaborato.

Messaggi di errore

Quando il codice di stato di livello superiore è diverso daOK, potrebbe esserci un campo aggiuntivoerror_message all’interno dell’oggetto Distance Matrix response. Questo campo contieneinformazioni più dettagliate sui motivi dietro il codice di stato specificato.

Nota: Questo campo non è garantito per essere sempre presente e itscontent è soggetto a modifiche.

Righe

Quando l’API della matrice di distanza restituisce i risultati, li posiziona all’interno di un array JSONrows. Anche se non vengono restituiti risultati (ad esempio quando le origini e/o le destinazioni non esistono), restituisce comunque un array vuoto. Le risposte XML sono costituite da zero o più elementi<row>.

Le righe vengono ordinate in base ai valori nel parametroorigin della richiesta. Ogni riga corrisponde a un’origine e ognielement all’interno di tale riga corrisponde a un accoppiamento dell’origine con un valoredestination.

Ogni array row contiene una o più voci element, che a loro volta contengono le informazioni su una singola associazione origine-destinazione.

Elementi

Le informazioni su ciascun accoppiamento origine-destinazione vengono restituite in una voceelement. Un element contiene i seguenti campi:

• status: vedere Codici di stato per un elenco di possibili codici di stato.
• duration: Il tempo necessario per percorrere questa rotta, espresso in secondi (il campo value) e come text. La rappresentazione testuale è localizzata in base al parametro language della query.

• duration_in_traffic: Il tempo necessario per percorrere questo percorso, in base alle condizioni attuali e storiche del traffico. Vedere il parametro di richiestatraffic_model per le opzioni che è possibile utilizzare per richiedere che il valore restituito sia ottimista, pessimista o una stima ottimale. La durata è espressa in secondi (il campovalue) e cometext. La rappresentazione testuale è localizzata in base al parametro language della query. La durata nel traffico viene restituita solo se tutte le seguenti condizioni sono vere:

  • La richiesta include un parametro departure_time.
  • La richiesta include una chiave API valida o un ID client e una firma validi di Google Maps Platform Premium Plan.
  • Le condizioni del traffico sono disponibili per il percorso richiesto.
  • Il parametromode è impostato sudriving.
• distance: La distanza totale di questo percorso, espressa in metri (value) e cometext. Il valore testuale utilizza il sistema di unità specificato con il parametrounit della richiesta originale o della regione di origine.
• fare: Se presente, contiene la tariffa totale (cioè il costo totale del biglietto) su questa rotta. Questa proprietà viene restituita solo per le richieste di transito e solo per i fornitori di transito in 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.
  • text: L’importo totale della tariffa, formattato nella lingua richiesta.

di Seguito è un esempio di un element che contiene informazioni tariffarie:

Il parametro sensore

Le API di Google Maps in precedenza necessario includere ilsensor parametro per indicare se l’applicazione utilizzata asensor per determinare la posizione dell’utente. Questo parametro non è piùrichiesto.