Specify the traffic model type to use

European Economic Area (EEA) developers

Traffic models use specific algorithms and factors to predict how traffic conditions impact total travel time for a given route. The Routes API offers different traffic model types to prioritize different factors used in calculating duration in traffic. You can specify the traffic model type you'd like your routes to use when calculating the duration for your routes or route matrix. When you set the traffic model type, the value returned in the duration field varies depending on the traffic model you choose.

Both the Routes API Compute Routes and Compute Route Matrix methods support traffic model types.

By default, both methods use the BEST_GUESS traffic model type.

To specify a traffic type

  1. Set your origin and destination.

  2. If your departure time is in the future, include the time using the departure_time parameter. If you don't specify a departure time, it defaults to now.

  3. Set the routingPreference parameter to TRAFFIC_AWARE_OPTIMAL. Setting the routingPreference to TRAFFIC_UNAWARE or TRAFFIC_AWARE is incompatible with the trafficModel parameter.

  4. Select the traffic model to use with the trafficModel parameter and one of the following types:

    • BEST_GUESS (default) to request that the returned duration_in_traffic is the best estimate of travel time given what is known about both historical traffic conditions and live traffic. Live traffic becomes more important the closer the departure_time is to now. Using the default type of BEST_GUESS gives the most useful predictions for the vast majority of use cases.

    • PESSIMISTIC to request that the returned duration_in_traffic models the time based on the historical traffic conditions on bad traffic days. This type gives an estimated duration that is most likely longer than the actual travel time on most days. Occasional days with particularly bad conditions may still exceed this estimate.

    • OPTIMISTIC to request that the returned duration_in_traffic models the time based on the historical traffic conditions on good traffic days. This type gives an estimated duration that is most likely shorter than the actual travel time on most days. Occasional days with particularly good conditions may still be faster than this estimate.

    For example: 

    "trafficModel": "OPTIMISTIC"

  5. Specify the routes.duration field in the field mask.

    REST

    -H X-Goog-FieldMask: routes.duration

    RPC

    const (fieldMask = "routes.duration")

When the Routes API estimates time in traffic, it uses the traffic model type you've requested.

Example: Traffic model request

For example, this request specifies that the duration be estimated using the OPTIMISTIC traffic model type at a specific departure time:

curl -X POST -H 'content-type: application/json' -d ' {
"origin": {
  "address": "Kyoto, Japan"
  },
"destination": {
  "placeId": "ChIJrYtcv-urAWAR3XzWvXv8n_s"
  },
"travelMode": "DRIVE",
"routingPreference": "TRAFFIC_AWARE_OPTIMAL",
"trafficModel": "OPTIMISTIC"
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: routes.duration' \
'https://routes.googleapis.com/directions/v2:computeRoutes'

This request returns the estimated duration using the OPTIMISTIC traffic model type for the trip:

"duration": "1238s"

If you change the traffic model type to PESSIMISTIC, the returned duration is longer:

"duration": "2436s"