API Quick Links

Articles and Tutorials

Directions Web Service API

The Directions Web Service allows developers to display driving instructions and images of routes on a map.

The web service can be accessed using any client software that supports standard HTTP GET requests and results can be returned in a number of text-based formats. XML and HTML is currently supported.

The directions web service is a commercial service. If you would like to use the service but don't have a subscription, contact sales@geosmart.co.nz .

Instructions Web Service

The instruction web service provides a turn-by-turn instruction of a route. Provided with named points it will create a driving instruction for traversing the points in the order specified. The output format can be either HTML or JSON as determined by the output parameter.

Request Parameters

The following request parameters are supported.

Parameter	Value	Description
stops	string	A comma-separated ordered list of stops that should be traversed. Coordinates are in NZMG. Each stop is in the format, <x>:<y>:<name>. Eg. 2661926:6492881:stopA,2662018:6493684:stopB,2661932:6494006:stopC
output	string	The type of output. Currently only supports html or json.

Example output

http://directions.geosmart.co.nz/ws/v1/instruction.php?stops=2661926:6492881:stopA,2662018:6493684:stopB,2661932:6494006:stopC&output=html

 
<div>
  <p><b>Total:</b> 1564 m (2 min)</p>
<p>Starting from stopA, go south east on ALBANY HWY</p>
<p>After 144 m , turn left onto ROTHWELL AVE</p>
<p>After 557 m , turn left onto WILLIAM PICKERING DR</p>
<p>Continue for 521 m along WILLIAM PICKERING DR to stopB</p>
<p>Starting from stopB, go north west on WILLIAM PICKERING DR</p>
<p>Continue for 341 m along WILLIAM PICKERING DR to stopC</p>
</div>

http://directions.geosmart.co.nz/ws/v1/instruction.php?stops=2661926:6492881:stopA,2662018:6493684:stopB,2661932:6494006:stopC&output=json

 
[
{
distance: 1222,
instructions : [
"Starting from stopA, go south east on ALBANY HWY",
"After 144 m , turn left onto ROTHWELL AVE",
"After 557 m , turn left onto WILLIAM PICKERING DR",
"Continue for 521 m along WILLIAM PICKERING DR to stopB"
]},
{
distance: 341,
instructions : [
"Starting from stopB, go north west on WILLIAM PICKERING DR",
"Continue for 341 m along WILLIAM PICKERING DR to stopC"
]},
]

Route Image Web Service

The route image web service provides a graphical representation of a route. Provided with named points it will create a PNG image showing a line feature on a transparent background. The GSRasterImageFeature class of the SmartFIND Maps API can be used to overlay a route image from this web service on a map (see example below).

Request Parameters

Parameter	Value	Description
stops	string	A comma-separated ordered list of stops that should be traversed. Coordinates are in NZMG. Each stop is in the format, <x>:<y><name> . Eg. 2661926:6492881:stopA,2662018:6493684:stopB,2661932:6494006:stopC
xmin	int	minimum X coordinate (NZMG) of the returned image
ymin	int	minimum Y coordinate (NZMG) of the returned image
xmax	int	maximum X coordinate (NZMG) of the returned image
ymax	int	maximum Y coordinate (NZMG) of the returned image
width	int	requested width of the image in pixels
height	int	requested height of the image in pixels

Integrating the route image web service with the maps API

If you want to use the route image web service to overlay routes on a map you will need to access it through a web proxy. The reason for this is security limitations of current browser technology. If you're running PHP on your web server it's trivial to write a proxy. For this application 4 lines of PHP is all it takes:

 
<?php
// imageproxy.php
$serviceUrl = 'http://<username>:<password>@directions.geosmart.co.nz/ws/v1/boundedimage.php';
$request = $serviceUrl . '?' . $_SERVER['QUERY_STRING'];
header('Content-Type: image/png');
echo file_get_contents($request);
?>

In the proxy the actual URL of the directions web service is defined. Because the service is protected by HTTP authentication the username and password is provided in the URL before the hostname component.

To overlay a route image on a map use the GSRasterImageFeature from the maps API. Below is a sample snippet that shows how to configure a raster feature to use the route image feature web service. Include it in your javacsript function that instantiates your map. The example below uses the coordinates of three predefined stops which of course should be replaced in your application.

 
// the variable map contains a map previously defined
var layer = map.createLayer("r1");
var callback = function(zoomLevel, bounds, dimension) {
    // we're using the imageproxy defined above. Make sure to replace the hostname and path to where you have place your proxy
    var url = "http://yourserver/path/to/imageproxy.php?stops=2661926:6492881:stopA,2662018:6493684:stopB,2661932:6494006:stopC&";
    url += "xmin=" + bounds.minX + "&ymin=" + bounds.minY + "&xmax=" + bounds.maxX + "&ymax=" + bounds.maxY;
    url += "&width=" + dimension.width + "&height=" + dimension.height;
    return url;
}
var rasterFeature = new GSRasterImageFeature(callback);
layer.addFeature(rasterFeature);