Waypoint Optimization

Service version: 1
Last edit: 2022.11.09

Purpose

This endpoint optimizes a provided waypoints sequence based on road network distances. Sequence is ordered to form the fastest route.

Service Limitations

  • The maximum amount of waypoints sent in the request is 12.
  • The waypoint limit includes origin and destination.
  • The service assumes Time Windows are within 24 hours from departAt. Because of that, Time Windows ending before departAt are automatically moved to the next day if possible.

Check our Pricing and Contact Sales to enable higher limits for the amount of waypoints.

Run this endpoint

You can easily run this and other endpoints. Go to the TomTom API Explorer page and follow the directions.

Types

The following data table describes the complex data types that can be used in the Waypoint Optimization service.

Type

Description

dateTime
string

A date and time specified in RFC 3339 format with the literal „Z”, or a time zone offset.
Example:

  • 2022-06-01T16:39:57Z

  • 2022-06-01T16:39:57-08:00

hour
string

A time specified in the format HH:MM. Time is based on a 24 hour system.
Example:

  • 00:00

  • 13:37

  • 23:32

Request data

HTTPS method: POST

  • Constants and parameters enclosed in curly brackets { } must be replaced with their values.
  • Please see the following Request parameters section with the required and optional parameters tables for their values. The generic request format is as follows.

URL format

https://{baseURL}/routing/waypointoptimization/{versionNumber}?key={Your_API_Key}

curl command format

1curl -v -XPOST -H "Content-type: application/json" -d
2'{
3 "waypoints": [{
4 "point": {
5 "latitude": waypoint_latitude,
6 "longitude": waypoint_longitude
7 },
8 "timeWindows":[{
9 "openingHour": "hour_string",
10 "closingHour": "hour_string"
11 }
12 ],
13 "serviceTimeInSeconds": service_time_s
14 },
15 ...
16 ],
17 "options": {
18 "travelMode": "type_of_vehicle",
19 "vehicleMaxSpeed": max_speed_kph,
20 "vehicleWeight": max_weight_kg,
21 "vehicleAxleWeight": max_axle_weight_kg,
22 "vehicleLength": vehicle_length_m,
23 "vehicleWidth": vehicle_width_m,
24 "vehicleHeight": vehicle_height_m,
25 "vehicleCommercial": is_vehicle_commercial,
26 "vehicleLoadType": ["load_type", ...],
27 "vehicleAdrTunnelRestrictionCode": "tunnel_restriction_code",
28 "outputExtensions": ["travelTimes", "routeLengths"],
29 "traffic": "historical" | "live",
30 "departAt": dateTime | "any" | "now",
31 "waypointConstraints": {
32 "originIndex": index_of_origin_endpoint,
33 "destinationIndex": index_of_destination_endpoint,
34 "visitingOrders": [[index_of_the_first_waypoint, index_of_the_second_waypoint], ...]
35 },
36 "groupConstraints": {
37 "groups": [
38 {
39 "includedPointIndexes": [waypoint_indexes_included_in_group]
40 },
41 ...
42 ],
43 "groupOrders": [[group_indexes]]
44 }
45 }
46}'
47'https://{baseURL}/routing/waypointoptimization/{versionNumber}?key={Your_API_Key}'

Request parameters

The following table describes the parameters that can be used in a request.

  • Required parameters must be used or the call will fail.
  • Optional parameters may be used.
  • The order of request parameters is not important.

Note: There are no optional parameters in this endpoint.

Required parameters

Description

baseURL
string

Base URL for calling the API.
Values:

versionNumber
string

Service version number.
Value: 1

key
string

An API Key valid for the requested service.
Value: Your valid API Key.

POST request body

1{
2 "waypoints": [{
3 "point": {
4 "latitude": waypoint_latitude,
5 "longitude": waypoint_longitude
6 },
7 "timeWindows":[{
8 "openingHour": "hour_string",
9 "closingHour": "hour_string"
10 }
11 ],
12 "serviceTimeInSeconds": service_time_s
13 }
14 ...
15 ],
16 "options": {
17 "travelMode": "type_of_vehicle",
18 "vehicleMaxSpeed": max_speed_kph,
19 "vehicleWeight": max_weight_kg,
20 "vehicleAxleWeight": max_axle_weight_kg,
21 "vehicleLength": vehicle_length_m,
22 "vehicleWidth": vehicle_width_m,
23 "vehicleHeight": vehicle_height_m,
24 "vehicleCommercial": is_vehicle_commercial,
25 "vehicleLoadType": ["load_type", ...],
26 "vehicleAdrTunnelRestrictionCode": "tunnel_restriction_code",
27 "outputExtensions": ["travelTimes", "routeLengths"],
28 "traffic": "historical" | "live",
29 "departAt": dateTime | "any" | "now",
30 "waypointConstraints" : {
31 "originIndex": index_of_origin_endpoint,
32 "destinationIndex": index_of_destination_endpoint,
33 "visitingOrders": [[index_of_the_first_waypoint, index_of_the_second_waypoint], ...]
34 },
35 "groupConstraints": {
36 "groups": [
37 {
38 "includedPointIndexes": [waypoint_indexes_included_in_group]
39 },
40 ...
41 ],
42 "groupOrders": [[group_indexes]]
43 }
44 }
45}

Request fields

The following table describes the fields that can be used in a request body.

Primary fields

Field

Description

waypoints
array(waypoint)

A list of waypoints that the Waypoint Optimization Service will use as input, and then optimize the order of the waypoints.
Minimum array size: 2
Maximum array size: 12
Waypoints is a zero-based index array. All the indexes used in the Waypoint optimization API start at 0.

options
object

Object containing parameters refining route construction.
Field is not required.

waypoint object

point
object

Point representing the waypoint's geographic coordinates.

timeWindows
array(timeWindow)

List of time windows defined for the point.
Currently the service supports one time window per waypoint.
If a time window is defined even for a single point, optimization with time windows is turned on and default time values are applied where no explicit times are set.
A time window cannot be set for the waypoint used in originIndex. An exception to this is when originIndex is set to -1.
The departAt option is required to use timeWindows. It has to be set to now, or to a specific dateTime.
Field is not required.
Default value: []
Minimum array size: 0
Maximim array size: 1

serviceTimeInSeconds
integer

The time provided in seconds spent active at a waypoint. Those are planned activities, such as loading, unloading, delivering a parcel, etc.
This value is taken from the originIndex point presented in the leg.
The departAt option is required to use serviceTimeInSeconds. It has to be set to now, or to a specific dateTime.
Field is not required.
Default value: 0

point object

latitude
double

Latitude coordinate of the point.

longitude
double

Longitude coordinate of the point.

timeWindow object

openingHour
hour

Opening time of the point. The required format is hour.
Field is not required.
Default value: 00:00

closingHour
hour

Closing time of the point. The required format is hour.
If the closingHour value is before openingHour it is assumed to be on the next day.
If the closingHour value is before departAt both openingHour and closingHour are assumed to be on the next day.
The value for the closingHour cannot be the same as the openingHour.
Field is not required.
Default value: never closing

options object

travelMode
string

Form of transport.
Possible values:

  • "car"

  • "truck"

Field is not required.
Default value: "car"

vehicleMaxSpeed
integer

Maximum speed of the vehicle in km/h.

  • Must have a value in the range [0,250].

  • A value of 0 means that an appropriate value for the vehicle will be determined and applied during waypoint optimization.

Field is not required.
Default value: 0

vehicleWeight
integer

Vehicle weight in kg. A value of 0 means that vehicle weight restrictions are not considered.
Field is not required.
Default value: 0

vehicleAxleWeight
integer

Vehicle axle weight in kg. A value of 0 means that weight restrictions per axle are not considered.
Field is not required.
Default value: 0

vehicleLength
integer

Vehicle length in meters. A value of 0 means that length restrictions are not considered.
Field is not required.
Default value: 0

vehicleWidth
integer

Vehicle width in meters. A value of 0 means that width restrictions are not considered.
Field is not required.
Default value: 0

vehicleHeight
integer

Vehicle height in meters. A value of 0 means that height restrictions are not considered.
Field is not required.
Default value: 0

vehicleCommercial
boolean

Is vehicle used commercially. Vehicle used for commercial purposes may not be allowed to drive on some roads.
Field is not required.
Default value: false

vehicleLoadType
array (string)

List of cargo classifications of hazardous materials transported that are restricted from some roads.
For routing in the USA use US Hazamat classes:

  • "USHazmatClass1": Explosives

  • "USHazmatClass2": Compressed gas

  • "USHazmatClass3": Flammable liquids

  • "USHazmatClass4": Flammable solids

  • "USHazmatClass5": Oxidizers

  • "USHazmatClass6": Poisons

  • "USHazmatClass7": Radioactive

  • "USHazmatClass8": Corrosives

  • "USHazmatClass9": Miscellaneous

For routing in all other countries use generic classifications:

  • "otherHazmatExplosive": Explosives

  • "otherHazmatGeneral": Miscellaneous

  • "otherHazmatHarmfulToWater": Harmful to water

Possible values:

  • "USHazmatClass1"

  • "USHazmatClass2"

  • "USHazmatClass3"

  • "USHazmatClass4"

  • "USHazmatClass5"

  • "USHazmatClass6"

  • "USHazmatClass7"

  • "USHazmatClass8"

  • "USHazmatClass9"

  • "otherHazmatExplosive"

  • "otherHazmatGeneral"

  • "otherHazmatHarmfulToWater"

Note:

  • The vehicleLoadType and vehicleAdrTunnelRestrictionCode parameters are independent; please provide both if applicable.

Field is not required.
Default value: []

vehicleAdrTunnelRestrictionCode
string

ADR tunnel restrictions. If vehicleAdrTunnelRestrictionCode is specified, the vehicle is subject to ADR tunnel restrictions.

  • Vehicles with code "B" are restricted from roads with ADR tunnel categories B, C, D, and E.

  • Vehicles with code "C" are restricted from roads with ADR tunnel categories C, D, and E.

  • Vehicles with code "D" are restricted from roads with ADR tunnel categories D and E.

  • Vehicles with code "E" are restricted from roads with ADR tunnel category E.

  • If vehicleAdrTunnelRestrictionCode is not specified, no ADR tunnel restrictions apply.

Possible values:

  • "B"

  • "C"

  • "D"

  • "E"

Note:

  • The vehicleLoadType and vehicleAdrTunnelRestrictionCode parameters are independent; please provide both if applicable.

Reference:

Field is not required.

outputExtensions
array(string)

Response extensions. A list of additional information that will be returned in the response.
Possible values:

  • "travelTimes" - adds information about travel time in seconds, departure time, arrival time, waiting time, and service time. When departAt is set to any, then departureTime, arrivalTime , waitingTimeInSeconds, and serviceTimeInSeconds are not present in the response body.

  • "routeLengths" - adds information about route length in meters.

Field is not required.
Default value: []

traffic
string

Decides how traffic is considered for computing routes.
Possible values:

  • historical - Routing and estimated travel time consider historical travel times and long-term closures. Traffic jams and short-term closures during the travel time window do not influence routing or travel time.

  • live - In addition to historical travel times, routing and estimated travel time consider traffic jams and short- and long-term closures during the travel time window.


    Note: traffic=live may not be used in conjunction with travel time any, also see departAt.

Field is not required.
Default value: historical

departAt
string

The date and time of departure from the origin point.

  • Departure times apart from any and now must be specified as a dateTime in the future.

Possible values:

  • any - This mode is tailored to the use case where the time context is irrelevant. The traffic=live parameter value cannot be used together with any. Time windows cannot be used when departAt is set to any.

  • now - The departure time will be set to the processing time of the first waypoint. Processing time may be any time between sending the request and its completion. This mode is best used together with traffic=live, as the service will then always consider the most recent available traffic information during routing.

  • dateTime

Field is not required.
Default value: any

waypointConstraints
object

Optimization guidelines and constraints for waypoints.
Field is not required.

groupConstraints
object

Optimization guidelines and constraints for groups of waypoints.
Field is not required.

waypointConstraints object

originIndex
integer

Index of a waypoint (in the waypoints array) used as the origin for the route.
If set to -1, then optimization will determine the best origin point.
Default value: 0

destinationIndex
integer

Index of a waypoint (in the waypoints array) used as the destination for the route.
If set to -1, then optimization will determine the best destination point.
Default value: size(waypoints)-1

visitingOrders
array(array(integer, integer))

Defines a list of ordered pairs (A, B), where waypoint with index A will always be in the output before waypoint indexed B. Other points can be between points in the loose sequence.
Notice:

  • Each point can only be a part of one pair.
  • Points can be a part of different groups, but groupOrder has to allow described succession.

Default value: []
Min items: 2
Max items: 2

groupConstraints object

groups
array(group)

List of group definitions.
Group describes a subset of points that will be optimized so that all its elements form a group after optimization. It means that points creating a group will be next to each other in the output.
Note:

  • An index can only appear in one group and is zero-based.
  • If origin and/or destination is not optimized - selected (or default) indexes can't be part of any group.

  • If at least one group is defined - all of the other points must belong to a group.

  • If at least one group is defined - the groupOrders field must be defined.

Default value: []

groupOrders
array(array(integer))

Defines the order in which groups have to occur in the output.
Default value: []

group object

includedPointIndexes


array(integer)

Waypoint indexes that will create a group.


Default value: []

Response data

Response body

The following JSON code block example demonstrates a successful response from the API server.

1{
2 "optimizedOrder": [0, 2, 1, 3],
3 "summary": {
4 "routeSummary": {
5 "originIndex": 0,
6 "destinationIndex": 3,
7 "lengthInMeters": 2500,
8 "travelTimeInSeconds": 150,
9 "waitingTimeInSeconds": 0,
10 "serviceTimeInSeconds": 360,
11 "departureTime": "2022-05-01T08:00:00-08:00",
12 "arrivalTime": "2022-05-01T08:08:30-08:00"
13 },
14 "legSummaries": [
15 {
16 "originIndex": 0,
17 "destinationIndex": 2,
18 "lengthInMeters": 1000,
19 "travelTimeInSeconds": 60,
20 "waitingTimeInSeconds": 0,
21 "serviceTimeInSeconds": 120,
22 "departureTime": "2022-05-01T08:02:00-08:00",
23 "arrivalTime": "2022-05-01T08:03:00-08:00"
24 },
25 {
26 "originIndex": 2,
27 "destinationIndex": 1,
28 "lengthInMeters": 500,
29 "travelTimeInSeconds": 30,
30 "waitingTimeInSeconds": 0,
31 "serviceTimeInSeconds": 60,
32 "departureTime": "2022-05-01T08:04:00-08:00",
33 "arrivalTime": "2022-05-01T08:04:30-08:00"
34 },
35 {
36 "originIndex": 1,
37 "destinationIndex": 3,
38 "lengthInMeters": 1000,
39 "travelTimeInSeconds": 60,
40 "waitingTimeInSeconds": 0,
41 "serviceTimeInSeconds": 180,
42 "departureTime": "2022-05-01T08:07:30-08:00",
43 "arrivalTime": "2022-05-01T08:08:30-08:00"
44 }
45 ]
46 }
47}

Response fields

The following table describes all of the fields that can appear in a response.

Primary fields

Field

Description

optimizedOrder
array (integer)

Optimized sequence of original waypoint indexes.
Indexes are based on the order of waypoints sent to the service in the request.
Indexes used in the Waypoint Optimization API start at 0.

summary
object

Contains additional information about the route created by optimized sequence.

summary object

Field Description

routeSummary
object

Contains a summary about the route from the start to the end.

legSummaries
array (routeSummary)

Contains a summary about routes between waypoints.

routeSummary object

Field Description

originIndex
integer

The origin index of the described route.
Indexes used in the Waypoint Optimization API start at 0.

destinationIndex
integer

The destination index of the described route.
Indexes used in the Waypoint Optimization API start at 0.

lengthInMeters
integer

Distance in meters between origin and destination indices.

travelTimeInSeconds
integer

Travel time in seconds between origin and destination indices.

waitingTimeInSeconds
integer

Indicates additional time in seconds spent waiting to reach the opening time in a given travel segment. Present if at least one window constraint is used.

serviceTimeInSeconds
integer

The time spent active at a waypoint. Those are planned activities, such as loading, unloading, delivering the parcel, etc.

departureTime
string

The estimated departure time for the route, or a single leg given at the local time of the first waypoint. Specified as a dateTime.
There is a possible situation that the first departure time is set later than departAt, this is the recommended time to start the travel.
Each departureTime in the legSummaries is extended by the serviceTimeInSeconds value.
Present if at least one service time constraint is used in the request.

arrivalTime
string

The estimated arrival time for the route, or a single leg given at the local time of the last waypoint. Specified as a dateTime.

Response codes

Code

Meaning & possible causes

200

OK: Response returned.

400

Bad request:

  • One or more parameters were incorrectly specified.
  • There are too many points.
  • There are too few points.
  • Points in the request are not connected by the road network.
  • Points in the request are far away from the road.
  • Provided window constraints do not allow optimizing the route.

404

Not found: Request path is incorrect.

429

Too many requests: Too many requests were sent in a given amount of time for the supplied API Key.

500

Internal Server Error: The service cannot handle the request right now, an unexpected condition has occurred.

503

Service Unavailable: The service cannot handle the request right now, this is certainly a temporary state.

Example

Request example

https://api.tomtom.com/routing/waypointoptimization/1?key={Your_API_Key}

POST request body

1{
2 "waypoints": [
3 {
4 "point": {
5 "latitude": 45.458546,
6 "longitude": 9.15049
7 }
8 },
9 {
10 "point": {
11 "latitude": 50.033688,
12 "longitude": 14.8226
13 }
14 },
15 {
16 "point": {
17 "latitude": 50.033688,
18 "longitude": 14.538226
19 }
20 },
21 {
22 "point": {
23 "latitude": 50.033688,
24 "longitude": 13.538226
25 }
26 }
27 ],
28 "options": {
29 "travelMode": "truck",
30 "vehicleMaxSpeed": 110
31 }
32}

Response body

1{
2 "optimizedOrder": [0, 2, 1, 3]
3}