Choose Fields to Return

  • When calling the ComputeRoutes() method, specify desired response fields using a field mask with the $fields URL parameter, fields URL parameter, or X-Goog-FieldMask HTTP/gRPC header.

  • Construct field masks as comma-separated lists of dot-separated field paths representing the message hierarchy starting from the top-level response.

  • For production, avoid using wildcard field masks or selecting all top-level fields to improve performance, ensure stable latency, and reduce response size.

  • Selecting specific fields instead of all fields minimizes server processing, safeguards against potential performance degradation from future response field additions, and enhances network throughput.

When you call the ComputeRoutes() method, you must specify which fields you want returned in the response. You do it by using a response field mask, which you provide with the URL parameter $fields or fields, or by using the HTTP/gRPC header X-Goog-FieldMask. For more information, see System Parameters.

Field mask

The field mask value is a comma-separated list of field paths. Each field path is a dot-separated list of field names that represent the message hierarchy. A field name is either the JSON object key, or the protobuf field tag name. The field path starts from the top level response message type, and is optionally followed by one or more dots, and then the next level of field name. In general, field paths are constructed in the following way:

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

A special case field mask is a wildcard “*”, which selects all root-level fields.

Examples

The following example demonstrates how to set field masks for the ComputeRoutes() method.

Example 1

Field mask of all available fields (for manual inspection).

X-Goog-FieldMask: *

Example 2

Field mask of Route-level duration, distance, and polyline (an example production setup).

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

We discourage the use of the wildcard (*) response field mask, or specifying the field mask at the top level (routes) in production. Selecting 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.

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