<br />

> [!WARNING]
> This product or feature is Experimental (pre-GA). Pre-GA products and features might have limited support, and changes to pre-GA products and features might not be compatible with other pre-GA versions. Pre-GA Offerings are covered by the [Google
> Maps Platform Service Specific Terms](https://cloud.google.com/maps-platform/terms/maps-service-terms). For more information, see the [launch stage descriptions](https://developers.google.com/maps/launch-stages.md.txt).

<br />

> [!WARNING]
> This feature is not enabled by default. If you want to use it, contact [Support](https://developers.google.com/maps/documentation/routes_preferred/support.md.txt) with the following information: Estimated ComputeRoutes QPM (queries-per-minute) using waypoint optimization, typical number of waypoints per request, and maximum number of waypoints per request.

Waypoint optimization is a Routes Preferred feature that extends
[`ComputeRoutes`](https://developers.google.com/maps/documentation/routes_preferred/reference/rest/v1/TopLevel/computeRoutes.md.txt).
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](https://developers.google.com/maps/documentation/routes_preferred/reference/rest/Shared.Types/Route.md.txt#polyline)
is the same as in
[Directions API](https://developers.google.com/maps/documentation/directions/overview.md.txt) and
[ComputeRoutes](https://developers.google.com/maps/documentation/routes_preferred/reference/rest/v1/TopLevel/computeRoutes.md.txt).

    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.

## Recommended content

- [Choose Fields to Return](https://developers.google.com/maps/documentation/routes_preferred/choose_fields.md.txt)
- [Use Intermediate Waypoints](https://developers.google.com/maps/documentation/routes_preferred/intermed_waypoints.md.txt)