Travelling Salesman Problem Web Service
The Travelling Salesman Problem solution is a route optimisation web service solution for sales, distribution, freight, and service people.
The web service can be accessed using any client software that supports standard HTTP POST requests and results can be returned in a number of text-based formats. XML , JSON and CSV are currently supported.
Authentication
The TSP web service is a commercial service. If you would like to use the service but do not have a subscription contact sales@geosmart.co.nz.
The service uses HTTP Basic Authentication. When using the service non-interactively the username and password may be specified in the URL before the hostname component:
http://<user>:<password>@spatial.geosmart.co.nz/tsp
Request URL
HTTP POST method is used to create a new TSP route optimisation job.
http://<user>:<password>@spatial.geosmart.co.nz/tsp
Request using Web Interface
The link below allows you to request a TSP job via HTML interface.
http://<user>:<password>@spatial.geosmart.co.nz/tsp.html
Request POST Data
| Parameter | Type | Description |
|---|---|---|
stops | string | CSV location data. Each row defines one location to be optimised. The values are:
|
| service | enum('','d','m') | The service field is to instruct the web service to generate the driving instructions for one location to next from the optimised result or map view. The service 'd' will only allow you to access the optimised results with distance, time and driving instructions. The 'm' will including the 'd' option as well as the output html map view. Default to an empty string which means the optimised results with distance and time. |
Sample POST Data with Default Column Order
A001,2670922,6479941
A002,2671150,6479908,start
A003,2671240,6479761
A004,2671214,6479418,finish
Sample POST Data with User Defined Column Order
x,y,type,id
2670922,6479941,,A001
2671150,6479908,waypoint,A002
2671240,6479761,finish,A003
2671214,6479418,start,A004
Sample Request Code in PHP with Default Column Order
$stops = <<<EOF
A001,2670922,6479941
A002,2671150,6479908
A003,2671240,6479761
A004,2671214,6479418
EOF;
$options = array(
'http'=>array(
'method' => "POST",
'header' => "Accept-language: en\r\n"."Content-type: application/x-www-form-urlencoded\r\n",
'max_redirects' => 0,
'content' => http_build_query(array( 'stops' => $stops, 'service'=>'d') )));
$context = stream_context_create($options);
$response = @file_get_contents('http://<user>:<password>@spatial.geosmart.co.nz/tsp',false,$context);
Sample Response Headers
HTTP/1.0 201 Created
Date: Fri, 12 Jun 2009 03:16:58 GMT
Location: /tsp/1234
Content-Length: 9
Content-Type:
In the response headers, the Location header contains the URI for the job created. The completion time for each optimisation varies, therefore the URI can be used to get the current status of the job.
Request Job Status
http://<user>:<password>@spatial.geosmart.co.nz/tsp/<job id>
| Field | Type | Description |
|---|---|---|
| id | integer | A unique identifier |
| status | enum('pending','completed') | A status of the requested job: pending or completed |
| requested | datetime | The requested date and time |
| completed | datetime | The completed date and time |
| input | URL | A link to view the input supplied |
| output | URL | A link to view the optimisation result |
| nonoptimised_distance | integer | The total distance in metres of the non-optimsed route |
| nonoptimised_time | time (hh:mm) | The approximate driving time of the non-optimsed route |
| optimised_distance | integer | The total distance in metres of the optimsed route |
| optimised_time | time (hh:mm) | The approximate driving time of the optimsed route |
Example XML Output
<job>
<id>1234</id>
<status>completed</status>
<service>d</service>
<requested>2009-06-11 18:33:20</requested>
<completed>2009-06-11 18:39:32</completed>
<input>/tsp/2/input</input>
<output>/tsp/2/output</output>
<nonoptimised_distance>31406</nonoptimised_distance>
<nonoptimised_time>00:42</nonoptimised_time>
<optimised_distance>15615</optimised_distance>
<optimised_time>00:26</optimised_time>
</job>
Request Job Input
http://<user>:<password>@spatial.geosmart.co.nz/tsp/<job id>/input
The URL is to view the input supplied for a previously requested job. It can be returned in CSV, XML or JSON.
application/csv
http://<user>:<password>@spatial.geosmart.co.nz/tsp/<job id>/input.csv
text/xml
http://<user>:<password>@spatial.geosmart.co.nz/tsp/<job id>/input.xml
text/javascript
http://<user>:<password>@spatial.geosmart.co.nz/tsp/<job id>/input.json
Request Job Output
http://<user>:<password>@spatial.geosmart.co.nz/tsp/<job id>/output
If a job is completed then the resulting output/directions can requested using the above URL. If the job is incomplete, a 404 Not Found error will be returned.
The format of output can be CSV and XML.
application/csv
http://<user>:<password>@spatial.geosmart.co.nz/tsp/<job id>/output.csv
text/xml
http://<user>:<password>@spatial.geosmart.co.nz/tsp/<job id>/output.xml
| Field | Type | Description |
|---|---|---|
| id | integer | A unique identifier |
| x | float | The x coordinate of the location in the NZMG coordinate system |
| y | float | The y coordinate of the location in the NZMG coordinate system |
| distance | integer | The distance in metres from the previous location |
| time | time (hh:mm) | The approximate driving time from the previous location |
Example CSV output
id,x,y,distance,time
"A 29 Apollo Drive","2665166","6493817","0","00:00"
"C 13 Orbit Drive","2664865","6494304","886","00:02"
"B Tawa Drive","2663723","6494474","2086","00:04"
"E Greville Road","2663777","6494842","408","00:00"
"G Sunset Road","2664815","6492854","3403","00:05"
"D East Coast Road","2667239","6491900","3770","00:06"
"F 166 Sunnynook Road","2665618","6491896","2479","00:04"
"H Diana Drive","2664899","6490055","2583","00:05"
Request Job Directions
http://<user>:<password>@spatial.geosmart.co.nz/tsp/<job id>/directions
If a job is completed then the resulting directions can requested using the above URL. If the job is incomplete, a 404 Not Found error will be returned.
The format of directions can be CSV and XML.
application/csv
http://<user>:<password>@spatial.geosmart.co.nz/tsp/<job id>/directions.csv
text/xml
http://<user>:<password>@spatial.geosmart.co.nz/tsp/<job id>/directions.xml
| Field | Type | Description |
|---|---|---|
| id | integer | A unique identifier |
| x | float | The x coordinate of the location in the NZMG coordinate system |
| y | float | The y coordinate of the location in the NZMG coordinate system |
| distance | integer | The distance in metres from the previous location |
| time | time (hh:mm) | The approximate driving time from the previous location |
| directions | string | The driving instructions to the next stop if exists. Seperated by "|". |
Example CSV output
id,x,y,distance,time,directions
"A 29 Apollo Drive","2665166","6493817","0","00:00","Start from A 29 Apollo Drive, go west on Apollo Dr|After 319 m go straight at the roundabout onto Apollo Dr|After 130 m go right at the roundabout onto Orbit Dr|Continue for 324 m along Orbt Dr to C 13 Orbit Drive"
"C 13 Orbit Drive","2664865","6494304","886","00:02","Start from C 13 Orbit Drive, go north west on Orbit Dr|After 278 m go right onto Apollo Dr|After 359 m go left at the roundabout onto Rosedale Rd|After 1074 m go right at the roundabout onto Tawa Dr|Continue for 289 m along Tawa Dr to B Tawa Drive"
"B Tawa Drive","2663723","6494474","2086","00:04","Start from B Tawa Drive, go north on Tawa Dr|After 290 m go straight at the roundabout onto Greville Rd|Continue for 65 m along Greville Rd to E Greville Road"
"E Greville Road","2663777","6494842","408","00:00","Start from E Greville Road, go north east on Greville Rd|After 116 m go right at the roundabout onto Entry 412 Greville Rd|After 515 m go straight onto Northern Mwy|After 979 m go straiht onto Exit 414 Upper Harbour Hwy|After 501 m go left onto Constellation Dr|After 217 m go right onto Parkway Dr|After 389 m go right onto Ramp Rd|After 181 m go right onto Sunset Rd|Continue for 425 m along Sunset Rd to G Sunset Road"
"G Sunset Road","2664815","6492854","3403","00:05","Start from G Sunset Road, go north east on Sunset Rd|After 1271 m go right at the roundabout onto East Coast Rd|After 1726 m go left at the roundabout onto East Coast Rd|Continue for 744m along East Coast Rd to D East Coast Road"
"D East Coast Road","2667239","6491900","3770","00:06","Start from D East Coast Road, go north west on East Coast Rd|After 736 m go left onto Forrest Hill Rd|After 494 m go right onto Blakeborough Dr|After 176 m go left onto Grenada Ave|Ater 394 m go right onto Becroft Dr|After 450 m go left onto Sunnynook Rd|Continue for 226 m along Sunnynook Rd to F 166 Sunnynook Road"
"F 166 Sunnynook Road","2665618","6491896","2479","00:04","Start from F 166 Sunnynook Road, go south west on Sunnynook Rd|After 171 m go straight at the roundabout onto Sunnynook Rd|After 408 m go left at the roundabout onto Target Rd|After 738 m go left onto Wairau Rd|After 138 m go right onto Diana Dr|Continue for 1082 m along Diana Dr to H Diana Drive"
"H Diana Drive","2664899","6490055","2583","00:05",""
Request Job Map View
http://<user>:<password>@spatial.geosmart.co.nz/tsp/<job id>/output.html
If a job is completed and used 'm' service type then the map view will be asscessed from the link above.