DistancesAndDirections/Optimisation/UpdateWaypoints (v 1.00)
Add, edit or remove a waypoint from the existing route optimisation job. You may update several waypoints at once by passing in arrays of values; these arrays must be of equal length.
REST code samples & end points
Choose a code sample language below.
Select an end point to view an example.
Try it
Enter your values in the form below to try the service for yourself. We've put some example values in already to get you started.
* 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 |
|
JobID |
Integer |
The ID of the route optimisation job you wish to update. |
|
|
5 |
|
WaypointID |
Array of String |
An ID string of your choice that you can use to identify each waypoint in the output. This must be unique for each vehicle and waypoint in your job, and an ID should not contain a comma. WaypointIDs are case-sensitive. |
|
|
MyDeliveryID1,MyDeli
veryID2,MyDeliveryID
3 |
|
UpdateType * |
Array of String |
Specify whether you wish to add, edit or remove this waypoint from the route optimisation job. |
Add |
Add | Edit | Remove |
Add,Add,Add |
|
Location * |
Array of String |
The location of the waypoint, 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 |
|
Size * |
Array of Float |
The size of the delivery for the waypoint, in the same units as the vehicle capacities. Leave blank if you do not wish to optimise by capacity. Each waypoint that has a size set greater than zero will consume 3 credits rather than 1. |
-1 |
|
7.5,-1,-1 |
|
Pause * |
Array of Integer |
The expected pause time in minutes at the waypoint. Leave blank if there is no pause time at the waypoint. |
0 |
|
0,5,3 |
|
TimeslotStart * |
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. Each waypoint that has a timeslot set to anything other than -1 will consume 3 credits rather than 1. |
-1 |
|
60,-1,-1 |
|
TimeslotEnd * |
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. Each waypoint that has a timeslot set to anything other than -1 will consume 3 credits rather than 1. |
-1 |
|
180,-1,-1 |
|
Priority * |
Array of Float |
The relative priority assigned to the waypoint. A waypoint with priority 2x is twice as important as a waypoint with priority x. If a route is forced to miss out some waypoints, the optimisation algorithm will take this priority information into account when figuring out which ones to drop. If Priority is set for one waypoint it must be set for every waypoint. Note that 0 is an invalid priority and will cause the web service to throw an error response. |
-1 |
|
1,1,2.5 |
* 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 |
|
WaypointID |
String |
The ID of the updated waypoint. |
|
0 |
|
UpdateStatus |
Boolean |
A boolean indicating whether or not the update was successful. |
|
True |
|
FailReason |
String |
A string indicating why the update failed. If the update was a success, this will be the empty string. |
DuplicateWaypointID | WaypointIDNotFound | InvalidUpdateType | InvalidLocation | InvalidSize | InvalidPause | InvalidTimeslotStart | TimeslotStartAfterTimeslotEnd | InvalidTimeslotEnd | InvalidPriority |
|
Prices
This table will outline the credit costs or required licenses for this web service. Many web services support both credit or licenses while many are free!
| |
£25
Plan |
£50
Plan |
£100
Plan |
£250
Plan |
£500
Plan |
£1,000
Plan |
£2,500
Plan |
| There is no associated charge for look-ups using this web service. |
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 |
Invalid JobID |
No job with that ID was found on your account, or the JobID was not entered. |
Please enter a valid JobID, as returned by the "Create" web service, that is no more than three months old. |
|
1002 |
Job Already Started |
The job has already been started. |
You cannot edit the input parameters for a route optimisation job that has been completed or has already been started. Consider creating a new route optimisation job. |
|
1003 |
No Waypoint ID |
The WaypointID field was not set. |
Set the WaypointID field. |
|
1004 |
Duplicate Waypoint IDs |
Two or more WaypointIDs in your input are identical. |
You cannot update the same Waypoint twice in one request - remove one of the duplicate WaypointIDs from your input. |
|
1005 |
Inconsistent Array Lengths |
You entered arrays of values as parameters, but they are not all of the same length. |
If you enter more than one comma-separated value for WaypointID, then UpdateType, Location, Size, Pause TimeslotStart, TimeslotEnd and Priority must also have the same number of items for each array. Also, ensure your WaypointIDs do not contain commas, as these will be interpreted as multiple IDs. |
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 are 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 that the key is correct. It should be in the 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 they look fine, please contact support as it may be from an IP address 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 they look fine, please contact support as it may be from a URL on our blacklist. |
|
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. Check the usage details first to see if usage is normal. |
|
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 so 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 we advise you to use management keys with care. |
Sign in to 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. If you would like the limit increased, please contact us. |
|
14 |
Free service limit exceeded |
You have used too many free web services. |
Our web services are designed to operate in 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 use 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 recently renewed your key. Contact us if you have any questions. |