Dev: SM: Example - Directions

From AAT Wiki
Jump to: navigation, search

Introduction

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.

https://www.streetmaps.co.za/ajax_route.asp?key=YOUR 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

Multipoint Routes

https://www.streetmaps.co.za/ajax_route.asp?key=YOUR KEY HERE&pointtype=xy&points=30.853718,-29.772739,30.859678,-30.087688,30.859772,-30.087188&tsp=1 

The following arguments are required:

KEY (string) Your Unique API key must always be passed to the server
pointtype=xy (string) This specifies the format of the point list
points=x1,y1,x2,y2,...xn,yn (float) The list of points to find directions for
tsp (int) The method used to determine the route.
The options are
0 - Optimization, start - end
1 - Optimization, round-trip
2 - Optimization, start - no fixed end
3 - No optimization, start-end
4 - No optimization, round-trip
10 - Optimization, start - end (straight line distances used in optimization)
11 - Optimization, round-trip (straight line distances used in optimization)
12 -Optimization, start - no fixed end (straight line distances used in optimization)

Optional Parameters

  • sv=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)
  • coords=full Shows a full list of coordinates indicating the path for the individual direction steps (mutually exclusive with the sv option)

Results

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" /> 
</results>  

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

Show Directions on the Map

Only two lines of code are used to draw the Directions / route on the map.

myMap.ShowRoute(x1,y1,x2,y2)
myMap.Init();

As discussed before you will need the starting and destination points before displaying the route on the map. And as you can see you simply place the coordinates in to the above function, initials the map, and you will see the route on the map.

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