Get a route matrix

A route matrix is a two-dimensional array of route information, where the rows correspond to the origins and the columns correspond to the destinations. Given a list of origins and destinations, the Route Matrix class calculates the distance and duration of a route starting at each origin and ending at each destination. Use the Route Matrix class to calculate the distance and duration of a route for multiple origins and destinations.

Request limits

The RouteMatrix.computeRouteMatrix() method enforces the following request limits for waypoints using address or Place instances, and for items. Items are the routes between each origin and destination in a route matrix, so the number of items is the number of origins times the number of destinations. For example, if you have 10 origins and 10 destinations, you have 100 items:

• The number of items cannot exceed 625 for routes that are not TRANSIT routes.
• If you specify a TRANSIT route, the number of items cannot exceed 100.
• If you specify TRAFFIC_AWARE_OPTIMAL, the number of items cannot exceed 100.
• If you specify origins or destinations using addresses or Place instances, you specify up to 50 total this way.

Example route matrix request

The following example shows a ComputeRouteMatrixRequest. This example does the following:

• Shows specifying 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 forth.
• Specify the fields to return. In this example, configure the request to return durationMillis, distanceMeters, and condition for each route.

const request = {
  origins: [origin1, origin2],
  destinations: [destinationA, destinationB],
  travelMode: google.maps.TravelMode.DRIVING,
  units: google.maps.UnitSystem.METRIC,
  fields: ['durationMillis', 'distanceMeters', 'condition'], 
};
    

The response contains the four possible routes for the combination of all origin and destination waypoints, as shown in the following example:

"matrix": {
  "rows": [
    {
      "items": [
        {
          "condition": "ROUTE_EXISTS",
          "distanceMeters": 202587,
          "durationMillis": 10040000
        },
        {
          "condition": "ROUTE_EXISTS",
          "distanceMeters": 252734,
          "durationMillis": 12240000
        }
      ]
    },
    {
      "items": [
        {
          "condition": "ROUTE_EXISTS",
          "distanceMeters": 166135,
          "durationMillis": 6596000
        },
        {
          "condition": "ROUTE_EXISTS",
          "distanceMeters": 216282,
          "durationMillis": 8797000
        }
      ]
    }
  ]
}
    

Identify each route in the result by using the origin and destination index to find the corresponding RouteMatrixItem in the 2D array. For example, the RouteMatrixItem describing the route calculated from the origin at index 1 and destination 0 in the request would be in the 2nd element of the RouteMatrix.rows array and the 1st element of the RouteMatrixRow.items array.

The following code snippet shows how to identify the RouteMatrixItem to find the route for a specific origin and destination:

// Find the route for origin 'x' and destination 'y'.
const {matrix} = await RouteMatrix.computeRouteMatrix(request);
const myRouteMatrixItem = matrix.rows[x].items[y];
    

Choose fields to return

When you request a route matrix, you must use a field mask to specify what information the response should return.

Using a field mask also ensures that you don't request unnecessary data, which in turn helps with response latency and avoids returning information your system doesn't need.

Specify the list of fields you need by setting the ComputeRoutesMatrixRequest.fields property, as shown in the following snippet:

fields: ['durationMillis', 'distanceMeters', 'condition'],
    

Determine what field masks to use

Here's how you can determine which fields you want to use, and construct the field masks for them:

1. Request all fields using a field mask of ['*'].
2. Look at the hierarchy of the fields in the RouteMatrixItem class for the fields you want.

3. Construct your field masks using the hierarchy of the fields shown in the previous step, using this format:

   topLevelField[.secondLevelField][.thirdLevelField][...]

For example, for this RouteMatrixItem:

  "travelAdvisory": {
    "fuelConsumptionMicroliters": 0,
    "tollInfo": {
      "estimatedPrices": [
        {
          "currencyCode": "USD",
          "units": 4,
          "nanos": 400000000
        }
      ]
    }
  },
    

If you want to return only the tollInfo field for the RouteMatrixItem, your field mask is as follows:

fields: ['travelAdvisory.tollInfo']

If you instead want to request the estimated fuel consumption, your field mask is as follows:

fields: ['travelAdvisory.fuelConsumptionMicroliters']

If you want to request both, your field mask is as follows:

fields: ['travelAdvisory.fuelConsumptionMicroliters', 'travelAdvisory.tollInfo']

And if you want to request the complete set of travel advisories, your field mask is as follows:

fields: ['travelAdvisory']