Routes Preferred API is currently available only to select customers. Contact sales to learn more.

Optimize your route waypoints

Stay organized with collections Save and categorize content based on your preferences.

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.

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.

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 /v1: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

  • Your route may not contain more than 98 intermediate waypoints.

  • Ensure that you add routes.optimizedIntermediateWaypointIndex to the field mask.

  • You may not specify waypoints of the type via. That is, all provided waypoints must be stops.

  • Requests that contain between 25 - 98 intermediate waypoints must 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.

    • You must specify the position of the waypoints using their latitude and longitude.

    • The travel mode must be DRIVE.