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
.
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, specifyroutes.travelAdvisory.speedReadingIntervals
At the leg level, return traffic information in the response for each leg of the route by including
routes.legs.travelAdvisory.speedReadingIntervals
orroutes.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