Waypoint Optimization

Service version: 1

Last edit: 2023.04.04

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`

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

Feature usage

Legend

Symbol	Meaning
✔	These features can be used together. Check corresponding field descriptions for usage details.
★	Feature has to be used in combination with the marked feature. Check corresponding field descriptions for usage details.
✘	Features can't be used together.
—	Not applicable.

Features

When I use <row>, can I use <column>?	Waypoint Constraints	Group Constraints	Time Windows	Depart At	Traffic	Service Time	Importance
Waypoint Constraints	—	✔	✔	✔	✔	✔	✔
Group Constraints	✔	—	✔	✔	✔	✔	✘
Time Windows	✔	✔	—	★	✔	✔	✔
Depart At	✔	✔	✔	—	✔	✔	✔
Traffic	✔	✔	✔	✔	—	✔	✔
Service Time	✔	✔	✔	✔	✔	—	✔
Importance	✔	✘	★	★	✔	✔	—

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.
The service requires an explicit Content-Type header set to application/json.

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'{
"waypoints": [{
    "point": {
      "latitude": waypoint_latitude,
      "longitude": waypoint_longitude
    },
    "timeWindows":[{
        "openingHour": "hour_string",
        "closingHour": "hour_string"
      }
    ],
    "serviceTimeInSeconds": service_time_s,
    "importance": waypoint_importance_value
  },
  ...
],
"options": {
  "travelMode": "type_of_vehicle",
  "vehicleMaxSpeed": max_speed_kph,
  "vehicleWeight": max_weight_kg,
  "vehicleAxleWeight": max_axle_weight_kg,
  "vehicleLength": vehicle_length_m,
  "vehicleWidth": vehicle_width_m,
  "vehicleHeight": vehicle_height_m,
  "vehicleCommercial": is_vehicle_commercial,
  "vehicleLoadType": ["load_type", ...],
  "vehicleAdrTunnelRestrictionCode": "tunnel_restriction_code",
  "outputExtensions": ["travelTimes", "routeLengths"],
  "traffic": "historical" | "live",
  "departAt": dateTime | "any" | "now",
  "waypointConstraints": {
    "originIndex": index_of_origin_endpoint,
    "destinationIndex": index_of_destination_endpoint,
    "visitingOrders": [[index_of_the_first_waypoint, index_of_the_second_waypoint], ...]
  },
  "groupConstraints": {
    "groups": [
      {
        "includedPointIndexes": [waypoint_indexes_included_in_group]
      },
      ...
    ],
    "groupOrders": [[group_indexes]]
  }
}
47}'
48'https://{baseURL}/routing/waypointoptimization/{versionNumber}?key={Your_API_Key}'

Request headers

The following table describes HTTP request headers of particular interest to Waypoint Optimization service clients.

Required headers	Description
Content-Type	Specifies the MIME type of the body of the request. Value: `application/json`

Optional headers	Description
Tracking-ID	Specifies an identifier for the request. It can be used to trace a call. The value must match the regular expression `'^[a-zA-Z0-9-]{1,100}$'`. An example of the format that matches this regular expression is UUID: (e.g., `9ac68072-c7a4-11e8-a8d5-f2801f1b9fd1` ). For details check RFC 4122. If specified, it is replicated in the Tracking-ID response header. If not specified, the service will generate a request identifier and return it in the Tracking-ID response header. It is only meant to be used for support and does not involve tracking of you or your users in any form. Value: An `identifier` for the request. Default value: A service-generated request identifier.

Optional headers

Description

Tracking-ID

Specifies an identifier for the request.

It can be used to trace a call.
The value must match the regular expression '^[a-zA-Z0-9-]{1,100}$'.
An example of the format that matches this regular expression is UUID: (e.g., 9ac68072-c7a4-11e8-a8d5-f2801f1b9fd1 ). For details check RFC 4122.
If specified, it is replicated in the Tracking-ID response header.
If not specified, the service will generate a request identifier and return it in the Tracking-ID response header.
It is only meant to be used for support and does not involve tracking of you or your users in any form.

Value: An identifier for the request.
Default value: A service-generated request identifier.

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: `api.tomtom.com`: The default global API endpoint. `kr-api.tomtom.com`: The region-specific endpoint for South Korea. See the region-specific content documentation
`versionNumber` string	Service version number. Value: `1`
`key` string	An API Key valid for the requested service. Value: Your valid `API Key`.

Required parameters

Description

baseURL
string

Base URL for calling the API.
Values:

api.tomtom.com: The default global API endpoint.
kr-api.tomtom.com: The region-specific endpoint for South Korea. See the region-specific content documentation

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{
"waypoints": [{
    "point": {
      "latitude": waypoint_latitude,
      "longitude": waypoint_longitude
    },
    "timeWindows":[{
        "openingHour": "hour_string",
        "closingHour": "hour_string"
      }
    ],
    "serviceTimeInSeconds": service_time_s,
    "importance": waypoint_importance_value
  }
  ...
],
"options": {
  "travelMode": "type_of_vehicle",
  "vehicleMaxSpeed": max_speed_kph,
  "vehicleWeight": max_weight_kg,
  "vehicleAxleWeight": max_axle_weight_kg,
  "vehicleLength": vehicle_length_m,
  "vehicleWidth": vehicle_width_m,
  "vehicleHeight": vehicle_height_m,
  "vehicleCommercial": is_vehicle_commercial,
  "vehicleLoadType": ["load_type", ...],
  "vehicleAdrTunnelRestrictionCode": "tunnel_restriction_code",
  "outputExtensions": ["travelTimes", "routeLengths"],
  "traffic": "historical" | "live",
  "departAt": dateTime | "any" | "now",
  "waypointConstraints" : {
    "originIndex": index_of_origin_endpoint,
    "destinationIndex": index_of_destination_endpoint,
    "visitingOrders": [[index_of_the_first_waypoint, index_of_the_second_waypoint], ...]
  },
  "groupConstraints": {
    "groups": [
      {
        "includedPointIndexes": [waypoint_indexes_included_in_group]
      },
      ...
    ],
    "groupOrders": [[group_indexes]]
  }
}
46}

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`. Time zone of time windows is the same as time zone of departure point. Field is not required. Default value: `[]` Minimum array size: `0` Maximum 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`
`importance` integer	Specifying `importance` for at least one waypoint turns on the waypoint exclusion feature. This feature excludes waypoints from the resulting route so that the remaining waypoints fit into desired time windows. Importance helps select which waypoints to remove. The lower the importance, the more likely the point will be excluded if necessary. An importance cannot be set for the waypoint used in `originIndex`/`destinationIndex`. An exception to this is when `originIndex`/`destinationIndex` is set to `-1`. Important notice: Setting `importance` to 100 does not guarantee a waypoint will be included in the output. Field is not required. Field requires `timeWindows`. Default value: `1` Minimum value: `1` Maximum value: `100`
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: See the European Agreement Concerning the International Carriage of Dangerous Goods by Road (ADR), United Nations, 2019, section 1.9.5 and chapter 8.6. 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.

Response body - JSON
1{
"optimizedOrder": [0, 2, 1, 3],
"excludedWaypoints": [4],
"summary": {
  "routeSummary": {
    "originIndex": 0,
    "destinationIndex": 3,
    "lengthInMeters": 2500,
    "travelTimeInSeconds": 150,
    "waitingTimeInSeconds": 0,
    "serviceTimeInSeconds": 360,
    "departureTime": "2022-05-01T08:00:00-08:00",
    "arrivalTime": "2022-05-01T08:08:30-08:00"
  },
  "legSummaries": [
    {
      "originIndex": 0,
      "destinationIndex": 2,
      "lengthInMeters": 1000,
      "travelTimeInSeconds": 60,
      "waitingTimeInSeconds": 0,
      "serviceTimeInSeconds": 120,
      "departureTime": "2022-05-01T08:02:00-08:00",
      "arrivalTime": "2022-05-01T08:03:00-08:00"
    },
    {
      "originIndex": 2,
      "destinationIndex": 1,
      "lengthInMeters": 500,
      "travelTimeInSeconds": 30,
      "waitingTimeInSeconds": 0,
      "serviceTimeInSeconds": 60,
      "departureTime": "2022-05-01T08:04:00-08:00",
      "arrivalTime": "2022-05-01T08:04:30-08:00"
    },
    {
      "originIndex": 1,
      "destinationIndex": 3,
      "lengthInMeters": 1000,
      "travelTimeInSeconds": 60,
      "waitingTimeInSeconds": 0,
      "serviceTimeInSeconds": 180,
      "departureTime": "2022-05-01T08:07:30-08:00",
      "arrivalTime": "2022-05-01T08:08:30-08:00"
    }
  ]
}
48}

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.
`excludedWaypoints` array (integer)	List of indexes excluded from the `optimizedOrder` if `importance` is provided. The `excludedWaypoints` field is present only if at least one waypoint was excluded from the `optimizedOrder`. 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

post

URL request example

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

POST request body

post
POST request body - JSON
1{
"waypoints": [
  {
    "point": {
      "latitude": 45.458546,
      "longitude": 9.15049
    }
  },
  {
    "point": {
      "latitude": 50.033688,
      "longitude": 14.8226
    }
  },
  {
    "point": {
      "latitude": 50.033688,
      "longitude": 14.538226
    }
  },
  {
    "point": {
      "latitude": 50.033688,
      "longitude": 13.538226
    }
  }
],
"options": {
  "travelMode": "truck",
  "vehicleMaxSpeed": 110
}
32}

Response body

Response body - JSON
1{
2  "optimizedOrder": [0, 2, 1, 3]
3}

Waypoint Optimization

Purpose

Service Limitations

Run this endpoint

Types

Feature usage

Legend

Features

Request data

HTTPS method: POST

URL format

curl command format

Request headers

Request parameters

POST request body

Request fields

Response data

Response body

Response fields

Response codes

Example

Request example

POST request body

Response body

HTTPS method: `POST`