Compute a route matrix

Use the Routes API to calculate the distance and duration of a route for multiple origins and destinations by calling the computeRouteMatrix method (REST) or the streaming ComputeRouteMatrix method (gRPC).

Given a list of origins and destinations, the method calculates the distance and duration of a route starting at each origin and ending at each destination.

Request limits

The Compute Route Matrix methods enforce the following request limits:

• The number of elements (number of origins × number of destinations) cannot exceed 625.

• If you specify TRAFFIC_AWARE_OPTIMAL, then the number of elements cannot exceed 100. For more on TRAFFIC_AWARE_OPTIMAL, see Configure quality vs latency.

• The maximum number of waypoints (origins + destinations) that you can specify by using a Place ID is 50.

Response errors

One feature of the Compute Route Matrix methods is that errors can be returned either for the entire response or for individual response elements. For example, the entire response contains an error if the request is malformed (for example, it has zero origins).

However, if an error applies to a subset of elements in the response (for example, a route cannot be computed for one combination of origin and destination), then only the elements affected by the error return an error code.

Stream results

The ComputeRouteMatrix gRPC method takes in a list of origins and destinations and returns a stream containing route information for each combination of origin and destination. Because the results are returned as a stream, you do not have to wait until all possible route combinations are calculated before you can start to process the results.

The elements returned by the stream are not guaranteed to be returned in any order. Therefore, each response element contains an origin_index and a destination_index. For the origins and destinations specified by the request, the route origin is equivalent to origins[origin_index] for a given element and the route destination is equivalent to destinations[destination_index]. These arrays are zero-indexed. It is important to store the origin and destination list orders.

Computing a Route Matrix Examples

Use the computeRouteMatrix method in an HTTP request to compute a route matrix.

HTTP example

The following example shows a computeRouteMatrix HTTP request. In this example you:

• Specify an array of two origin and two destination waypoints. The method calculates a route from each origin to each destination so the response contains four routes.

  In the array, the first element is at an index of 0, the second is index 1, and so on.

• Include a response field mask to specify which fields of the response (REST) or ComputeRoutesResponse (gRPC) to return. In this example, configure the request to return originIndex, destinationIndex, duration, distanceMeters, status, and condition for each route. For more information, see Choose fields to return.

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'

The response contains the four possible routes for the combination of all origin and destination waypoints.

Identify each route in the response by using the originIndex and destinationIndex response fields. For example, an originIndex of 1 in the response corresponds to a route calculated from the waypoint at index 1 of the origins array in the request.

[
    {
        "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"
    }
]

gRPC examples

For example gRPC requests, see the examples on Example gRPC request. The Java example on that page calls both the Compute Routes and Compute Route Matrix.