Choose fields to return

When you call a method to compute a route or compute a route matrix, you must specify 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.

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

Field masking is a good design practice to ensure that you do not request unnecessary data, which helps to avoid unnecessary processing time and billing charges.

For more information on 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.

Field paths are constructed in the following way:

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

  • For the compute routes methods, the field paths specify:

    • REST: The fields of the Route object in the response to return, prefixed by routes.. For example, routes.distanceMeters.
    • gRPC: The fields of the Route object in the response to return.

  • For the compute route matrix methods, the field paths specify the fields of the:

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

Specify a field path

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

REST call to computeRoutes

In the first example, you use a REST call to the computeRoutes method to calculate a route. In this example, you specify to return the Route.distanceMeters and the Route.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, specify to return the 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. Returning just the fields that you need:

  • Allows our server to save processing cycles, which allows us to return your results with a lower latency.

  • Ensures stable latency performance. We might add more response fields in the future, and those new fields might require extra computation time. If you select all fields, or if you select all fields at top level, you might experience performance degradation because any new field that we add will be automatically included in your response.

  • Results in a smaller response size, which translates into higher network throughput.

  • Ensures that you do not request unnecessary data, which helps to avoid unnecessary processing time and billing charges.