Choose what information to return

When you call a method to compute a route or compute a route matrix, you must specify what information you want by specifying which fields you want returned 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.

Field masking is a good design practice to ensure that you don't request unnecessary data, which 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 a field path as follows:

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

Note: Don't use spaces anywhere in the list of field paths.

• 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
  • REST: Specifies the fields of the Response body to return.
  • gRPC: Specifies the fields of the RouteMatrixElement object in the response to return.

For more information about how to construct field masks, see the field_mask.proto.

Determine what field masks to use

Here's how you can determine which field masks you want to use:

1. Request all fields using a field mask of *.
   Caution: While this wildcard field mask is okay to use in development, don't use the wildcard (*) response field mask in production. The cost may be higher than expected as more advanced features are requested through this field mask, and it increases response latency. Make sure you are requesting only the fields you need to minimize your costs and request response time.
2. Look at the hierarchy of the fields in the response, and determine what fields you want.
3. Build your field mask using the field hierarchy.

For example, for this partial response from a transit route:

 "routes": [
  {
    "legs": [
    {
      "distanceMeters": 12886,
    }
...
]}]

If you want to return only the distanceMeters field, your field mask is:

routes.legs.distanceMeters

Another example: To return everything under legs in the response, your field mask is:

routes.legs

Specify a field path

This section contains examples on how to specify a field path as part of a response field mask.

Caution: A special case field mask is a wildcard "*", which selects all fields. However, while this wildcard field mask is okay to use in development, don't use it in production. The cost may be higher than expected as advanced features are requested through this field mask, and it increases response latency. Make sure you are requesting only the fields you need to minimize your costs and request response time.

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 the Route.duration fields in the response. Remember to prefix the field name by routes.

-H 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:

-H 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. Returning just the fields that you need:

• Decreases processing times, so your results are returned with a lower latency.
• Ensures stable latency performance if the API adds more response fields in the future, and those new fields require extra computation time. If you select all fields, or if you select all fields at the top level, you might experience performance degradation when all new fields 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.

Note: When a response message is parsed, and a field in the response message contains its default value, the field may be omitted from the response even if you specified it in the response field mask. For more information, see the Language Guide (proto3). For example, when you compute a route matrix, the distanceMeters field of the response can contain a value of 0, its default value. Because 0 is the default value of distanceMeters, it is omitted from the response.

Request a route token

To request that the Routes API returns route tokens for generated routes, follow the requirements for returning a route token, and then use the routes.route_token field mask to request the token:

1. Set travel_mode to DRIVING.
2. Set routing_preference to TRAFFIC_AWARE or TRAFFIC_AWARE_OPTIMAL.
3. Check that none of your route waypoints are via waypoints.
4. Specify the route token field mask:

   -H X-Goog-FieldMask: routes.route_token

Note: Due to dynamic road conditions, routes generated with a given token may differ from the planned route. To minimize the differences, use the token within minutes of token generation.

You can use 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 request body for a single origin, single-destination route, and using field masks to request a route token, along with the route duration, distance, and route polyline:

terminal
curl -X POST -d
{"origin":{
    "location": {
        "latLng":{
            "latitude":  -37.8167,
            "longitude": 144.9619
        }
    }
},
"destination":{
    "location": {
        "latLng":{
            "latitude":-37.8155,
            "longitude": 144.9663
        }
    }
},
"routingPreference":"TRAFFIC_AWARE",
"travelMode":"DRIVE"
}
-H X-Goog-FieldMask: routes.route_token,routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline
'https://routes.googleapis.com/directions/v2:computeRoutes'

For more details, see the Compute Routes API reference.