<br />

> [!WARNING]
> This product or feature is in Preview (pre-GA). Pre-GA products and features might have limited support, and changes to pre-GA products and features might not be compatible with other pre-GA versions. Pre-GA Offerings are covered by the [Google
> Maps Platform Service Specific Terms](https://cloud.google.com/maps-platform/terms/maps-service-terms). For more information, see the [launch stage
> descriptions](https://developers.google.com/maps/launch-stages).

<br />

You can calculate the distance and duration of a route for multiple
origins and destinations by using the `ComputeRouteMatrix` method
of the Routes Preferred API. `ComputeRouteMatrix` supports
both streaming gRPC calls and REST HTTP calls.

Given a list of origin and destination pairs, `ComputeRouteMatrix`
calculates the distance and duration of a route starting at each origin
and ending at each destination. Each element of the stream corresponds
to the information for a single route.

The `ComputeRouteMatrix` method has several advantages over
Distance Matrix API (Legacy):

- Streaming allows elements to be returned before the entire matrix has been calculated, lowering latency.
- `ComputeRouteMatrix` has fine-grained options for traffic calculation, letting you make quality-latency trade off decisions.
- Requests are run at a higher priority within Google's infrastructure, which results in higher availability.
- You can specify heading (direction of travel) and side-of-road information for waypoints.
- You can request for toll information to be returned, along with route distance and ETA.

## Enable the ComputeRouteMatrix method

Before you can use the `ComputeRouteMatrix` method in your code, you must
enable it. For more information on enabling Routes Preferred API
methods, see [Getting Started](https://developers.google.com/maps/documentation/routes_preferred/get_started.md.txt).

> [!IMPORTANT]
> **Important:** Check your quota limits for Routes Preferred API methods. If you need to increase your quota limits, contact support by filing a case on the [Google Maps Platform support page](https://console.cloud.google.com/google/maps-apis/support) in the Google Cloud Console, or by calling the [Google Cloud Support Hotline](https://developers.google.com/maps/documentation/routes_preferred/support.md.txt#support_hotline).

## Use the ComputeRouteMatrix method

The `ComputeRouteMatrix` method is available through the Routes Preferred
*v1* endpoint.

See the following documentation for more detailed information:

gRPC:
<https://developers.google.com/maps/documentation/routes_preferred/reference/rpc/google.maps.routes.v1>

REST:
<https://developers.google.com/maps/documentation/routes_preferred/reference/rest/v1/TopLevel/computeRouteMatrix>

The following generic steps describe how to use gRPC to call
the `ComputeRouteMatrix` method:

1. Check out the necessary protobuffers from the googleapis repository:

   <https://github.com/googleapis/googleapis/tree/master/google/maps/routes>

   Note that some build systems, such as Go, may automatically do this for you.
2. Using your preferred language and set of build tools, generate the relevant
   protobuffer code.

3. Generate your request. Two required pieces of metadata must be sent
   with the request:

   - *X-Goog-Api-Key* must be set to your API key.
   - *X-Goog-Fieldmask* must be set to a comma separated list of the fields
     you require from the response. For example,
     *X-Goog-FieldMask: originIndex,destinationIndex,duration,distanceMeters,status*.
     You can use the wildcard character (\*) to denote all fields, but that is
     discouraged. Use the wildcard character to test and understand the
     API response, but explicitly list the fields you want in the field mask
     in your production code.

     For more information on how to construct the field mask string, see
     <https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/field_mask.proto>.
     Note that disabling fields you do not need can reduce latency since
     those fields may require further computation. Your latency will stay
     stable if you specify the fields you need and new fields that require
     more computation are added later.
4. Send your request to `routespreferred.googleapis.com:443`.You must use
   the TLS protocol.

For examples of using the `ComputeRouteMatrix` method, see
[Computing a Route Matrix (Beta) Examples](https://developers.google.com/maps/documentation/routes_preferred/compute_matrix_examples.md.txt).

One distinguishing feature of the `ComputeRouteMatrix` method is that
error codes can be returned either for the entire stream or for individual
elements. For example, the stream connection returns an error if the request
is malformed (for example, it has zero origins). However, if an error applies
to just a few elements of the stream (for example, setting an invalid Place ID
for an origin), then only the elements affected by the error contain error codes.

The elements returned by the stream are not guaranteed to be returned
in any order. Because of this, each 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 is equivalent
to `destinations[destination_index]`. These arrays are zero-indexed. It
is important to store the origin and destination list orders.

## Calculating toll fees

For information on calculating toll fees, see
[Calculate toll fees](https://developers.google.com/maps/documentation/routes_preferred/calculate_toll_fees.md.txt).

For examples of calculating toll fees, see
[Computing a Route Matrix Examples](https://developers.google.com/maps/documentation/routes_preferred/compute_matrix_examples.md.txt#toll-fee-examples).