Richiesta e risposta dell'API Distance Matrix (legacy)

Sviluppatori dello Spazio economico europeo (SEE)

Introduzione

Una richiesta API Distance Matrix (Legacy) ha il seguente formato:

https://maps.googleapis.com/maps/api/distancematrix/outputFormat?parameters

dove outputFormat può essere uno dei seguenti valori:

  • json (consigliato) indica l'output in formato JSON (JavaScript Object Notation).
  • xml indica l'output in formato XML.

Alcuni parametri sono obbligatori, altri invece sono facoltativi. Come è consuetudine negli URL, tutti i parametri sono separati dal carattere e commerciale (&). Tutti i caratteri riservati (ad esempio il segno più "+") devono essere codificati nell'URL. L'elenco dei parametri e dei relativi valori possibili è riportato di seguito.

Parametri obbligatori

  • destinazioni

    Una o più località da utilizzare come punto di arrivo per il calcolo della distanza e del tempo di percorrenza. Le opzioni per il parametro destinations sono le stesse del parametro origins.

  • origins

    Il punto di partenza per il calcolo della distanza e del tempo di percorrenza. Puoi fornire una o più località separate dalla barra verticale (|), sotto forma di ID luogo, indirizzo o coordinate di latitudine/longitudine:

    • ID luogo: se fornisci un ID luogo, devi anteporre il prefisso place_id:.
    • Indirizzo: se passi un indirizzo, il servizio geocodifica la stringa e la converte in una coordinata di latitudine/longitudine per calcolare la distanza. Questa coordinata potrebbe essere diversa da quella restituita dall'API Geocoding, ad esempio l'ingresso di un edificio anziché il suo centro.
      Nota: è preferibile utilizzare gli ID luogo anziché gli indirizzi o le coordinate di latitudine/longitudine. L'utilizzo delle coordinate comporterà sempre l'aggancio del punto alla strada più vicina a queste coordinate, che potrebbe non essere un punto di accesso alla proprietà o anche una strada che porta rapidamente o in sicurezza alla destinazione. L'utilizzo dell'indirizzo fornirà la distanza dal centro dell'edificio, anziché da un ingresso dell'edificio.
    • Coordinate: se passi le coordinate di latitudine/longitudine, queste verranno agganciate alla strada più vicina. È preferibile passare un ID luogo. Se passi le coordinate, assicurati che non ci siano spazi tra i valori di latitudine e longitudine.
    • I Plus Code devono essere formattati come codice globale o codice composto. Formatta i Plus Code come mostrato di seguito (i segni più vengono convertiti in caratteri di escape URL %2B e gli spazi vengono convertiti in caratteri di escape URL %20):
      • Un codice globale è un prefisso di 4 caratteri e un codice locale di almeno 6 caratteri (849VCWC8+R9 è codificato in 849VCWC8%2BR9).
      • codice composto è un codice locale di almeno sei caratteri con una posizione esplicita (CWC8+R9 Mountain View, CA, USA è codificato in CWC8%2BR9%20Mountain%20View%20CA%20USA).
    • Polilinea codificata In alternativa, puoi fornire un insieme di coordinate codificate utilizzando l'algoritmo per polilinee codificate. Questo è particolarmente utile se hai un numero elevato di punti di origine, perché l'URL è notevolmente più breve quando utilizzi 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 |. Ad esempio: 
        origins=enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:|enc:udymA{~bxM:

Parametri facoltativi

  • arrival_time

    Specifica l'orario di arrivo preferito per le indicazioni per il trasporto pubblico, in secondi dalla mezzanotte del 1° gennaio 1970 UTC. Puoi specificare departure_time o arrival_time, ma non entrambi. Tieni presente che arrival_time deve essere specificato come numero intero.

  • evitare

    È possibile calcolare le distanze rispettando determinate limitazioni. Le limitazioni sono indicate dall'utilizzo del parametro avoid e da un argomento di questo parametro che indica la limitazione da evitare. Sono supportate le seguenti limitazioni:

    • tolls indica che il percorso calcolato deve evitare strade/ponti a pedaggio.
    • highways indica che il percorso calcolato deve evitare le autostrade.
    • ferries indica che il percorso calcolato deve evitare i traghetti.
    • indoor indica che il percorso calcolato deve evitare le scale interne per le indicazioni stradali a piedi e per il trasporto pubblico.

    È possibile richiedere un percorso che eviti qualsiasi combinazione di pedaggi, autostrade e traghetti passando entrambe le limitazioni al parametro avoid. Ad esempio avoid=tolls|highways|ferries.

    Nota: l'aggiunta di limitazioni non preclude i percorsi che includono la caratteristica limitata, ma indirizza il risultato verso percorsi più favorevoli.

  • departure_time

    Specifica l'orario di partenza preferito. Puoi specificare l'ora come numero intero in secondi dalla mezzanotte del 1° gennaio 1970 UTC. Se viene specificato un valore departure_time successivo a 9999-12-31T23:59:59.999999999Z, l'API utilizzerà il valore di riserva departure_time 9999-12-31T23:59:59.999999999Z. In alternativa, puoi specificare il valore now, che imposta l'ora di partenza sull'ora corrente (con un'approssimazione al secondo più vicino). L'orario di partenza può essere specificato in due casi:

    • Per le richieste in cui la modalità di viaggio è il trasporto pubblico: puoi facoltativamente specificare departure_time o arrival_time. Se non viene specificato nessuno dei due orari, departure_time viene impostato per impostazione predefinita su ora (ovvero l'orario di partenza viene impostato per impostazione predefinita sull'ora corrente).
    • Per le richieste in cui la modalità di viaggio è la guida: puoi specificare departure_time per ricevere un percorso e una durata del viaggio (campo di risposta: duration_in_traffic) che tengono conto delle condizioni del traffico. Il valore departure_time deve essere impostato sull'ora corrente o su un'ora futura. Non può essere una data passata.
    Nota: se l'ora di partenza non è specificata, la scelta del percorso e della durata si basa sulla rete stradale e sulle condizioni medie del traffico indipendenti dal tempo. I risultati di una determinata richiesta possono variare nel tempo a causa di modifiche alla rete stradale, condizioni del traffico medie aggiornate e natura distribuita del servizio. I risultati possono anche variare tra percorsi quasi equivalenti in qualsiasi momento o frequenza.
    Nota: le richieste di Distance Matrix che specificano departure_time quando mode=driving sono limitate a un massimo di 100 elementi per richiesta. Il numero di origini moltiplicato per il numero di destinazioni definisce il numero di elementi.

  • language

    La lingua in cui restituire i risultati.

    • Consulta l'elenco delle lingue supportate. Google aggiorna spesso le lingue supportate, pertanto questo elenco potrebbe non essere esaustivo.
    • Se language non viene fornito, l'API tenta di utilizzare la lingua preferita specificata nell'intestazione Accept-Language.
    • L'API fa del suo meglio per fornire un indirizzo leggibile sia per l'utente sia per le persone del posto. Per raggiungere questo obiettivo, restituisce gli indirizzi nella lingua locale, traslitterati in un alfabeto leggibile dall'utente, se necessario, rispettando la lingua preferita. Tutti gli altri indirizzi vengono restituiti nella lingua preferita. I componenti dell'indirizzo vengono restituiti tutti 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 geocodificatore interpreta le abbreviazioni in modo diverso a seconda della lingua, ad esempio le abbreviazioni per i tipi di strade o i sinonimi che potrebbero essere validi in una lingua ma non in un'altra. Ad esempio, utca e tér sono sinonimi di via in ungherese.

  • modalità

    Per il calcolo di distanze e indicazioni stradali, puoi specificare la modalità di trasporto da utilizzare. Per impostazione predefinita, viene utilizzata la modalità DRIVING. Per impostazione predefinita, le indicazioni stradali vengono calcolate come indicazioni per la guida. Sono supportate le seguenti modalità di viaggio:

    • driving (predefinito) indica le indicazioni stradali o la distanza standard utilizzando la rete stradale.
    • walking richiede indicazioni a piedi o distanza utilizzando percorsi pedonali e marciapiedi (se disponibili).
    • bicycling richiede indicazioni in bicicletta o distanza utilizzando piste ciclabili e strade preferite (se disponibili).
    • transit richiede indicazioni stradali o distanza utilizzando i percorsi dei mezzi pubblici (se disponibili). Se imposti la modalità su mezzi pubblici, puoi facoltativamente specificare un valore departure_time o arrival_time. Se non viene specificato nessuno dei due orari, departure_time viene impostato per impostazione predefinita su ora (ovvero l'orario di partenza viene impostato per impostazione predefinita sull'ora corrente). Se vuoi, puoi anche includere un transit_mode e/o un transit_routing_preference.
    Nota: a volte le indicazioni in bicicletta e a piedi potrebbero non includere percorsi pedonali o ciclabili chiari, pertanto queste indicazioni restituiranno avvisi nel risultato restituito che devi mostrare all'utente.
    Nota: i percorsi con il trasporto pubblico sono disponibili per un massimo di 7 giorni nel passato o di 100 giorni nel futuro, in base alla disponibilità delle informazioni sul trasporto pubblico fornite dai fornitori di dati. Gli orari del trasporto pubblico cambiano di frequente, le corse disponibili possono variare nel tempo e non è garantito che i risultati delle previsioni siano coerenti con largo anticipo.

  • regione

    Il codice regione, specificato come valore di due caratteri ccTLD ("dominio di primo livello"). La maggior parte dei codici ccTLD è identica ai codici ISO 3166-1, con alcune eccezioni degne di nota. Ad esempio, il ccTLD del Regno Unito è "uk" (.co.uk), mentre il suo codice ISO 3166-1 è"gb " (tecnicamente per l'entità "Regno Unito di Gran Bretagna e Irlanda del Nord").

  • traffic_model

    Specifica le ipotesi da utilizzare per il calcolo del 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 parametro traffic_model può essere specificato solo per le indicazioni stradali in cui la richiesta include un departure_time. I valori disponibili per questo parametro sono:

    • best_guess (predefinito) indica che il valore duration_in_traffic restituito deve essere la migliore stima 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ù departure_time è vicino al momento attuale.
    • pessimistic indica che il valore duration_in_traffic restituito dovrebbe essere superiore al tempo di percorrenza effettivo nella maggior parte dei giorni, anche se in alcuni giorni con condizioni del traffico particolarmente negative potrebbe superare questo valore.
    • optimistic indica che il valore duration_in_traffic restituito deve essere inferiore al tempo di percorrenza effettivo nella maggior parte dei giorni, anche se occasionalmente, in giorni con condizioni del traffico particolarmente favorevoli, il tempo di percorrenza potrebbe essere inferiore a questo valore.

    Il valore predefinito di best_guess fornirà le previsioni più utili per la stragrande maggioranza dei casi d'uso. È possibile che la previsione del tempo di percorrenza di best_guess sia inferiore a optimistic o, in alternativa, superiore a pessimistic, a causa del modo in cui il modello predittivo di best_guess integra le informazioni sul traffico in tempo reale.

  • transit_mode

    Specifica una o più modalità di trasporto preferite. Questo parametro può essere specificato solo per le indicazioni per il trasporto pubblico. Il parametro supporta i seguenti argomenti:

    • bus indica che il percorso calcolato deve preferire il viaggio in autobus.
    • subway indica che il percorso calcolato deve preferire il viaggio in metropolitana.
    • train indica che il percorso calcolato deve preferire il viaggio in treno.
    • tram indica che il percorso calcolato deve preferire il viaggio in tram e metropolitana leggera.
    • rail indica che il percorso calcolato deve preferire il viaggio in treno, tram, metropolitana leggera e metropolitana. Equivale a transit_mode=train|tram|subway.

  • transit_routing_preference

    Specifica le preferenze per i percorsi con il trasporto pubblico. Utilizzando questo parametro, puoi influenzare le opzioni restituite, anziché accettare il percorso migliore predefinito scelto dall'API. Questo parametro può essere specificato solo per le indicazioni per il trasporto pubblico. Il parametro supporta i seguenti argomenti:

    • less_walking indica che il percorso calcolato deve preferire tratti a piedi limitati.
    • fewer_transfers indica che il percorso calcolato deve preferire un numero limitato di cambi.

  • unità

    Specifica il sistema di unità da utilizzare per la visualizzazione dei risultati.

    Nota: questa impostazione del sistema di unità di misura influisce solo sul testo visualizzato nei campi della distanza. I campi relativi alla distanza contengono anche valori che sono sempre espressi in metri.

Esempi di richieste

Questo esempio utilizza le coordinate di latitudine/longitudine per specificare le coordinate della destinazione:

URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=40.659569%2C-73.933783%7C40.729029%2C-73.851524%7C40.6860072%2C-73.6334271%7C40.598566%2C-73.7527626
  &origins=40.6655101%2C-73.89188969999998
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=40.6655101%2C-73.89188969999998&destinations=40.659569%2C-73.933783%7C40.729029%2C-73.851524%7C40.6860072%2C-73.6334271%7C40.598566%2C-73.7527626&key=YOUR_API_KEY'

Questo esempio utilizza i Plus Code per specificare le coordinate della destinazione:

URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=San%20Francisco
  &origins=849VCWC8%2BR9
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=849VCWC8%2BR9&destinations=San%20Francisco&key=YOUR_API_KEY'

Questo esempio mostra la stessa richiesta utilizzando una polilinea codificata:

URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=enc%3A_kjwFjtsbMt%60EgnKcqLcaOzkGari%40naPxhVg%7CJjjb%40cqLcaOzkGari%40naPxhV%3A
  &origins=40.6655101%2C-73.89188969999998
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=40.6655101%2C-73.89188969999998&destinations=enc%3A_kjwFjtsbMt%60EgnKcqLcaOzkGari%40naPxhVg%7CJjjb%40cqLcaOzkGari%40naPxhV%3A&key=YOUR_API_KEY'

Informazioni sul traffico

Le informazioni sul traffico vengono utilizzate quando si applicano tutte le seguenti condizioni (queste sono le condizioni necessarie per ricevere il campo duration_in_traffic nella risposta di Distance Matrix):

  • Il parametro di viaggio mode è driving o non è specificato (driving è la modalità di viaggio predefinita).
  • La richiesta include un parametro departure_time valido. departure_time può essere impostato sull'ora corrente o su un'ora futura. Non può essere una data passata.

Se vuoi, puoi includere il parametro traffic_model nella richiesta per specificare le ipotesi da utilizzare per il calcolo del tempo nel traffico.

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

URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?departure_time=now
  &destinations=Lexington%2CMA%7CConcord%2CMA
  &origins=Boston%2CMA%7CCharlestown%2CMA
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=Boston%2CMA%7CCharlestown%2CMA&destinations=Lexington%2CMA%7CConcord%2CMA&departure_time=now&key=YOUR_API_KEY'

JSON

{
  "destination_addresses": ["Lexington, MA, USA", "Concord, MA, USA"],
  "origin_addresses": ["Boston, MA, USA", "Charlestown, Boston, MA, USA"],
  "rows":
    [
      {
        "elements":
          [
            {
              "distance": { "text": "33.3 km", "value": 33253 },
              "duration": { "text": "27 mins", "value": 1620 },
              "duration_in_traffic": { "text": "34 mins", "value": 2019 },
              "status": "OK",
            },
            {
              "distance": { "text": "41.5 km", "value": 41491 },
              "duration": { "text": "33 mins", "value": 1981 },
              "duration_in_traffic": { "text": "39 mins", "value": 2342 },
              "status": "OK",
            },
          ],
      },
      {
        "elements":
          [
            {
              "distance": { "text": "31.1 km", "value": 31100 },
              "duration": { "text": "26 mins", "value": 1543 },
              "duration_in_traffic": { "text": "29 mins", "value": 1754 },
              "status": "OK",
            },
            {
              "distance": { "text": "39.3 km", "value": 39338 },
              "duration": { "text": "32 mins", "value": 1904 },
              "duration_in_traffic": { "text": "35 mins", "value": 2077 },
              "status": "OK",
            },
          ],
      },
    ],
  "status": "OK",
}

XML


 OK
 Boston, MA, USA
 Charlestown, Boston, MA, USA
 Lexington, MA, USA
 Concord, MA, USA
 
  
   OK
   
    1620
    27 mins
   
   
    33253
    33.3 km
   
   
    2018
    34 mins
   
  
  
   OK
   
    1981
    33 mins
   
   
    41491
    41.5 km
   
   
    2342
    39 mins
   
  
 
 
  
   OK
   
    1543
    26 mins
   
   
    31100
    31.1 km
   
   
    1759
    29 mins
   
  
  
   OK
   
    1904
    32 mins
   
   
    39338
    39.3 km
   
   
    2077
    35 mins

Modificatori dei luoghi

Puoi utilizzare i modificatori di località per indicare in che modo i conducenti devono avvicinarsi a una determinata località, utilizzando il modificatore side_of_road per specificare quale lato della strada utilizzare o specificando un'intestazione per indicare la direzione di marcia corretta.

Specifica che i percorsi calcolati devono passare attraverso un lato specifico della strada

Quando specifichi una località, puoi richiedere che il percorso calcolato passi attraverso il lato della strada verso cui è orientato il waypoint utilizzando il prefisso side_of_road:. Ad esempio, questa richiesta restituirà la distanza per un percorso lungo in modo che il veicolo termini sul lato della strada verso cui è stato orientato il waypoint:

URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=side_of_road%3A37.7663444%2C-122.4412006
  &origins=37.7680296%2C-122.4375126
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=37.7680296%2C-122.4375126&destinations=side_of_road%3A37.7663444%2C-122.4412006&key=YOUR_API_KEY'

Quando utilizzi side_of_road: con polilinee codificate, il modificatore viene applicato a ogni località lungo la polilinea. Ad esempio, le due destinazioni in questa richiesta utilizzano entrambe il parametro:

URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=side_of_road%3Aenc%3A%7BoqeF%60fejV%5BnC%3A
  &origins=San%20Francisco%20City%20hall
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=San%20Francisco%20City%20hall&destinations=side_of_road%3Aenc%3A%7BoqeF%60fejV%5BnC%3A&key=YOUR_API_KEY'

Il modificatore side_of_road: può essere utilizzato solo con questa limitazione:

Specifica che i percorsi calcolati devono avere una direzione specifica

Quando specifichi una località, puoi richiedere che il percorso calcolato passi attraverso la località in una direzione specifica. Questa direzione è specificata con il prefisso heading=X:, dove X è un valore intero in gradi compreso tra 0 (incluso) e 360 (escluso). Un'intestazione pari a 0 indica il nord, 90 indica l'est, continuando in senso orario. Ad esempio, in questa richiesta il percorso calcolato va verso est dall'origine, poi fa un'inversione a U:

URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=37.773245%2C-122.469502
  &origins=heading%3D90%3A37.773279%2C-122.468780
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=heading%3D90%3A37.773279%2C-122.468780&destinations=37.773245%2C-122.469502&key=YOUR_API_KEY'

Il modificatore heading=X: può essere utilizzato solo con queste limitazioni:

  • Il parametro di viaggio mode è driving, bicycling o non è specificato (driving è la modalità di viaggio predefinita).
  • Il modificatore side_of_road non è specificato per la stessa località.
  • La località è specificata con un valore di latitudine/longitudine. Non puoi utilizzare heading con indirizzi, ID luogo o polilinee codificate.

Richieste e risposte di Distance Matrix

Di seguito è riportato un esempio di richiesta HTTP che richiede la distanza e la durata da Vancouver, BC, Canada e da Seattle, WA, USA, a San Francisco, CA, USA e a Victoria, BC, Canada.

URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=San%20Francisco%7CVictoria%20BC
  &language=fr-FR
  &mode=bicycling
  &origins=Vancouver%20BC%7CSeattle
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=Vancouver%20BC%7CSeattle&destinations=San%20Francisco%7CVictoria%20BC&mode=bicycling&language=fr-FR&key=YOUR_API_KEY'

Questa richiesta restituirà quattro elementi: due origini per due destinazioni:

Da Vancouver a San Francisco Da Vancouver a Victoria
Da Seattle a San Francisco Da Seattle a Victoria

I risultati vengono restituiti in righe, ognuna delle quali contiene un'origine associata a ogni destinazione.

JSON

{
  "destination_addresses":
    ["San Francisco, Californie, États-Unis", "Victoria, BC, Canada"],
  "origin_addresses":
    ["Vancouver, BC, Canada", "Seattle, Washington, États-Unis"],
  "rows":
    [
      {
        "elements":
          [
            {
              "distance": { "text": "1 712 km", "value": 1711765 },
              "duration": { "text": "3 jours 16 heures", "value": 318119 },
              "status": "OK",
            },
            {
              "distance": { "text": "140 km", "value": 139695 },
              "duration": { "text": "6 heures 49 minutes", "value": 24567 },
              "status": "OK",
            },
          ],
      },
      {
        "elements":
          [
            {
              "distance": { "text": "1 452 km", "value": 1451704 },
              "duration": { "text": "3 jours 2 heures", "value": 266680 },
              "status": "OK",
            },
            {
              "distance": { "text": "146 km", "value": 146500 },
              "duration": { "text": "2 heures 53 minutes", "value": 10374 },
              "status": "OK",
            },
          ],
      },
    ],
  "status": "OK",
}

XML


 OK
 Vancouver, BC, Canada
 Seattle, Washington, États-Unis
 San Francisco, Californie, États-Unis
 Victoria, BC, Canada
 
  
   OK
   
    318119
    3 jours 16 heures
   
   
    1711765
    1 712 km
   
  
  
   OK
   
    24567
    6 heures 49 minutes
   
   
    139695
    140 km
   
  
 
 
  
   OK
   
    266680
    3 jours 2 heures
   
   
    1451704
    1 452 km
   
  
  
   OK
   
    10374
    2 heures 53 minutes
   
   
    146500
    146 km

DistanceMatrixResponse

Campo Obbligatorio Tipo Descrizione
elemento obbligatorio Array<string>

Un array di indirizzi restituiti dall'API dalla tua richiesta originale. Come per origin_addresses, questi valori vengono localizzati, se opportuno. Questi contenuti devono essere letti così come sono. Non analizzare in modo programmatico gli indirizzi formattati.

elemento obbligatorio Array<string>

Un array di indirizzi restituiti dall'API dalla tua richiesta originale. Questi vengono formattati dal geocodificatore e localizzati in base al parametro della lingua passato con la richiesta. Questi contenuti devono essere letti così come sono. Non analizzare in modo programmatico gli indirizzi formattati.

elemento obbligatorio Array<DistanceMatrixRow>

Un array di elementi, ognuno dei quali contiene a sua volta un elemento status, duration e distance.

Per saperne di più, consulta DistanceMatrixRow.

elemento obbligatorio DistanceMatrixStatus

Contiene lo stato della richiesta e può contenere informazioni di debug per aiutarti a individuare il motivo per cui la richiesta non è andata a buon fine.

Per saperne di più, consulta DistanceMatrixStatus.

facoltativo stringa

Una stringa contenente il testo leggibile di eventuali errori riscontrati durante l'elaborazione della richiesta.

DistanceMatrixStatus

Codici di stato restituiti dal servizio.

  • OK indica che la risposta contiene un risultato valido.
  • INVALID_REQUEST indica che la richiesta fornita non era valida.
  • MAX_ELEMENTS_EXCEEDED indica che il prodotto delle origini e delle 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 una delle seguenti opzioni:
    • 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).
  • OVER_QUERY_LIMIT indica che il servizio ha ricevuto troppe richieste dalla tua applicazione nel periodo di tempo consentito.
  • REQUEST_DENIED indica che il servizio ha negato l'utilizzo del servizio Distance Matrix da parte della tua applicazione.
  • UNKNOWN_ERROR indica che non è stato possibile elaborare una richiesta Distance Matrix a causa di un errore del server. La richiesta potrebbe andare a buon fine se riprovi.

DistanceMatrixRow

Campo Obbligatorio Tipo Descrizione
elemento obbligatorio Array<DistanceMatrixElement>

Quando l'API Distance Matrix restituisce i risultati, li inserisce in un array di righe JSON. Anche se non vengono restituiti risultati (ad esempio se le origini e/o le destinazioni non esistono), viene comunque restituito un array vuoto.

Le righe sono ordinate in base ai valori nel parametro origin della richiesta. Ogni riga corrisponde a un'origine e ogni elemento all'interno della riga corrisponde a un accoppiamento dell'origine con un valore di destinazione.

Ogni array di righe contiene una o più voci di elementi, che a loro volta contengono le informazioni su una singola coppia origine-destinazione.

Per saperne di più, consulta DistanceMatrixElement.

DistanceMatrixElement

Campo Obbligatorio Tipo Descrizione
elemento obbligatorio DistanceMatrixElementStatus

Uno stato per l'elemento.

Per saperne di più, consulta DistanceMatrixElementStatus.

facoltativo TextValueObject

La distanza totale di questo percorso, espressa in metri (valore) e come testo. Il valore testuale utilizza il sistema di unità di misura specificato con il parametro unit della richiesta originale o la regione dell'origine.

Per saperne di più, consulta TextValueObject.

facoltativo TextValueObject

Il tempo necessario per percorrere questo itinerario, espresso in secondi (il campo value) e come testo. La rappresentazione testuale è localizzata in base al parametro della lingua della query.

Per saperne di più, consulta TextValueObject.

facoltativo TextValueObject

Il tempo necessario per percorrere questo itinerario, in base alle condizioni del traffico attuali e storiche. Consulta il parametro di richiesta traffic_model per le opzioni che puoi utilizzare per richiedere che il valore restituito sia ottimistico, pessimistico o una stima approssimativa. La durata è espressa in secondi (il campo value) e come testo. La rappresentazione testuale è localizzata in base al parametro della lingua della query. La durata nel traffico viene restituita solo se sono soddisfatte tutte le seguenti condizioni:

  • La richiesta include un parametro departure_time.
  • Le condizioni del traffico sono disponibili per il percorso richiesto.
  • Il parametro mode è impostato su driving.

Per saperne di più, consulta TextValueObject.

facoltativo Tariffa

Se presente, contiene la tariffa totale (ovvero i costi totali dei biglietti) su questo percorso. Questa proprietà viene restituita solo per le richieste di trasporto pubblico e solo per i fornitori di trasporto pubblico per i quali sono disponibili informazioni sulle tariffe.

Per saperne di più, consulta Tariffa.

Tariffa

La tariffa totale per il percorso.

{
  "currency" : "USD",
  "value" : 6,
  "text" : "$6.00"
}
Campo Obbligatorio Tipo Descrizione
elemento obbligatorio stringa

Un codice valuta ISO 4217 che indica la valuta in cui è espresso l'importo.

text

elemento obbligatorio stringa

L'importo totale della tariffa, formattato nella lingua richiesta.
elemento obbligatorio numero

L'importo totale della tariffa, nella valuta specificata.

DistanceMatrixElementStatus

  • OK indica che la risposta contiene un risultato valido.
  • NOT_FOUND indica che non è stato possibile geocodificare l'origine e/o la destinazione di questo accoppiamento.
  • ZERO_RESULTS indica che non è stato possibile trovare un percorso tra l'origine e la destinazione.
  • MAX_ROUTE_LENGTH_EXCEEDED indica che il percorso richiesto è troppo lungo e non può essere elaborato.

TextValueObject

Un oggetto contenente un valore numerico e la relativa rappresentazione testuale formattata.

Campo Obbligatorio Tipo Descrizione

text

elemento obbligatorio stringa

Valore stringa.
elemento obbligatorio numero

Valore numerico.