Method: computeRouteMatrix

Recupera un elenco di origini e destinazioni e restituisce un flusso contenente informazioni sul percorso per ogni combinazione di origine e destinazione.

NOTA: questo metodo richiede l'indicazione di una maschera per il campo della risposta nell'input. Puoi fornire la maschera del campo di risposta utilizzando il parametro URL $fields o fields oppure l'intestazione HTTP/gRPC X-Goog-FieldMask (consulta le intestazioni e i parametri URL disponibili). Il valore è un elenco di percorsi dei campi separati da virgole. Consulta questa documentazione dettagliata su come creare i percorsi dei campi.

Ad esempio, in questo metodo:

  • Maschera per tutti i campi disponibili (per l'ispezione manuale): X-Goog-FieldMask: *
  • Maschera per il campo di durate dei percorsi, distanze, stato dell'elemento, condizione e indici degli elementi (un esempio di configurazione di produzione): X-Goog-FieldMask: originIndex,destinationIndex,status,condition,distanceMeters,duration

È fondamentale includere status nella maschera del campo, altrimenti tutti i messaggi sembreranno corretti. Google sconsiglia l'utilizzo della maschera del campo di risposta con caratteri jolly (*) perché:

  • La selezione dei soli campi necessari consente al nostro server di salvare i cicli di calcolo, consentendoci di restituirti il risultato con una latenza inferiore.
  • La selezione dei soli campi necessari nel job di produzione garantisce prestazioni di latenza stabili. In futuro potremmo aggiungere altri campi di risposta e questi nuovi campi potrebbero richiedere tempi di calcolo aggiuntivi. Se selezioni tutti i campi o tutti i campi al livello più alto, potresti riscontrare un peggioramento delle prestazioni perché qualsiasi nuovo campo che aggiungiamo verrà incluso automaticamente nella risposta.
  • La selezione solo dei campi necessari comporta una riduzione delle dimensioni della risposta e, di conseguenza, una velocità effettiva di rete superiore.

Richiesta HTTP

POST https://routes.googleapis.com/distanceMatrix/v2:computeRouteMatrix

L'URL utilizza la sintassi di transcodifica gRPC.

Corpo della richiesta

Il corpo della richiesta contiene dati con la seguente struttura:

Rappresentazione JSON
{
  "origins": [
    {
      object (RouteMatrixOrigin)
    }
  ],
  "destinations": [
    {
      object (RouteMatrixDestination)
    }
  ],
  "travelMode": enum (RouteTravelMode),
  "routingPreference": enum (RoutingPreference),
  "departureTime": string,
  "arrivalTime": string,
  "languageCode": string,
  "regionCode": string,
  "extraComputations": [
    enum (ExtraComputation)
  ],
  "trafficModel": enum (TrafficModel),
  "transitPreferences": {
    object (TransitPreferences)
  }
}
Campi
origins[]

object (RouteMatrixOrigin)

Obbligatorio. Array di origini, che determina le righe della matrice della risposta. Alla cardinalità delle origini e delle destinazioni si applicano diverse limitazioni di dimensioni:

  • La somma del numero di origini e del numero di destinazioni specificate come placeId o address non deve essere maggiore di 50.
  • Il prodotto tra numero di origini × numero di destinazioni non deve essere superiore in ogni caso a 625.
  • Il prodotto del numero di origini × numero di destinazioni non deve essere maggiore di 100 se routingPreference è impostato su TRAFFIC_AWARE_OPTIMAL.
  • Il prodotto del numero di origini × numero di destinazioni non deve essere maggiore di 100 se il valore di TravelMode è impostato su TRANSIT.
destinations[]

object (RouteMatrixDestination)

Obbligatorio. Array di destinazioni, che determina le colonne della matrice di risposta.

travelMode

enum (RouteTravelMode)

Campo facoltativo. Specifica la modalità di trasporto.

routingPreference

enum (RoutingPreference)

Campo facoltativo. Specifica come calcolare la route. Il server tenta di utilizzare la preferenza di routing selezionata per calcolare la route. Se la preferenza di routing genera un errore o una latenza molto lunga, viene restituito un errore. Puoi specificare questa opzione solo quando travelMode è DRIVE o TWO_WHEELER, altrimenti la richiesta non va a buon fine.

departureTime

string (Timestamp format)

Campo facoltativo. L'orario di partenza. Se non imposti questo valore, il valore predefinito sarà l'ora in cui hai effettuato la richiesta. NOTA: è possibile specificare un departureTime solo in passato quando RouteTravelMode è impostato su TRANSIT.

Un timestamp in formato "Zulu" UTC RFC3339, con risoluzione in nanosecondi e fino a nove cifre frazionarie. Esempi: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".

arrivalTime

string (Timestamp format)

Campo facoltativo. L'ora di arrivo. NOTA: può essere impostato solo quando il criterio RouteTravelMode è impostato su TRANSIT. Puoi specificare departureTime o arrivalTime, ma non entrambi.

Un timestamp in formato "Zulu" UTC RFC3339, con risoluzione in nanosecondi e fino a nove cifre frazionarie. Esempi: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".

languageCode

string

Campo facoltativo. Il codice lingua BCP-47, ad esempio "en-US" o "sr-Latn". Per ulteriori informazioni, consulta la sezione Identificatore impostazioni internazionali Unicode. Consulta la pagina Supporto delle lingue per consultare l'elenco delle lingue supportate. Se non fornisci questo valore, la lingua di visualizzazione viene dedotta dalla località della prima origine.

regionCode

string

Campo facoltativo. Il codice regione specificato come valore di due caratteri ccTLD ("dominio di primo livello"). Per ulteriori informazioni, consulta l'articolo sui domini di primo livello nazionali.

extraComputations[]

enum (ExtraComputation)

Campo facoltativo. Un elenco di calcoli aggiuntivi che possono essere utilizzati per completare la richiesta. Nota: questi calcoli aggiuntivi potrebbero restituire campi aggiuntivi nella risposta. Questi campi aggiuntivi devono essere specificati anche nella maschera del campo affinché vengano restituiti nella risposta.

trafficModel

enum (TrafficModel)

Campo facoltativo. Specifica le ipotesi da utilizzare per il calcolo del tempo nel traffico. Questa impostazione influisce sul valore restituito nel campo della durata nel campo RouteMatrixElement, che contiene il tempo previsto nel traffico in base alle medie storiche. Da RoutingPreference a TRAFFIC_AWARE_OPTIMAL e da RouteTravelMode a DRIVE. Il valore predefinito è BEST_GUESS se viene richiesto il traffico e TrafficModel non è specificato.

transitPreferences

object (TransitPreferences)

Campo facoltativo. Specifica le preferenze che influiscono sul percorso restituito per TRANSIT route. NOTA: puoi specificare un transitPreferences solo se RouteTravelMode è impostato su TRANSIT.

Corpo della risposta

Contiene informazioni di route calcolate per una coppia di origine/destinazione nell'API v2.computeRouteMatrix. Questo protocollo può essere trasmesso in streaming al client.

In caso di esito positivo, il corpo della risposta contiene dati con la seguente struttura:

Rappresentazione JSON
{
  "status": {
    object (Status)
  },
  "condition": enum (RouteMatrixElementCondition),
  "distanceMeters": integer,
  "duration": string,
  "staticDuration": string,
  "travelAdvisory": {
    object (RouteTravelAdvisory)
  },
  "fallbackInfo": {
    object (FallbackInfo)
  },
  "localizedValues": {
    object (LocalizedValues)
  },
  "originIndex": integer,
  "destinationIndex": integer
}
Campi
status

object (Status)

Codice di stato di errore per questo elemento.

condition

enum (RouteMatrixElementCondition)

Indica se il percorso è stato trovato o meno. Indipendente dallo stato.

distanceMeters

integer

La distanza da percorrere del percorso, in metri.

duration

string (Duration format)

Il tempo necessario per percorrere il percorso. Se imposti routingPreference su TRAFFIC_UNAWARE, questo valore equivale a staticDuration. Se imposti routingPreference su TRAFFIC_AWARE o TRAFFIC_AWARE_OPTIMAL, questo valore viene calcolato tenendo conto delle condizioni del traffico.

Una durata in secondi con un massimo di nove cifre frazionarie, che termina con "s". Esempio: "3.5s".

staticDuration

string (Duration format)

La durata del percorso senza tenere conto delle condizioni del traffico.

Una durata in secondi con un massimo di nove cifre frazionarie, che termina con "s". Esempio: "3.5s".

travelAdvisory

object (RouteTravelAdvisory)

Informazioni aggiuntive sul percorso. Ad esempio: informazioni sulle limitazioni e sui pedaggi

fallbackInfo

object (FallbackInfo)

In alcuni casi, quando il server non è in grado di calcolare la route con le preferenze specificate per questa particolare coppia origine/destinazione, potrebbe utilizzare una modalità di calcolo diversa. Quando viene utilizzata la modalità di riserva, questo campo contiene informazioni dettagliate sulla risposta di riserva. In caso contrario, il campo non viene configurato.

localizedValues

object (LocalizedValues)

Rappresentazioni testuali delle proprietà dell'elemento RouteMatrixElement.

originIndex

integer

Indice in base zero dell'origine nella richiesta.

destinationIndex

integer

Indice in base zero della destinazione nella richiesta.

RouteMatrixOrigin

Una singola origine per ComputeRouteMatrixRequest

Rappresentazione JSON
{
  "waypoint": {
    object (Waypoint)
  },
  "routeModifiers": {
    object (RouteModifiers)
  }
}
Campi
waypoint

object (Waypoint)

Obbligatorio. Waypoint di partenza

routeModifiers

object (RouteModifiers)

Campo facoltativo. Modificatori per ogni percorso che prende questa come origine

RouteMatrixDestination

Una singola destinazione per ComputeRouteMatrixRequest

Rappresentazione JSON
{
  "waypoint": {
    object (Waypoint)
  }
}
Campi
waypoint

object (Waypoint)

Obbligatorio. Waypoint di destinazione

ExtraComputation

Calcoli aggiuntivi da eseguire durante il completamento della richiesta.

Enum
EXTRA_COMPUTATION_UNSPECIFIED Non utilizzato. Le richieste contenenti questo valore non andranno a buon fine.
TOLLS Informazioni sul pedaggio per gli elementi della matrice.

RouteMatrixElementCondition

La condizione della route che viene restituita.

Enum
ROUTE_MATRIX_ELEMENT_CONDITION_UNSPECIFIED Utilizzato solo quando il status dell'elemento non è OK.
ROUTE_EXISTS È stato trovato un percorso e sono state compilate le informazioni corrispondenti per l'elemento.
ROUTE_NOT_FOUND Nessun percorso trovato. I campi contenenti informazioni sul percorso, come distanceMeters o duration, non verranno compilati nell'elemento.

LocalizedValues

Rappresentazioni testuali di determinate proprietà.

Rappresentazione JSON
{
  "distance": {
    object (LocalizedText)
  },
  "duration": {
    object (LocalizedText)
  },
  "staticDuration": {
    object (LocalizedText)
  },
  "transitFare": {
    object (LocalizedText)
  }
}
Campi
distance

object (LocalizedText)

Distanza da percorrere rappresentata in formato di testo.

duration

object (LocalizedText)

Durata rappresentata in formato testo tenendo conto delle condizioni del traffico. Nota: se non sono state richieste informazioni sul traffico, questo valore corrisponde al valore di staticDuration.

staticDuration

object (LocalizedText)

Durata rappresentata in formato testo senza tenere conto delle condizioni del traffico.

transitFare

object (LocalizedText)

Tariffa di trasporto pubblico rappresentata in formato testo.