Choose what information to return

When you call a method to compute a route or route matrix, you must specify what information you want by listing the fields to return in the response. There is no default list of returned fields. If you omit this list, the methods return an error.

You specify the field list by creating a response field mask. You then pass the response field mask to either method by using the URL parameter $fields or fields, or by using the HTTP or gRPC header X-Goog-FieldMask.

Using a field mask is a good design practice to ensure that you don't request unnecessary data, which in turn helps to avoid unnecessary processing time and billed charges.

For more information about URL parameters, see System Parameters.

Define a response field mask

The response field mask is a comma-separated list of paths, where each path specifies a unique field in the response message. The path starts from the top-level response message and uses a dot-separated path to the specified field.

Construct and specify a field path as follows:

  1. Find the fields that contain the information you need from the Routes API. For details, see Field References.
  2. Determine the paths for the fields you need and construct the field masks for them: For details, see Determine what field mask you want to use.
  3. Combine the field masks for all of the fields you need, separating the field masks with commas. For example, to request the distanceMeters for the route leg, plus the duration for each route leg step, enter them both, separated by a comma, with no spaces:

  4. Send the field mask with your API request. For example, in a cURL request, you would specify the field mask with -H and X-Goog-FieldMask:

    -H X-Goog-FieldMask: routes.legs.distanceMeters,routes.legs.steps.duration
For examples and more details, see the following sections.

Field References

To see the fields that you can request in a response through field masks, refer to the Routes API references linked in the following list. Specify fields in camel case as shown in the reference. For example, routePreference.

These references include the fields that are available; however, you need to refer to the hierarchy of the fields to determine the full field mask path. For details on getting the hierarchy of the fields, see Determine what field mask you want to use.

  • Compute route field mask
    • REST: Specifies the fields of the Route object in the response to return, prefixed by routes., for example, routes.distanceMeters.
    • gRPC: Specifies the fields of the Route object in the response to return.
  • Compute route matrix field masks

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 response for the fields you want.
  3. Construct your field masks using the hierarchy of the fields shown in the previous step, using this format:


For example, for this partial response from a route:

"routes": [
        "legs": [
            {  "steps": [
                    {"distanceMeters": 119},
                    {"distanceMeters": 41}  ]
        "distanceMeters": 160

If you want to return only the distanceMeters field for the route leg; that is, the last distanceMeters in the preceding sample, your field mask is as follows:


If you want instead want to return the distanceMeters field for each step of the route leg; that is, the distanceMeters under steps in the preceding sample, your field mask is as follows:


If you want to return both, with the result above, your field mask is as follows:


Example field mask paths

This section contains more examples on how to specify a field path as part of a response field mask in REST and gRPC calls.

REST call to computeRoutes

In the first example, you use a REST call to the computeRoutes method to calculate a route. In this example, in the header, you specify field masks to return the route distanceMeters and duration fields in the response. Remember to prefix the field name by routes.

X-Goog-FieldMask: routes.distanceMeters,routes.duration

REST call to computeRouteMatrix

For the REST computeRouteMatrix method used to compute a route matrix, in the header, specify to return originIndex, destinationIndex, and duration for each combination of origin and destination:

X-Goog-FieldMask: originIndex,destinationIndex,duration

gRPC call

For gRPC, set a variable containing the response field mask. You can then pass that variable to the request.

const (
  fieldMask = "routes.distanceMeters,routes.duration,routes.polyline.encodedPolyline"

Field path considerations

Include only the fields that you require in the response to return just the fields that you need:

  • Decreases processing times, so your results are returned with a lower latency.
  • Ensures stable latency performance. If you select all fields, or if you select all fields at the top level, you might experience performance degradation when new fields are added and then are automatically included in your response.
  • Results in a smaller response size, which translates into higher network throughput.
  • Ensures that you don't request unnecessary data, which helps to avoid unnecessary processing time and billed charges.

For more details on constructing a field mask, see the field_mask.proto.

Request a route token

To request that the Routes API returns route tokens for generated routes, follow these steps:

  1. Set the following parameters required to return a route token:
    • Set travelMode to DRIVE.
    • Set routingPreference to TRAFFIC_AWARE or TRAFFIC_AWARE_OPTIMAL.
  2. Check that none of your route waypoints are via waypoints.
  3. Specify the routes.routeToken field mask to return a route token:
    X-Goog-FieldMask: routes.routeToken

You can use the route token for your planned route in the Navigation SDK. For more details, see Plan a route (Android) or Plan a route (iOS).

Route token example

Here's an example cURL request body for a single origin, single-destination route, using field masks to request a route token, along with the route duration, distance, and route polyline:

curl -X POST -d
    "location": {
            "latitude":  -37.8167,
            "longitude": 144.9619
    "location": {
            "longitude": 144.9663
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H X-Goog-FieldMask: routes.routeToken,routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline

For more details, see the Compute Routes API reference.