Optimize your route waypoints

  • Waypoint Optimization, an experimental Routes Preferred feature, helps find the most efficient route by reordering intermediate waypoints for driving, motorcycling, cycling, or walking directions.

  • To use it, enable the feature through Support, set optimizeWaypointOrder to true in your ComputeRoutes request, and include optimizedIntermediateWaypointIndex in the field mask.

  • The response will provide the optimized waypoint order in the optimizedIntermediateWaypointIndex field and may take longer to process, requiring a higher timeout value (e.g., 10 seconds) for X-Server-Timeout.

  • Usage limitations include a maximum of 98 waypoints (latitude/longitude) or 25 waypoints (place IDs), all waypoints must be stopovers, and requests with 25+ waypoints have additional distance and travel mode restrictions.

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.

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.

Recommended content