Specify how and if to include traffic data

The traffic preferences you select balance the accuracy of the route details with request performance. When you make a request, you want to weigh whether it is better to return the most accurate results possible, or to return results as quickly as possible. The Routes API provides options that let you control the quality of the response data vs the latency of the response.

Caution: Requests using TRAFFIC_AWARE and TRAFFIC_AWARE_OPTIMAL are billed at a higher rate. Learn more about billing.

Set the level of traffic data

The Routes API provides RoutingPreference (REST) and RoutingPreference (gRPC) that let you specify routing preferences for calculating routes. These preferences differ in the extent that they factor traffic conditions into the route calculation. Each routing preference produces results that differ to a degree in regard to route quality, estimated ETA, and response latency.

Traffic conditions characterize the rate of traffic flow. For example:

• When there is no congestion, traffic conditions are considered normal, and traffic flows at the regular unimpeded speed.
• Approaching rush-hour, traffic density increases, which causes traffic to slow down, producing light to moderate traffic conditions.
• In bumper-to-bumper traffic, the flow-rate grinds to a halt, producing heavy traffic conditions.

Traffic unaware

When you set the TRAFFIC_UNAWARE routing preference, routes are calculated without accounting for current traffic conditions. This routing preference provides the lowest response latency (responses are returned the fastest).

TRAFFIC_UNAWARE is the default setting.

Note: If you specify TRAFFIC_UNAWARE, the choice of route and duration are based on road network and average time-independent traffic conditions. Results for a given request may vary over time due to changes in the road network, updated average traffic conditions, and the distributed nature of the service. Results may also vary between nearly-equivalent routes at any time or frequency.

In the response:

• The ETA is contained in the duration response property.

• The duration and staticDuration response properties contain the same value.

Use this routing preference when you want responses returned the quickest, and approximate routing details are good enough.

Note: This setting is equivalent to when current traffic is not used in the Directions API and Distance Matrix API.

Traffic aware

When you set the TRAFFIC_AWARE routing preference, routes are calculated accounting for current traffic conditions. As a result, the route and route details more accurately reflect real-world conditions. Because this increase in data quality comes at the expense of response latency, performance optimizations are applied to reduce much of the latency.

In the response:

• The ETA taking real-time traffic into consideration is contained in the duration response property.

• The staticDuration response property contains the duration of traveling through the route without taking traffic conditions into consideration.

Use this routing preference when you want more accurate routing details than TRAFFIC_UNAWARE, and yet you don't mind if responses are returned with a moderate increase in latency.

Note: This setting is new for the Routes API and has no equivalent in the Directions API and Distance Matrix API.

Traffic aware optimal

When you set the TRAFFIC_AWARE_OPTIMAL routing preference, routes are calculated accounting for current traffic conditions, but no performance optimizations are applied. In this mode, the server performs a more exhaustive search of the road network to find the optimal route.

The TRAFFIC_AWARE_OPTIMAL routing preference is equivalent to the mode used by maps.google.com and by the Google Maps mobile app.

When using this option with Compute Route Matrix, the number of elements in a request (number of origins × number of destinations) cannot exceed 100. For more on Compute Route Matrix limits, see Compute a route matrix.

In the response:

• The ETA taking real-time traffic into consideration is contained in the duration response property.

• The staticDuration response property contains the duration of traveling through the route without taking traffic conditions into consideration.

This routing preference provides the highest response latency (that is, responses return with the longest delay). Use this routing preference when you want results of the highest quality, without regard to how long responses take.

Note: This option is equivalent to specifying departure_time in the Directions API and Distance Matrix API.

Effect of setting departure time

You optionally use the departureTime property to set the departure time for a trip. If you don't set the departureTime property, it defaults to the time that you make the request.

• For TRAFFIC_UNAWARE, you cannot set departureTime because the choice of route and duration are based on road network and average time-independent traffic conditions.

• For TRAFFIC_AWARE and TRAFFIC_AWARE_OPTIMAL, which take live traffic conditions into consideration, live traffic becomes more important the closer the departureTime is to now. The farther you set the departure time into the future, the more consideration is given to historical traffic conditions.

Example setting routing preference

The following JSON code demonstrates how to set the routing preference in a request message entity body.

{
  "origin":{
    "location":{
      "latLng":{
        "latitude":37.419734,
        "longitude":-122.0827784
      }
    }
  },
  "destination":{
    "location":{
      "latLng":{
        "latitude":37.417670,
        "longitude":-122.079595
      }
    }
  },
  "travelMode":"DRIVE",
  "routingPreference":"TRAFFIC_AWARE_OPTIMAL"
}

Configure polyline quality

The Routes API lets you request information about traffic conditions along a traffic-aware polyline. See Request polylines for more information.

The quality of a polyline can be described in the following terms:

• The number of points that make up the polyline

  The more points there are, the smoother the polyline (especially in curves).

• The floating-point precision of the points

  Points are specified as latitude and longitude values, which are represented in single-precision floating-point format. This works well for small values (which can be represented precisely), but precision decreases as values increase because of floating-point rounding errors.

The computeRoutes method (REST) and the ComputeRoutes method (gRPC) supports the polylineQuality request option for controlling polyline quality.

Example setting polyline quality

polylineQuality specifies the quality of the polyline as HIGH_QUALITY or OVERVIEW (default). With OVERVIEW, the polyline is composed using a small number of points and has a lower request latency than HIGH_QUALITY.

For example, in the request body:

{
  "origin":{
    "location":{
      "latLng":{
        "latitude": 37.419734,
        "longitude": -122.0827784
      }
    }
  },
  "destination":{
    "location":{
      "latLng":{
        "latitude": 37.417670,
        "longitude": -122.079595
      }
    }
  },
  "travelMode": "DRIVE",
  "routingPreference": "TRAFFIC_AWARE",
  "polylineQuality": "HIGH_QUALITY",
  "polylineEncoding": "ENCODED_POLYLINE", 
  "departureTime": "2023-10-15T15:01:23.045123456Z",
  ...
}