Waypoint optimization is a Routes Preferred feature that extends
ComputeRoutes
.
It optimizes the order of the intermediate waypoints in a traveler's route,
ensuring that they travel the most efficient route possible. The ComputeRoutes
implementation of waypoint optimization supports the following travel modes:
- Driving
- Motorized two-wheeling
- Cycling
- Walking
Why use waypoint optimization?
When building an app that guides users through a number of waypoints en route to a destination, it's important that the traveller traverses the waypoints in the optimal order. This ensures that the traveller arrives at every waypoint in the shortest amount of time.
How it works
By default, ComputeRoutes
calculates a route through its waypoints, in the order
in which they were originally provided. You can get ComputeRoutes
to optimize
the route by rearranging the intermediate waypoints into a more efficient order.
You'll receive a route with optimized waypoints if you set the
optimizeWaypointOrder
field in the request body to true
.
Note: The waypoint optimization calculation is primarily based on travel time, but the feature also takes other factors into consideration, such as distance and the number of turns.
Get reordered waypoints
To get a route with reordered waypoints, set the boolean field
optimizeWaypointOrder
to true
in the body of your request to
ComputeRoutes
. Also, include the field optimizedIntermediateWaypointIndex
in the field mask. The response body contains the optimized waypoint order in
the optimizedIntermediateWaypointIndex
fields.
Note: The optimizedIntermediateWaypointIndex
field returns zero-based
values.
Example request
The following example request supplies a route near the Stanford University campus. The route waypoints have been supplied sequentially in the request. The request contains an origin and a destination, with two intermediate waypoints.
POST /v1alpha:computeRoutes
Host: routespreferred.googleapis.com
Content-Type: application/json
X-Server-Timeout: 10
X-Goog-Api-Key: YOUR_API_KEY
X-Goog-FieldMask: routes.optimizedIntermediateWaypointIndex,routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline
{
"origin":{
"location":{
"latLng":{
"latitude": 37.418956,
"longitude": -122.160815
}
}
},
"intermediates": [
{
"location":{
"latLng":{
"latitude": 37.4176423,
"longitude":-122.1102246
}
}
},
{
"location":{
"latLng":{
"latitude": 37.407689,
"longitude": -122.1360597
}
}
}
],
"destination":{
"location":{
"latLng":{
"latitude": 37.4032137,
"longitude": -122.0349119
}
}
},
"travelMode": "DRIVE",
"optimizeWaypointOrder": true,
"routingPreference": "TRAFFIC_AWARE"}
Example response
You can find the reordered intermediate waypoint indexes in the
optimizedIntermediateWaypointIndex
fields within the routes object in the
response body. The encoded
polyline
is the same as in
Directions API and
ComputeRoutes.
routes {
distance_meters: 17647
duration {
seconds: 1866
}
polyline {
encoded_polyline: "wkkcFvorhVU{@Ec@C}CG}@Mm@[}@i@y@[[g@_@Tk@BSjCgGfF|D\\Pv@Lj@@XaCTeC\\aCTs@`ByD`@k@h@e@x@Yh@GtADhBF|@G`AWpAs@lAsAdA{A`BmDr@cBmUqQoS}OyGmFiBsAgEwD}CaCU_@Og@@e@Hy@nGkO~@sBr@cBlDqIlByEp@}AjIfGnBbBHLLd@^p@~ErDfNrKrA~@DIhEeBTQ~AqDlE{KjBgE|FnEh@aAi@`A}FoE~AmD`A}BcAm@mHwFwD}CkLwIsDqCgF_EG[GKnCsDrA_BrC_CnCoBpEkD`EyClCsBcBeBIAkGkH]k@eJmKQKsAuA_@g@wCoDGQmEmFmIqROKaDuHvBkBxAgANCRH^f@v@dBHDD?`AUiBqEhBpEaATMCQYm@wAY]SIOByAfAwBjB_ByDaAwBiCeIA[c@aBqEuNOm@IQbA{c@p@aZFmCTuBLg@Tc@BUAKxOeV~Vy_@nBoDv@_BvAcDzA_EdG{RdC{HtIsY|B{Hx@mDbAuFdBsMbKsv@TaBf@}AdF{Sn@_DJq@Lo@aE`@]GUQmAmAQk@@g@RK`Ce@d@UDEPc@f@cCrAyGJs@X{AbIem@bA{JD_AIaAMg@o@{A_Ad@y@NaCLCsCK_FGI"
}
optimizedIntermediateWaypointIndex: 1
optimizedIntermediateWaypointIndex: 0
}
In this example, notice that optimizing the waypoints reverses their original order.
Recommended practices
A request with optimized waypoints takes longer to process than a simple routing
request. As such, we recommend that you set a higher timeout on the method call
by setting a value for the X-Server-Timeout
request header to at least ten
seconds. If you continue to receive timeout errors, you can add another second
and then try again.
Usage limitations
To use waypoint optimization, you must follow these usage limitations and conditions:
You can specify up to the usage limit for intermediate waypoints on your route:
- Up to 98 waypoints using only latitude and longitude coordinates.
- Up to 25 waypoints if you specify any waypoints using place IDs.
All of your waypoints must be of the type stopover. None of your waypoints can be of the type via.
You must add
routes.optimizedIntermediateWaypointIndex
to the field mask.If your request has 25 or more intermediate waypoints, it must also adhere to the following conditions:
The accumulated straight-line distance between all of the waypoints must be less than 1,000 km. This distance includes both the origin and the destination.
The travel mode must be DRIVE.