Waypoint Optimization

Service version: 1
Last edit: 2022.06.21

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.

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.

TypeDescription
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

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

POST
URL request format
https://{baseURL}/routing/waypointoptimization/{versionNumber}?key={Your_API_Key}

curl command format

POST
Request curl command example
1curl -v -XPOST -H "Content-type: application/json" -d
2'{
3 "waypoints": [
4 "point": {
5 "latitude": waypoint_latitude,
6 "longitude": waypoint_longitude
7 },
8 ...
9 ],
10 "options": {
11 "travelMode": "type_of_vehicle",
12 "vehicleMaxSpeed": max_speed_kph,
13 "vehicleWeight": max_weight_kg,
14 "vehicleAxleWeight": max_axle_weight_kg,
15 "vehicleLength": vehicle_length_m,
16 "vehicleWidth": vehicle_width_m,
17 "vehicleHeight": vehicle_height_m,
18 "vehicleCommercial": is_vehicle_commercial,
19 "vehicleLoadType": ["load_type", ...],
20 "vehicleAdrTunnelRestrictionCode": "tunnel_restriction_code",
21 "outputExtensions": ["travelTimes", "routeLengths"],
22 "traffic": "historical" | "live",
23 "departAt": dateTime | "any" | "now",
24 "waypointConstraints": {
25 "originIndex": index_of_origin_endpoint,
26 "destinationIndex": index_of_destination_endpoint,
27 "visitingOrders": [[index_of_the_first_waypoint, index_of_the_second_waypoint], ...]
28 },
29 "groupConstraints": {
30 "groups": [
31 {
32 "includedPointIndexes": [waypoint_indexes_included_in_group]
33 },
34 ...
35 ],
36 "groupOrders": [[group_indexes]]
37 }
38 }
39}'
40'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 parametersDescription
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

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

Request fields

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

Primary fields
FieldDescription
waypoints
array
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
options
object
Object containing parameters refining route construction.
Field is not required.
waypoint object
point
object
Point representing the waypoint's geographic coordinates.
point object
latitude
double
Latitude coordinate of the point.
longitude
double
Longitude coordinate of the point.
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
number
Vehicle length in meters. A value of 0 means that length restrictions are not considered.
Field is not required.
Default value: 0
vehicleWidth
number
Vehicle width in meters. A value of 0 means that width restrictions are not considered.
Field is not required.
Default value: 0
vehicleHeight
number
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, and arrival time.
  • "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 usecase where the time context is irrelevant. The traffic=live parameter value cannot be used together with 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.
  • 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)
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 demonstrates a successful response from the API server.

POST
Response body - JSON
1{
2 "optimizedOrder": [0, 2, 1, 3],
3 "summary": {
4 "routeSummary": {
5 "originIndex": 0,
6 "destinationIndex": 3,
7 "lengthInMeters": 2500,
8 "travelTimeInSeconds": 150,
9 "departureTime": "2022-05-01T08:00:00.00-08:00",
10 "arrivalTime": "2022-05-01T08:02:30.00-08:00"
11 },
12 "legSummaries": [{
13 "originIndex": 0,
14 "destinationIndex": 2,
15 "lengthInMeters": 1000,
16 "travelTimeInSeconds": 60,
17 "departureTime": "2022-05-01T08:00:00.00-08:00",
18 "arrivalTime": "2022-05-01T08:01:00.00-08:00"
19 },{
20 "originIndex": 2,
21 "destinationIndex": 1,
22 "lengthInMeters": 500,
23 "travelTimeInSeconds": 30,
24 "departureTime": "2022-05-01T08:01:00.00-08:00",
25 "arrivalTime": "2022-05-01T08:01:30.00-08:00"
26 },{
27 "originIndex": 1,
28 "destinationIndex": 3,
29 "lengthInMeters": 1000,
30 "travelTimeInSeconds": 60,
31 "departureTime": "2022-05-01T08:01:30.00-08:00",
32 "arrivalTime": "2022-05-01T08:02:30.00-08:00"
33 }]
34 }
35}

Response fields

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

Primary fields
FieldDescription
optimizedOrder
array (integer)
Optimized sequence of original waypoint indexes.
Indexes are based on the order of waypoints sent to the service in the request.
summary
object
Contains additional information about the route created by optimized sequence.
summary object
FieldDescription
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
FieldDescription
originIndex
integer
The origin index of the described route.
destinationIndex
integer
The destination index of the described route.
lengthInMeters
integer
Distance in meters between origin and destination indices.
travelTimeInSeconds
integer
Travel time in seconds between origin and destination indices.
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.
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

CodeMeaning and possible causes
200OK: Response returned.
400Bad 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.
404Not found: Request path is incorrect.
429Too many requests: Too many requests were sent in a given amount of time for the supplied API Key.
500Internal Server Error: The service cannot handle the request right now, an unexpected condition has occurred.
503Service Unavailable: The service cannot handle the request right now, this is certainly a temporary state.

Example

Request format

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

POST request body

POST
POST request body - JSON
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

Response body - JSON
1{
2 "optimizedOrder": [
3 0,
4 2,
5 1,
6 3
7 ]
8}