L'API Routes è attualmente in anteprima (pre-GA). I prodotti e le funzionalità pre-GA potrebbero avere supporto limitato e le modifiche ai prodotti e alle funzionalità pre-GA potrebbero non essere compatibili con altre versioni pre-GA. Le Offerte pre-GA sono coperte dai Termini di servizio specifici per Google Maps Platform. Per ulteriori informazioni, consulta le descrizioni delle fasi di lancio.

Calcola una matrice di route

Utilizza l'API Routes per calcolare la distanza e la durata di una route per più origini e destinazioni chiamando il metodo computeRouteMatrix (REST) o il metodo di streaming ComputeRouteMatrix (gRPC).

Dato un elenco di coppie di origini e destinazioni, i metodi calcolano la distanza e la durata di un percorso che inizia da ogni origine e termina su ogni destinazione.

Limiti per le richieste

I metodi della matrice di route Compute applicano i seguenti limiti di richiesta:

  • Il numero di elementi (numero di origini × numero di destinazioni) non può superare 625.

  • Se specifichi TRAFFIC_AWARE_OPTIMAL, il numero di elementi non può superare 100. Per scoprire di più su TRAFFIC_AWARE_OPTIMAL, consulta Confronto tra qualità e latenza.

  • Il numero massimo di tappe (origini + destinazioni) che puoi specificare utilizzando un ID luogo è 50.

Errori di risposta

Una funzionalità dei metodi della matrice di route Compute è che gli errori possono essere restituiti per l'intera risposta o per singoli elementi di risposta. Ad esempio, l'intera risposta contiene un errore se la richiesta non è nel formato corretto (ad esempio, non ha origini).

Tuttavia, se un errore si applica a un sottoinsieme di elementi della risposta (ad esempio, una route non può essere calcolata per una combinazione di origine e destinazione), solo gli elementi interessati dall'errore restituiscono un codice di errore.

Risultati dello stream

Il metodo gRPC ComputeRouteMatrix prende un elenco di origini e destinazioni e restituisce un flusso contenente informazioni sulle route per ogni combinazione di origine e destinazione. Poiché i risultati vengono restituiti come flusso, non devi attendere che vengano calcolate tutte le possibili combinazioni di route prima di poter iniziare a elaborare i risultati.

Per gli elementi restituiti dal flusso non è garantito che vengano restituiti in qualsiasi ordine. Pertanto, ogni elemento di risposta contiene un elemento origin_index e un elemento destination_index. Per le origini e le destinazioni specificate dalla richiesta, l'origine del percorso è uguale a origins[origin_index] per un determinato elemento e la destinazione del percorso è uguale a destinations[destination_index]. Questi array sono indicizzati zero. È importante memorizzare gli ordini dell'elenco di origine e di destinazione.

Esempio di calcolo di una matrice di route

Utilizza il metodo computeRouteMatrix in una richiesta HTTP per calcolare una matrice di route.

Esempio HTTP

L'esempio seguente mostra una richiesta HTTP computeRouteMatrix. In questo esempio:

  • Specifica un array di due punti di origine e di due destinazioni. Il metodo calcola una route da ogni origine a ogni destinazione in modo che la risposta contenga quattro route.

    Nella matrice, il primo elemento si trova a un indice pari a 0, il secondo all'indice 1 e così via.

  • Includi una maschera del campo di risposta per specificare quali campi della risposta (REST) o ComputeRoutesResponse (gRPC) restituire. In questo esempio, configura la richiesta per restituire originIndex, destinationIndex, duration, distanceMeters, status e condition per ogni route. Per maggiori informazioni, consulta Scegliere i campi da restituire.

curl -X POST -d '{
  "origins": [
    {
      "waypoint": {
        "location": {
          "latLng": {
            "latitude": 37.420761,
            "longitude": -122.081356
          }
        }
      },
      "routeModifiers": { "avoid_ferries": true}
    },
    {
      "waypoint": {
        "location": {
          "latLng": {
            "latitude": 37.403184,
            "longitude": -122.097371
          }
        }
      },
      "routeModifiers": { "avoid_ferries": true}
    }
  ],
  "destinations": [
    {
      "waypoint": {
        "location": {
          "latLng": {
            "latitude": 37.420999,
            "longitude": -122.086894
          }
        }
      }
    },
    {
      "waypoint": {
        "location": {
          "latLng": {
            "latitude": 37.383047,
            "longitude": -122.044651
          }
        }
      }
    }
  ],
  "travelMode": "DRIVE",
  "routingPreference": "TRAFFIC_AWARE"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: originIndex,destinationIndex,duration,distanceMeters,status,condition' \
'https://routes.googleapis.com/distanceMatrix/v2:computeRouteMatrix'

La risposta contiene i quattro percorsi possibili per la combinazione di tutti i Waypoint di origine e di destinazione.

Identifica ciascun percorso nella risposta utilizzando i campi originIndex e destinationIndex. Ad esempio, originIndex di 1 nella risposta corrisponde a una route calcolata dal punto di via all'indice 1 dell'array origins nella richiesta.

[
    {
        "originIndex": 0,
        "destinationIndex": 0,
        "status": {},
        "distanceMeters": 822,
        "duration": "160s",
        "condition": "ROUTE_EXISTS"
    },
    {
        "originIndex": 1,
        "destinationIndex": 0,
        "status": {},
        "distanceMeters": 2919,
        "duration": "361s",
        "condition": "ROUTE_EXISTS"
    },
    {
        "originIndex": 1,
        "destinationIndex": 1,
        "status": {},
        "distanceMeters": 5598,
        "duration": "402s",
        "condition": "ROUTE_EXISTS"
    },
    {
        "originIndex": 0,
        "destinationIndex": 1,
        "status": {},
        "distanceMeters": 7259,
        "duration": "712s",
        "condition": "ROUTE_EXISTS"
    }
]

Esempi di gRPC

Ad esempio, per le richieste gRPC, vedi gli esempi su richiesta gRPC di esempio. L'esempio Java su quella pagina chiama sia la route Compute sia la matrice di route Compute.