Request traffic information on polylines

The Routes API lets you request information about traffic conditions along a traffic-aware polyline. Traffic conditions are expressed in terms of speed categories (NORMAL, SLOW, TRAFFIC_JAM) applicable on a given interval of the response polyline. The intervals are defined by the indexes of their starting (inclusive) and ending (exclusive) polyline points.

For more on polylines, see:

Configure quality vs latency for information on configuring the quality of the ployline
Encoded Polyline Algorithm Format describes the algorithm for encoding a polyline.
Interactive Polyline Encoder Utility lets you create encoded polylines in a UI or decode polylines to display on a map. For example, use this utility to decode a polyline created by the code below.

Return a polyline

A polyline is represented by Polyline (REST) or Polyline (gRPC) object. You can return a polyline in the response at both the route and leg level.

Control which polyline to return by using the response field mask:

At the route level, return a polyline in the response by including routes.polyline in the response field mask.
At the leg level, return a polyline in the response for each leg of the route by including routes.legs.polyline.

Note: Each leg corresponds to the trip between two waypoints when via is false for the waypoint to indicate a stop on the route. For example, a route with no intermediate waypoints has only one leg. A route that includes an intermediate waypoint with a stop has two legs. A route that includes one intermediate waypoint with via set to true has one leg.

For example, to return a polyline for the entire route and for each leg:

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

Configure polyline type

The computeRoutes method (REST) and the ComputeRoutes method (gRPC) support the polylineEncoding request option for controlling the polyline type.

polylineEncoding specifies how to encode the polyline as either ENCODED_POLYLINE (default), meaning use the polyline encoding algorithm, or GEO_JSON_LINESTRING, meaning use the GeoJSON LineString format.

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": "2019-10-15T15:01:23.045123456Z",
  ...
}

Return traffic information

You can configure the response to include information about tolls and possible traffic zone restrictions:

At the route level, this information is included in a RouteTravelAdvisory (REST) or RouteTravelAdvisory (gRPC) object.
At the leg level, this information is included in a RouteLegTravelAdvisory (REST) or RouteLegTravelAdvisory (gRPC) object.

Both RouteTravelAdvisory and RouteLegTravelAdvisory includes an array field for traffic speed information detailing traffic density. Each object in the array is represented by a SpeedReadingInterval (REST) or SpeedReadingInterval (gRPC) object.

A SpeedReadingInterval object includes speed reading for a route interval. The entire array of objects covers the entire polyline of the route without overlap. The start point of a specified interval is the same as the end point of the preceding interval.

To configure the method to return traffic information with the polyline, use the the response field mask:

At the route level, return a all traffic information in the response by including routes.travelAdvisory in the response field mask. To return just the SpeedReadingInterval, specify routes.travelAdvisory.speedReadingIntervals
At the leg level, return traffic information in the response for each leg of the route by including routes.legs.travelAdvisory.speedReadingIntervals or routes.legs.steps.travelAdvisory.speedReadingIntervals.

When returning traffic information, you typically return both the polyline and traffic information in the response:

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

Example response for a traffic-aware polyline

In the response, route-level traffic is available in routes.travelAdvisory.speedReadingIntervals. Leg-level traffic is available under routes.legs.travelAdvisory.speedReadingIntervals.

Every interval is described by its startPolylinePointIndex, endPolylinePointIndex, and the corresponding speed category. Notice that the lack of start index within the interval corresponds with index 0 in accordance with the proto3 practices.

The startPolylinePointIndex and endPolylinePointIndex values are not always consecutive. For example:

{
  "startPolylinePointIndex": 2,
  "endPolylinePointIndex": 4,
  "speed": "NORMAL"
}

In this case, the traffic conditions were the same from index 2 to index 4.

Shown below is the complete response:

{
  "routes": [
    {
      "legs": {
        "polyline": {
          "encodedPolyline": "}boeF~zbjVAg@EmB`GWHlD"
        },
        "travelAdvisory": {
          "speedReadingIntervals": [
            {
              "endPolylinePointIndex": 1,
              "speed": "NORMAL"
            },
            {
              "startPolylinePointIndex": 1,
              "endPolylinePointIndex": 2,
              "speed": "SLOW"
            },
            {
              "startPolylinePointIndex": 2,
              "endPolylinePointIndex": 4,
              "speed": "NORMAL"
            }
          ] 
        }
      },
      "polyline": {
        "encodedPolyline": "}boeF~zbjVAg@EmB`GWHlD"
      },
      "travelAdvisory": {
        "speedReadingIntervals": [
          {
            "endPolylinePointIndex": 1,
            "speed": "NORMAL"
          },
          {
            "startPolylinePointIndex": 1,
            "endPolylinePointIndex": 2,
            "speed": "SLOW"
          },
          {
            "startPolylinePointIndex": 2,
            "endPolylinePointIndex": 4,
            "speed": "NORMAL"
          }
        ] 
      }
    }
  ]
}

Render Traffic Aware Polylines with Maps SDK

We recommend displaying traffic aware polylines on the map using the various features offered by Google Maps SDKs including custom coloring, strokes, and patterns along the polyline stretches. For more details about using polylines, see Polyline Features for Android and Polyline Features for iOS.

Example Polyline rendering

The users of Maps SDK have the opportunity of defining a customized mapping logic between the speed categories and the polyline rendering schemas. As an example, one might decide to display "NORMAL" speed as a thick blue line on the map while "SLOW" speed might be displayed as a thick orange line, and so on.

The following snippets add a thick blue polyline with geodesic segments from Melbourne to Perth. For more information, see Customizing appearances (for Android) and Customize the Polyline (for iOS).

Android

Java

Polyline line = map.addPolyline(new PolylineOptions()
    .add(new LatLng(-37.81319, 144.96298), new LatLng(-31.95285, 115.85734))
    .width(25)
    .color(Color.BLUE)
    .geodesic(true));

Kotlin

val line: Polyline = map.addPolyline(
  PolylineOptions()
    .add(LatLng(-37.81319, 144.96298), LatLng(-31.95285, 115.85734))
    .width(25f)
    .color(Color.BLUE)
    .geodesic(true)
)

iOS

Objective-C

GMSMutablePath *path = [GMSMutablePath path];
[path addLatitude:-37.81319 longitude:144.96298];
[path addLatitude:-31.95285 longitude:115.85734];
GMSPolyline *polyline = [GMSPolyline polylineWithPath:path];
polyline.strokeWidth = 10.f;
polyline.strokeColor = .blue;
polyline.geodesic = YES;
polyline.map = mapView;

Swift

let path = GMSMutablePath()
path.addLatitude(-37.81319, longitude: 144.96298)
path.addLatitude(-31.95285, longitude: 115.85734)
let polyline = GMSPolyline(path: path)
polyline.strokeWidth = 10.0
polyline.geodesic = true
polyline.map = mapView