Dev: SM: Directions API

From AAT Wiki
Jump to navigation Jump to search


To get direction from one point to another, you will need to get the starting and destination coordinates first by using the Search streets code XML Call. This it the URL / XML Call to the Streetmaps Server for directions. KEY HERE&x1=30.853718&y1=-29.772739&x2=30.859678&y2=-30.087688 

Four Arguments are passed via the URL

KEY (string) Your Unique API key must always be passed to the server
x1 and y1 (float) The starting point. coordinates are obtained first using the search streets code
x2 and y2 (float) The destination point. Again coordinates are obtained first using the search streets code

Multi-point Routes KEY HERE&pointtype=xy&points=30.853718,-29.772739,30.859678,-30.087688,30.859772,-30.087188&fmt=xml 

The following arguments are required:

Optional Parameters

KEY (string) Your Unique API key must always be passed to the server
pointtype (string) This specifies the format of the point list
  • "xy" - Points are specified as a list x1,y1,...xn,yn
  • "enc" - Points are specified as a Polyline encoded list
points (string) pointtype=xy: x1,y1,x2,y2,...xn,yn (float list - The list of points to find directions for

pointtype=enc: A Polyline encoded list. Google has documented it well here Encoded Polyline Algorithm. Here's a page with a number of implmentations for various languages: Encoding Polylines

  • "1" - Shows the coordinate just before the X/Y in the instruction; can be used to create a vector to indicate the angle of the turn (mutually exclusive with the coords option)
  • "1" - Will not show the <route> turn-by-turn instructions; reply will only contain an overview of the route.
  • "full" - Shows a full list of coordinates indicating the path for the individual direction steps (mutually exclusive with the sv option)
  • "xml" - return the results as XML
  • "js" - return the results as JSON. If this is used, specify the JSON callback function name in the "jscb" parameter.
  • "true" - Before calculating the route, each of the points in the route list will be evaluated to see if they're within 9m of an intersection, and if so, eliminated from the list. This is to compensate for the margin of error on GPS devices which can result in incorrect waypoints which can result in incorrect routes.


Here the results from a typical XML directions request

<?xml version="1.0" ?> 
<results type="route">
 <start data="66 QUENTIN SMYTHE ROAD" /> 
 <end data="5 SMYTHE ROAD" /> 
     <route step="1" instruction="Left Into" roadname="QUENTIN SMYTHE ROAD" travelfor="898.89m" totdist="898.89m" mapx="30.8537" mapy="-29.7727" speed="60" /> 
     <route step="2" instruction="Continue Along" roadname="JOHN CHARD PLACE" travelfor="247.76m" totdist="1146.65m" mapx="30.8558" mapy="-29.7734" speed="60" /> 
     <route step="3" instruction="Right Into" roadname="KRANTZVIEW ROAD" travelfor="2138.11m" totdist="3284.76m" mapx="30.8544" mapy="-29.7752" speed="60" /> 
     <route step="4" instruction="Left Into" roadname="WILLINGDON AVENUE" travelfor="460.66m" totdist="3745.42m" mapx="30.8464" mapy="-29.7904" speed="60" /> 
     <route step="5" instruction="Right Into" roadname="PIONEER ROAD (M39) (PIONEER ROAD)" travelfor="375.09m" totdist="4120.51m" mapx="30.8484" mapy="-29.7896" speed="100" /> 
     <route step="6" instruction="Left Into" roadname="ARTHUR HOPEWELL HIGHWAY (M13) (ARTHUR HOPEWELL HIGHWAY)" travelfor="2299.28m" totdist="6419.79m" mapx="30.8459" mapy="-29.7912" speed="70" /> 
     <route step="7" instruction="Continue Along" roadname="J S MARWICK HIGHWAY (M13) (J S MARWICK HIGHWAY)" travelfor="5834.33m" totdist="12254.12m" mapx="30.8503" mapy="-29.8089" speed="120" /> 
     <route step="8" instruction="Continue Along" roadname="N3 (N3 HIGHWAY)" travelfor="6811.10m" totdist="19065.22m" mapx="30.8937" mapy="-29.8336" speed="120" /> 
     <route step="9" instruction="Right Into" roadname="N2 (N2 HIGHWAY)" travelfor="12996.47m" totdist="32061.69m" mapx="30.9515" mapy="-29.8402" speed="70" /> 
     <route step="10" instruction="Continue Along" roadname="SOUTHERN HIGHWAY (M4) (SOUTHERN HIGHWAY)" travelfor="25.76m" totdist="32087.45m" mapx="30.9491" mapy="-29.9555" speed="70" /> 
     <route step="11" instruction="Continue Along" roadname="N2 (OUTER RING ROAD)" travelfor="16971.42m" totdist="49058.87m" mapx="30.9492" mapy="-29.9558" speed="120" /> 
     <route step="12" instruction="Continue Along" roadname="MAIN ROAD (R603) (MAIN ROAD)" travelfor="470.44m" totdist="49529.31m" mapx="30.8566" mapy="-30.0902" speed="70" /> 
     <route step="13" instruction="Left Into" roadname="KINGSWAY ROAD (R102) (KINGSWAY ROAD)" travelfor="346.69m" totdist="49876.00m" mapx="30.8580" mapy="-30.0938" speed="100" /> 
     <route step="14" instruction="Left Into" roadname="KINGSWAY GARDENS" travelfor="115.50m" totdist="49991.50m" mapx="30.8592" mapy="-30.0918" speed="60" /> 
     <route step="15" instruction="Left Into" roadname="SAVORY LANE" travelfor="109.53m" totdist="50101.03m" mapx="30.8591" mapy="-30.0912" speed="60" /> 
     <route step="16" instruction="Right Into" roadname="MADELINE ROAD" travelfor="24.76m" totdist="50125.79m" mapx="30.8594" mapy="-30.0901" speed="60" /> 
     <route step="17" instruction="Left Into" roadname="MURRAY ROAD" travelfor="97.51m" totdist="50223.30m" mapx="30.8586" mapy="-30.0893" speed="60" /> 
     <route step="18" instruction="Right Into" roadname="VEARY ROAD" travelfor="162.06m" totdist="50385.36m" mapx="30.8589" mapy="-30.0889" speed="60" /> 
     <route step="19" instruction="Left Into" roadname="SMYTHE ROAD" travelfor="139.99m" totdist="50525.35m" mapx="30.8597" mapy="-30.0878" speed="60" /> 

The XML is self explanatory but here is a brief description of some the important tags

start data The road name of the starting point
end data The road name of the destination point
Step Counts the number of turs / roads you will turn / cross before you get to you destination.
instruction Lets you know which way to turn to enter the next road
roadname The name of the road you will come across
travelfor The distance you will travel for on ont he current road

totdist The total distance you have traveled so far.

mapx / mapy The coordinates of where the action will take place ie. (only really needed if you want to use a GPS system)
Speed The Speed limit on this Road.
premapx / premapy If sv=1 is specified, this will be the point just before the mapx/mapy point
coords / coord If coords=full is specified, this will contain the path of the line for this direction step

Road Classification

Each name is prefixed with one of the following codes to provide additional information about its type

F	Freeway
I	Intersection Internal
N	Named Road
C	Traffic Circle
P	Parallel Road
R	Ramp
S	Slipway
E	Unnamed Road

For example: roadname=F|N2, or C|Traffic Circle