---
title: "POST /v2/optimize-waypoints"
method: POST
path: "/v2/optimize-waypoints"
---

# POST /v2/optimize-waypoints

`POST /v2/optimize-waypoints`

`OptimizeWaypoints` calculates the optimal order to travel between a set of waypoints to minimize either the travel time or the distance travelled during the journey, based on road network restrictions and the traffic pattern data.

For more information, see [Optimize waypoints](https://docs.aws.amazon.com/location/latest/developerguide/actions-optimize-waypoints.html) in the _Amazon Location Service Developer Guide_.

## Query parameters

- `key` string, password

## Request body

- object
  - `Avoid` object — Specifies options for areas to avoid. This is a best-effort avoidance setting, meaning the router will try to honor the avoidance preferences but may still include restricted areas if no feasible alternative route exists. If avoidance options are not followed, the response will indicate that the avoidance criteria were violated.
    - `Areas` WaypointOptimizationAvoidanceArea[] — Areas to be avoided.
      - `Geometry` object, required — Geometry of the area to be avoided.
        - `BoundingBox` Double[] — Geometry defined as a bounding box. The first pair represents the X and Y coordinates (longitude and latitude,) of the southwest corner of the bounding box; the second pair represents the X and Y coordinates (longitude and latitude) of the northeast corner.
    - `CarShuttleTrains` boolean — Avoidance options for cars-shuttles-trains.
    - `ControlledAccessHighways` boolean — Avoid controlled access highways while calculating the route.
    - `DirtRoads` boolean — Avoid dirt roads while calculating the route.
    - `Ferries` boolean — Avoidance options for ferries.
    - `TollRoads` boolean — Avoids roads where the specified toll transponders are the only mode of payment.
    - `Tunnels` boolean — Avoid tunnels while calculating the route.
    - `UTurns` boolean — Avoid U-turns for calculation on highways and motorways.
  - `Clustering` object — Options for WaypointOptimizationClustering.
    - `Algorithm` 'DrivingDistance' | 'TopologySegment', password — The algorithm to be used. <code>DrivingDistance</code> assigns all the waypoints that are within driving distance of each other into a single cluster. <code>TopologySegment</code> assigns all the waypoints that are within the same topology segment into a single cluster. A Topology segment is a linear stretch of road between two junctions.
    - `DrivingDistanceOptions` object — Driving distance options to be used when the clustering algorithm is DrivingDistance.
      - `DrivingDistance` integer, required — DrivingDistance assigns all the waypoints that are within driving distance of each other into a single cluster.
  - `DepartureTime` string, password — <p>Departure time from the waypoint.</p> <p>Time format:<code>YYYY-MM-DDThh:mm:ss.sssZ | YYYY-MM-DDThh:mm:ss.sss+hh:mm</code> </p> <p>Examples:</p> <p> <code>2020-04-22T17:57:24Z</code> </p> <p> <code>2020-04-22T17:57:24+02:00</code> </p>
  - `Destination` Double[] — The final position for the route in the World Geodetic System (WGS 84) format: <code>[longitude, latitude]</code>.
  - `DestinationOptions` object — Destination related options.
    - `AccessHours` object — Access hours corresponding to when a waypoint can be visited.
      - `From` object, required — Contains the ID of the starting waypoint in this connection.
        - `DayOfWeek` 'Monday' | 'Tuesday' | 'Wednesday' | 'Thursday' | 'Friday' | 'Saturday' | 'Sunday', password, required — Day of the week.
        - `TimeOfDay` string, password, required — Time of the day.
      - `To` object, required — Contains the ID of the ending waypoint in this connection.
        - `DayOfWeek` 'Monday' | 'Tuesday' | 'Wednesday' | 'Thursday' | 'Friday' | 'Saturday' | 'Sunday', password, required — Day of the week.
        - `TimeOfDay` string, password, required — Time of the day.
    - `AppointmentTime` string, password — Appointment time at the destination.
    - `Heading` number, double — GPS Heading at the position.
    - `Id` string — The waypoint Id.
    - `ServiceDuration` integer — <p>Service time spent at the destination. At an appointment, the service time should be the appointment duration.</p> <p> <b>Unit</b>: <code>seconds</code> </p>
    - `SideOfStreet` object — Options to configure matching the provided position to a side of the street.
      - `Position` Double[], required — Position in World Geodetic System (WGS 84) format: [longitude, latitude].
      - `UseWith` 'AnyStreet' | 'DividedStreetOnly' — <p>Strategy that defines when the side of street position should be used. AnyStreet will always use the provided position.</p> <p>Default value: <code>DividedStreetOnly</code> </p>
  - `Driver` object — Driver related options.
    - `RestCycles` object — Driver work-rest schedules defined by a short and long cycle. A rest needs to be taken after the short work duration. The short cycle can be repeated until you hit the long work duration, at which point the long rest duration should be taken before restarting.
      - `LongCycle` object, required — Long cycle for a driver work-rest schedule.
        - `RestDuration` integer, required — <p>Resting phase of the cycle.</p> <p> <b>Unit</b>: <code>seconds</code> </p>
        - `WorkDuration` integer, required — <p>Working phase of the cycle.</p> <p> <b>Unit</b>: <code>seconds</code> </p>
      - `ShortCycle` object, required — Short cycle for a driver work-rest schedule
        - `RestDuration` integer, required — <p>Resting phase of the cycle.</p> <p> <b>Unit</b>: <code>seconds</code> </p>
        - `WorkDuration` integer, required — <p>Working phase of the cycle.</p> <p> <b>Unit</b>: <code>seconds</code> </p>
    - `RestProfile` object — Pre defined rest profiles for a driver schedule. The only currently supported profile is EU.
      - `Profile` string, password, required — Pre defined rest profiles for a driver schedule. The only currently supported profile is EU.
    - `TreatServiceTimeAs` 'Rest' | 'Work', password — If the service time provided at a waypoint/destination should be considered as rest or work. This contributes to the total time breakdown returned within the response.
  - `Exclude` object — Specifies strict exclusion options for the route calculation. This setting mandates that the router will avoid any routes that include the specified options, rather than merely attempting to minimize them.
    - `Countries` CountryCode[] — List of countries to be avoided defined by two-letter or three-letter country codes.
  - `OptimizeSequencingFor` 'FastestRoute' | 'ShortestRoute' — <p>Specifies the optimization criteria for the calculated sequence.</p> <p>Default value: <code>FastestRoute</code>.</p>
  - `Origin` Double[], required — The start position for the route in World Geodetic System (WGS 84) format: [longitude, latitude].
  - `OriginOptions` object — Origin related options.
    - `Id` string — The Origin Id.
  - `Traffic` object — Options related to traffic.
    - `Usage` 'IgnoreTrafficData' | 'UseTrafficData' — <p>Determines if traffic should be used or ignored while calculating the route.</p> <p>Default value: <code>UseTrafficData</code> </p>
  - `TravelMode` 'Car' | 'Pedestrian' | 'Scooter' | 'Truck' — <p>Specifies the mode of transport when calculating a route. Used in estimating the speed of travel and road compatibility.</p> <p>Default value: <code>Car</code> </p>
  - `TravelModeOptions` object — Travel mode related options for the provided travel mode.
    - `Pedestrian` object — Travel mode options when the provided travel mode is <code>Pedestrian</code>.
      - `Speed` number, double — <p>Walking speed.</p> <p> <b>Unit</b>: <code>kilometers per hour</code> </p>
    - `Truck` object — Travel mode options when the provided travel mode is <code>Truck</code>.
      - `GrossWeight` integer — <p>Gross weight of the vehicle including trailers, and goods at capacity.</p> <p> <b>Unit</b>: <code>kilograms</code> </p>
      - `HazardousCargos` WaypointOptimizationHazardousCargoType[] — List of Hazardous cargo contained in the vehicle.
      - `Height` integer — <p>Height of the vehicle.</p> <p> <b>Unit</b>: <code>centimeters</code> </p>
      - `Length` integer — <p>Length of the vehicle.</p> <p> <b>Unit</b>: <code>centimeters</code> </p>
      - `Trailer` object — Trailer options corresponding to the vehicle.
        - `TrailerCount` integer — <p>Number of trailers attached to the vehicle.</p> <p>Default value: <code>0</code> </p>
      - `TruckType` 'StraightTruck' | 'Tractor', password — The type of truck: <code>LightTruck</code> for smaller delivery vehicles, <code> StraightTruck</code> for rigid body trucks, or <code>Tractor</code> for tractor-trailer combinations.
      - `TunnelRestrictionCode` string, password — <p>The tunnel restriction code.</p> <p>Tunnel categories in this list indicate the restrictions which apply to certain tunnels in Great Britain. They relate to the types of dangerous goods that can be transported through them.</p> <ul> <li> <p> <i>Tunnel Category B</i> </p> <ul> <li> <p> <i>Risk Level</i>: Limited risk</p> </li> <li> <p> <i>Restrictions</i>: Few restrictions</p> </li> </ul> </li> <li> <p> <i>Tunnel Category C</i> </p> <ul> <li> <p> <i>Risk Level</i>: Medium risk</p> </li> <li> <p> <i>Restrictions</i>: Some restrictions</p> </li> </ul> </li> <li> <p> <i>Tunnel Category D</i> </p> <ul> <li> <p> <i>Risk Level</i>: High risk</p> </li> <li> <p> <i>Restrictions</i>: Many restrictions occur</p> </li> </ul> </li> <li> <p> <i>Tunnel Category E</i> </p> <ul> <li> <p> <i>Risk Level</i>: Very high risk</p> </li> <li> <p> <i>Restrictions</i>: Restricted tunnel</p> </li> </ul> </li> </ul>
      - `WeightPerAxle` integer — <p>Heaviest weight per axle irrespective of the axle type or the axle group. Meant for usage in countries where the differences in axle types or axle groups are not distinguished.</p> <p> <b>Unit</b>: <code>kilograms</code> </p>
      - `Width` integer — <p>Width of the vehicle.</p> <p> <b>Unit</b>: <code>centimeters</code> </p>
  - `Waypoints` WaypointOptimizationWaypoint[] — <p>List of waypoints between the <code>Origin</code> and <code>Destination</code>, in World Geodetic System (WGS 84) format: [longitude, latitude].</p> <p>The maximum number of waypoints allowed per request:</p> <ul> <li> <p>Maximum 50 waypoints per request</p> </li> <li> <p>Maximum 20 waypoints when using constraints (<code>AccessHours</code>, <code>AppointmentTime</code>, <code>ServiceDuration</code>, <code>Heading</code>, <code>SideOfStreet</code>, <code>Before</code>)</p> </li> </ul>
    - `AccessHours` object — Access hours corresponding to when a waypoint can be visited.
      - `From` object, required — Contains the ID of the starting waypoint in this connection.
        - `DayOfWeek` 'Monday' | 'Tuesday' | 'Wednesday' | 'Thursday' | 'Friday' | 'Saturday' | 'Sunday', password, required — Day of the week.
        - `TimeOfDay` string, password, required — Time of the day.
      - `To` object, required — Contains the ID of the ending waypoint in this connection.
        - `DayOfWeek` 'Monday' | 'Tuesday' | 'Wednesday' | 'Thursday' | 'Friday' | 'Saturday' | 'Sunday', password, required — Day of the week.
        - `TimeOfDay` string, password, required — Time of the day.
    - `AppointmentTime` string, password — Appointment time at the waypoint.
    - `Before` WaypointIndex[] — Constraint defining what waypoints are to be visited after this waypoint.
    - `Heading` number, double — GPS Heading at the position.
    - `Id` string — The waypoint Id.
    - `Position` Double[], required — Position in World Geodetic System (WGS 84) format: [longitude, latitude].
    - `ServiceDuration` integer — <p>Service time spent at the waypoint. At an appointment, the service time should be the appointment duration.</p> <p> <b>Unit</b>: <code>seconds</code> </p>
    - `SideOfStreet` object — Options to configure matching the provided position to a side of the street.
      - `Position` Double[], required — Position in World Geodetic System (WGS 84) format: [longitude, latitude].
      - `UseWith` 'AnyStreet' | 'DividedStreetOnly' — <p>Strategy that defines when the side of street position should be used. AnyStreet will always use the provided position.</p> <p>Default value: <code>DividedStreetOnly</code> </p>

## Response `200`

Success

- OptimizeWaypointsResponse
  - `Connections` WaypointOptimizationConnection[], required — Details about the connection from one waypoint to the next, within the optimized sequence.
    - `Distance` integer, required — Distance of the step.
    - `From` string, required — contains the ID of the starting waypoint in this connection.
    - `RestDuration` integer, required — Resting time before the driver can continue driving.
    - `To` string, required — Contains the ID of the ending waypoint in this connection.
    - `TravelDuration` integer, required — <p>Total duration.</p> <p> <b>Unit</b>: <code>seconds</code> </p>
    - `WaitDuration` integer, required — <p>Duration of a wait step.</p> <p> <b>Unit</b>: <code>seconds</code> </p>
  - `Distance` integer, required — Overall distance to travel the whole sequence.
  - `Duration` integer, required — <p>Overall duration to travel the whole sequence.</p> <p> <b>Unit</b>: <code>seconds</code> </p>
  - `ImpedingWaypoints` WaypointOptimizationImpedingWaypoint[], required — Returns waypoints that caused the optimization problem to fail, and the constraints that were unsatisfied leading to the failure.
    - `FailedConstraints` WaypointOptimizationFailedConstraint[], required — Failed constraints for an impeding waypoint.
      - `Constraint` 'AccessHours' | 'AppointmentTime' | 'Before' | 'Heading' | 'ServiceDuration' | 'SideOfStreet', password — The failed constraint.
      - `Reason` string, password — Reason for the failed constraint.
    - `Id` string, required — The waypoint Id.
    - `Position` Double[], required — Position in World Geodetic System (WGS 84) format: [longitude, latitude].
  - `OptimizedWaypoints` WaypointOptimizationOptimizedWaypoint[], required — Waypoints in the order of the optimized sequence.
    - `ArrivalTime` string, password — <p>Estimated time of arrival at the destination.</p> <p>Time format:<code>YYYY-MM-DDThh:mm:ss.sssZ | YYYY-MM-DDThh:mm:ss.sss+hh:mm</code> </p> <p>Examples:</p> <p> <code>2020-04-22T17:57:24Z</code> </p> <p> <code>2020-04-22T17:57:24+02:00</code> </p>
    - `ClusterIndex` integer — Index of the cluster the waypoint is associated with. The index is included in the response only if clustering was performed while processing the request.
    - `DepartureTime` string, password, required — <p>Estimated time of departure from the origin.</p> <p>Time format:<code>YYYY-MM-DDThh:mm:ss.sssZ | YYYY-MM-DDThh:mm:ss.sss+hh:mm</code> </p> <p>Examples:</p> <p> <code>2020-04-22T17:57:24Z</code> </p> <p> <code>2020-04-22T17:57:24+02:00</code> </p>
    - `Id` string, required — The waypoint Id.
    - `Position` Double[], required — Position in World Geodetic System (WGS 84) format: [longitude, latitude].
  - `TimeBreakdown` object, required — Time breakdown for the sequence.
    - `RestDuration` integer, required — <p>Resting phase of the cycle.</p> <p> <b>Unit</b>: <code>seconds</code> </p>
    - `ServiceDuration` integer, required — <p>Service time spent at the destination. At an appointment, the service time should be the appointment duration.</p> <p> <b>Unit</b>: <code>seconds</code> </p>
    - `TravelDuration` integer, required — <p>Traveling phase of the cycle.</p> <p> <b>Unit</b>: <code>seconds</code> </p>
    - `WaitDuration` integer, required — <p>Waiting phase of the cycle.</p> <p> <b>Unit</b>: <code>seconds</code> </p>

## Other responses

- `480` — InternalServerException
- `481` — AccessDeniedException
- `482` — ValidationException
- `483` — ThrottlingException

---

[API](https://skmtc.net/aws/apis/geo-routes.md) · [All operations](https://skmtc.net/aws/apis/geo-routes/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/aws/geo-routes/versions/530ae2662aa3/schema)