Web services listing
Web service documentation  -  Distances and Directions  -  Optimisation/Optimise/v1.00

DistancesAndDirections/Optimisation/Optimise (v 1.00)

Optimises a set of waypoints so that they are sequenced in a way that tries to minimise total journey time or distance. Supports multiple vehicles, timeslots, capacities, pause times, vehicle dimensions for avoiding road restrictions and TomTom-derived speed profiles data for avoiding rush hour traffic. Read the route optimisation technical document on the website for full details.

SOAP WSDL

Standard HTTP
http://services.postcodeanywhere.co.uk/DistancesAndDirections
/optimisation/Optimise/v1.00/wsdlnew.ws

Secure HTTPS
https://services.postcodeanywhere.co.uk/DistancesAndDirections
/optimisation/Optimise/v1.00/wsdlnew.ws

REST code samples & end points

We have sample code available for most development environments. Choose a language below and click the button to view the code.

View

We're more than just a SOAP service. Select an end point below and click the button to view an example.

View

Try it

Enter your values in the form below to try the service for yourself.

Name Value Type Description Default Example
VehicleIDs * Array (comma separated list) of String If provided, these should be ID strings of your choice that you can use to identify each vehicle in the output. If this field is not left blank, you must enter the same number of VehicleIDs as Origins and Destinations. If left blank, the default values V1, V2, V3,... will be used.   VanOne,VanTwo
VehicleOrigins Array (comma separated list) of String The location of the start point for each vehicle, as a postcode, an OS grid reference or lat/long coordinate. Easting/Northing pairs should be hash-separated, while Lat/Long pairs in WGS84 format should be pipe-separated. Locations should be pre-validated using the VerifyLocation web service.   WR26NJ,B495HH
VehicleDestinations Array (comma separated list) of String The location of the end point for each vehicle, as a postcode, an OS grid reference or lat/long coordinate. Easting/Northing pairs should be hash-separated, while Lat/Long pairs in WGS84 format should be pipe-separated. Locations should be pre-validated using the VerifyLocation web service.   WR26NJ,B495HH
VehicleCapacities * Array (comma separated list) of Float The maximum capacity of each vehicle, in whatever units you like. Supply no values if you do not wish to optimise by capacity; supply a single value if every vehicle has the same capacity; or supply a full array of values if each vehicle has a different capacity. -1 15,12.5
VehicleBreakStarts * Array (comma separated list) of Integer If the driver needs to take a break mid-route, specify the start time of the break in minutes from the route start time. Supply no values, or -1 if you do not wish to factor in driver breaks; supply a single value if every driver has the same break start time; or supply a full array of values if some drivers have different break start times. Each driver can have a maximum of one break. -1 240,-1
VehicleBreakLengths * Array (comma separated list) of Float If the driver needs to take a break mid-route, specify the length of the break in minutes. Supply no values, or -1 if you do not wish to factor in driver breaks; supply a single value if every driver has the same break length; or supply a full array of values if some drivers have different break lengths. Each driver can have a maximum of one break. -1 30,-1
WaypointIDs * Array (comma separated list) of String If provided, these should be ID strings of your choice that you can use to identify each Waypoint in the output. If this field is not left blank, you must enter the same number of IDs as Waypoints. If left blank, the default values W1, W2, W3,... will be used.   MyDeliveryID1,MyDeliveryID2,MyDeliveryID3
WaypointLocations Array (comma separated list) of String The location of each waypoint to visit, as a postcode, an OS grid reference or lat/long coordinate. Easting/Northing pairs should be hash-separated, while Lat/Long pairs in WGS84 format should be pipe-separated. Locations should be pre-validated using the VerifyLocation web service.   HR74DU,458706#298565,52.014|-2.843
WaypointSizes * Array (comma separated list) of Float The size of the delivery for the waypoint, in the same units as VehicleCapacities. Supply no values if you do not wish to optimise by capacity; supply a single value if every waypoint has the same size; or supply a full array of values if each waypoint has a different size. Each waypoint that has a size set greater than zero will consume 3 credits rather than 1. -1 7.5,-1,-1
WaypointPauses * Array (comma separated list) of Integer The expected pause time in minutes at each waypoint. Leave blank if there is no pause time at any waypoint; supply a single value if every waypoint has the same pause time; or supply a full array of values if each waypoint has a different pause time. 0 0,5,3
WaypointTimeslotStarts * Array (comma separated list) of Integer The start of the preferred timeslot, measured in whole minutes from the vehicle's start time. Leave blank if you do not wish to optimise by timeslot or supply a complete array of values if some or all waypoints have timeslots; if only some waypoints have timeslots, supply '-1's for the waypoints with no timeslot. Each waypoint that has a timeslot set to anything other than -1 will consume 3 credits rather than 1. -1 60,-1,-1
WaypointTimeslotEnds * Array (comma separated list) of Integer The end of the preferred timeslot, measured in whole minutes from the vehicle's start time. Leave blank if you do not wish to optimise by timeslot or supply a complete array of values if some or all waypoints have timeslots; if only some waypoints have timeslots, supply '-1's for the waypoints with no timeslot. Each waypoint that has a timeslot set to anything other than -1 will consume 3 credits rather than 1. -1 180,-1,-1
TimeslotStrictness * String An indication of how strictly you wish to adhere to the given timeslots. Weak means that a vehicle may be given a route up to 15 minutes off the optimal in order to hit a single waypoint. Medium and Strong may induce a detour of up to 30 and 60 minutes respectively. Weak Medium
DepotReloadTime * Integer The expected time a vehicle will be stationary in the depot mid-route, if capacity constraints force it to return to the depot for a reload. 0 10
ExcludeMissedTimeslots * Boolean If set to true, the optimisation algorithm will exclude a waypoint from the results if it is unable to create an efficient route that arrives at the waypoint during the given timeslot. If set to false, the results will always include every waypoint in the output, regardless of whether or not the timeslot was hit. If set to true and the route hits the waypoint very slightly early, it may wait up to {15 (Weak), 30 (Medium), 60 (Strong)} minutes at the waypoint for the timeslot to arrive, depending upon the TimeslotStrictness parameter. False False
AlwaysWaitForTimeslot * Boolean If set to true, the optimisation algorithm will always ask a driver to wait at a waypoint if they are early for the timeslot, no matter how early they are. False False
   

* Optional - if left blank the default is used.

Parameters

Each request to the web service requires a number of parameters, all of which are listed below. All requests require a key which was generated when you registered. You can create any number of keys, each of which can be reported on individually and have specific security settings.

Name Type Description Default Values Example
Key String The key to use to authenticate to the service.     AA11-AA11-AA11-AA11
VehicleIDs * Array of String If provided, these should be ID strings of your choice that you can use to identify each vehicle in the output. If this field is not left blank, you must enter the same number of VehicleIDs as Origins and Destinations. If left blank, the default values V1, V2, V3,... will be used.     VanOne,VanTwo
VehicleOrigins Array of String The location of the start point for each vehicle, as a postcode, an OS grid reference or lat/long coordinate. Easting/Northing pairs should be hash-separated, while Lat/Long pairs in WGS84 format should be pipe-separated. Locations should be pre-validated using the VerifyLocation web service.     WR26NJ,B495HH
VehicleDestinations Array of String The location of the end point for each vehicle, as a postcode, an OS grid reference or lat/long coordinate. Easting/Northing pairs should be hash-separated, while Lat/Long pairs in WGS84 format should be pipe-separated. Locations should be pre-validated using the VerifyLocation web service.     WR26NJ,B495HH
VehicleCapacities * Array of Float The maximum capacity of each vehicle, in whatever units you like. Supply no values if you do not wish to optimise by capacity; supply a single value if every vehicle has the same capacity; or supply a full array of values if each vehicle has a different capacity. -1   15,12.5
VehicleBreakStarts * Array of Integer If the driver needs to take a break mid-route, specify the start time of the break in minutes from the route start time. Supply no values, or -1 if you do not wish to factor in driver breaks; supply a single value if every driver has the same break start time; or supply a full array of values if some drivers have different break start times. Each driver can have a maximum of one break. -1   240,-1
VehicleBreakLengths * Array of Float If the driver needs to take a break mid-route, specify the length of the break in minutes. Supply no values, or -1 if you do not wish to factor in driver breaks; supply a single value if every driver has the same break length; or supply a full array of values if some drivers have different break lengths. Each driver can have a maximum of one break. -1   30,-1
WaypointIDs * Array of String If provided, these should be ID strings of your choice that you can use to identify each Waypoint in the output. If this field is not left blank, you must enter the same number of IDs as Waypoints. If left blank, the default values W1, W2, W3,... will be used.     MyDeliveryID1,MyDeli
veryID2,MyDeliveryID
3
WaypointLocations Array of String The location of each waypoint to visit, as a postcode, an OS grid reference or lat/long coordinate. Easting/Northing pairs should be hash-separated, while Lat/Long pairs in WGS84 format should be pipe-separated. Locations should be pre-validated using the VerifyLocation web service.     HR74DU,458706#298565
,52.014|-2.843
WaypointSizes * Array of Float The size of the delivery for the waypoint, in the same units as VehicleCapacities. Supply no values if you do not wish to optimise by capacity; supply a single value if every waypoint has the same size; or supply a full array of values if each waypoint has a different size. Each waypoint that has a size set greater than zero will consume 3 credits rather than 1. -1   7.5,-1,-1
WaypointPauses * Array of Integer The expected pause time in minutes at each waypoint. Leave blank if there is no pause time at any waypoint; supply a single value if every waypoint has the same pause time; or supply a full array of values if each waypoint has a different pause time. 0   0,5,3
WaypointTimeslotStarts * Array of Integer The start of the preferred timeslot, measured in whole minutes from the vehicle's start time. Leave blank if you do not wish to optimise by timeslot or supply a complete array of values if some or all waypoints have timeslots; if only some waypoints have timeslots, supply '-1's for the waypoints with no timeslot. Each waypoint that has a timeslot set to anything other than -1 will consume 3 credits rather than 1. -1   60,-1,-1
WaypointTimeslotEnds * Array of Integer The end of the preferred timeslot, measured in whole minutes from the vehicle's start time. Leave blank if you do not wish to optimise by timeslot or supply a complete array of values if some or all waypoints have timeslots; if only some waypoints have timeslots, supply '-1's for the waypoints with no timeslot. Each waypoint that has a timeslot set to anything other than -1 will consume 3 credits rather than 1. -1   180,-1,-1
TimeslotStrictness * String An indication of how strictly you wish to adhere to the given timeslots. Weak means that a vehicle may be given a route up to 15 minutes off the optimal in order to hit a single waypoint. Medium and Strong may induce a detour of up to 30 and 60 minutes respectively. Weak Weak | Medium | Strong Medium
DepotReloadTime * Integer The expected time a vehicle will be stationary in the depot mid-route, if capacity constraints force it to return to the depot for a reload. 0   10
ExcludeMissedTimeslots * Boolean If set to true, the optimisation algorithm will exclude a waypoint from the results if it is unable to create an efficient route that arrives at the waypoint during the given timeslot. If set to false, the results will always include every waypoint in the output, regardless of whether or not the timeslot was hit. If set to true and the route hits the waypoint very slightly early, it may wait up to {15 (Weak), 30 (Medium), 60 (Strong)} minutes at the waypoint for the timeslot to arrive, depending upon the TimeslotStrictness parameter. False   False
AlwaysWaitForTimeslot * Boolean If set to true, the optimisation algorithm will always ask a driver to wait at a waypoint if they are early for the timeslot, no matter how early they are. False   False

* Optional - if left blank the default is used.

Fields

The response from the web service is a table with the specification below. Where no items are found, the response will be empty (although all endpoints specify the columns). If an error occurs, the response will not follow this format. Instead the response will be an error table (see general and specific errors).

Name Type Description Values Example
VehicleNumber Integer A zero based counter indicating the vehicle number.   0
VehicleID String The ID of the vehicle, if it was supplied in the input.   VanOne
StepType String An enumeration representing the type of step on the route. Start | Finish | Delivery | Travel | Depot | Wait | Break | ExcludedWaypoint | UnreachableWaypoint Start
StepNumber Integer A zero based counter indicating the step number in this vehicle's journey.   0
WaypointID String The ID of the waypoint, if it was supplied in the input.   VanOne
Location String The location string. These will be the same as the location strings which were input.   WR26NJ
CumulativeTime Float The time at which we start this step. E.g. if the StepType is Travel, this is the time at which we set out on the journey; if the StepType is Delivery, this is the time we arrive at the delivery location. Measured in minutes, measured from the vehicle start time.   0
CumulativeDistance Integer The cumulative distance for the route so far, in metres. When StepType is Travel, this is the distance to the start of that particular journey step - e.g. the very first Travel step will have a cumulative distance of 0.   0
TotalTime Float The total time in minutes for this vehicles route, including stops.   125.367
TotalDistance Integer The total distance in metres for this vehicles route.   111680
AverageTime Float The average time in minutes for all vehicles routes, including stops.   139.167
AverageDistance Integer The average distance in metres for all vehicles routes.   153711
MaximumTime Float The maximum time in minutes of a vehicles route, including stops.   152.967
MaximumDistance Integer The maximum distance in metres of a vehicles route.   195742

Prices

This table will outline the costs (in credits) or required licenses for this web service. Many web services support both credits or licenses while many are free!

Option Cost Notes
Credit Pack: Standard 1 credit(s) Consumes 8 credits plus 1 credit for each simple waypoint and 3 credits for each complex waypoint (a complex waypoint is one that uses timeslot or capacity information.), plus 5 credits if height, weight, width, length or axle weight restriction information is input.

Response Errors

Below are the errors which are specific to this web service (more general errors are listed below). If an error occurs, an error table like the one below will be returned (developers should test for a 4 column table with columns "Error", "Description", "Cause" and "Resolution". An error response will only contain a single row.

Error Description Cause Resolution
1001 Origin required No origin was entered. Please enter an origin.
1002 Destination required No destination was entered. Please enter a destination.
1003 Waypoints required No waypoints were entered. Please enter some waypoints.
1004 Unequal Vehicle list lengths The length of the Vehicle lists were different. Ensure the Origins and Destinations lists are the same length, and if a VehicleIDs, VehicleCapacities, VehicleBreakStart or VehicleBreakLength list was entered, ensure there is either one single entry or there is exactly one entry for every Origin/Destination pair.
1005 Unequal Waypoint list lengths The length of the waypoint lists were different. If WaypointIDs, WaypointSizes, WaypointTimeslotStarts, WaypointTimeSlotEnds or WaypointPauseTimes lists are entered, ensure there is either one single entry or exactly one entry for every waypoint.
1006 VehicleCapacities not float The VehicleCapacities parameter contains an item that could not be interpreted as a floating point number. Ensure the VehicleCapacities parameter contains only floating point numbers.
1007 WaypointSizes not float The WaypointSizes parameter contains an item that could not be interpreted as a floating point number. Ensure the WaypointSizes parameter contains only floating point numbers.
1008 WaypointTimeslotStarts not integer The WaypointTimeslotStarts parameter contains an item that could not be interpreted as an integer. Ensure the WaypointTimeslotStarts parameter contains only integers.
1009 WaypointTimeslotEnds not integer The WaypointTimeslotEnds parameter contains an item that could not be interpreted as an integer. Ensure the WaypointTimeslotEnds parameter contains only integers.
1010 WaypointPauseTimes not integer The WaypointPauseTimes parameter contains an item that could not be interpreted as an integer. Ensure the WaypointPauseTimes parameter contains only integers.
1011 Invalid TimeslotStrictness The TimeslotStrictness parameter was not one of the expected values. If using the TimeslotStrictness parameter, set it to one of the allowed values.
1012 WaypointSizes too big. One of the WaypointSizes values was bigger than one of the VehicleCapacities parameters. Make sure none of the WaypointSizes are bigger than any of the VehicleCapacities.
1013 Duplicate ID Two of the provided VehicleIDs or WaypointIDs were the same. Enter a unique ID for each Vehicle and Waypoint with no duplications. IDs may be case insensitive, so a VehicleID of "ONE" and a WaypointID of "One" will trigger this error.
1014 Invalid Location One of the VehicleOrigins, VehicleDestinations or WaypointLocations could not be mapped to the road network. Please enter location strings pre-validated through the free VerifyLocation web service.
1015 Timeslot start after timeslot end The timeslot start time for one of the waypoints is after, or equal to, the timeslot end time. Ensure the timeslot start time is less than the timeslot end time.
1016 VehicleBreakStarts not integer The VehicleBreakStarts parameter contains an item that could not be interpreted as an integer. Ensure the VehicleBreakStarts parameter contains only integers.
1017 VehicleBreakLengths not integer The VehicleBreakLengths parameter contains an item that could not be interpreted as an integer. Ensure the VehicleBreakLengths parameter contains only integers.
1018 DepotReloadTime not integer The DepotReloadTime parameter could not be interpreted as an integer. Ensure the DepotReloadTime parameter contains only a single integer.
1019 ExcludeMissedTimeslots not boolean The ExcludeMissedTimeslots parameter could not be interpreted as a boolean. Ensure the ExcludeMissedTimeslots parameter contains only a boolean.
1020 AlwaysWaitForTimeslot not boolean The AlwaysWaitForTimeslot parameter could not be interpreted as a boolean. Ensure the AlwaysWaitForTimeslot parameter contains only a boolean.

General Errors

These errors are general service errors and may be returned by any web service. Note that general errors are all below 100 while service specific errors start at 1000.

Error Description Cause Resolution
-1 Unknown error The cause of the error is unknown but details have been passed to our support staff who will investigate. These problems are typically short lived and often resolved by trying again in a few minutes.
2 Unknown key The key you are using to access the service was not found. Please check the key is correct, it should be the in form AA11-AA11-AA11-AA11.
3 Account out of credit Your account is either out of credit or has insufficient credit to service this request. Please check your account balance and top it up if necessary.
4 Request not allowed from this IP The request was disallowed from the IP address. Check the security settings on the key first. If that looks fine, please contact support as it may be from an IP addresses on our blacklist.
5 Request not allowed from this URL The request was disallowed from the URL. Check the security settings on the key first. If that looks fine, please contact support as it may be from a URL on our black list.
6 Web service not available on this key The requested web service is disallowed on this key. Check the security settings on the key first. You can limit a key to certain web services.
7 Web service not available on your plan The requested web service is not currently available on your payment plan. Some services are only available in specific regions due to licensing restrictions. Please contact us for more information.
8 Key daily limit exceeded The daily limit on the key has been exceeded. Alter the daily limit on the key if the usage seems normal. Check the usage details first though to see if it is unexpected.
9 Surge protector running The surge protector is currently enabled and has temporarily suspended access to the account. You can disable the surge protector at any time but this is only recommended if you are running through a batch of requests.
10 Surge protector triggered An unusually large number of requests have been processed for your account and the surge protector has been enabled. You can disable the surge protector at any time but this is only recommended if you are running through a batch of requests.
11 No valid license available The request requires a valid license but none were found. Please check your purchase history, you may be using a license that is no longer valid or of an incorrect type.
12 Management key required To use this web service you require a management key. Management can be enabled on any key but it is recommended management keys are use with care. Log onto the website and create a new management key or change an existing key.
13 Demo limit exceeded The daily demonstration limit for this service or account has been exceeded. The limit will be reset at midnight tonight or, if you would like the limit increased, please contact us.
14 Free service limit exceeded You have used too many free web services. Many of our web services are designed to operate in several stages - the first is usually a Find service followed by a Retrieve. If you use too many Finds without the corresponding number of retrieves you will receive this error. For more information, please contact us.
15 Wrong type of key The type of key you're using isn't supported by this web service. This usually happens if you're using a user or server license with a web service that only supports transactional keys. Please try another key and try again.
16 Key expired The key you are trying to use has expired. Please check that you are using the right key - a new one may have been issued if you have recently renewed your key. Please contact us if your have any questions.