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

TheRouteMatrix.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 notTRANSIT routes.
• If you specify aTRANSIT route, the number of items cannot exceed 100.
• If you specifyTRAFFIC_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 aComputeRouteMatrixRequest. 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 returndurationMillis,distanceMeters, andcondition for each route.

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

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

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 correspondingRouteMatrixItem in the 2D array. For example, theRouteMatrixItem describing the route calculated from the origin at index 1 and destination 0 in the request would be in the 2nd element of theRouteMatrix.rows array and the 1st element of theRouteMatrixRow.items array.

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

// Find the route for origin 'x' and destination 'y'.const{matrix}=awaitRouteMatrix.computeRouteMatrix(request);constmyRouteMatrixItem=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 theComputeRoutesMatrixRequest.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['*'].Caution: While you can use this wildcard field mask while in development to determine what fields you need, don't use it in production. Requesting all fields in production results in higher costs and longer response times. Your cost may also increase unexpectedly as more advanced features are added, since this field mask will automatically include them. Instead, request only the fields you need to minimize your costs and request response time.
2. Look at the hierarchy of the fields in theRouteMatrixItem 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 thisRouteMatrixItem:

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

fields: ['travelAdvisory.tollInfo']

fields: ['travelAdvisory.fuelConsumptionMicroliters']

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

fields: ['travelAdvisory']