Dev: SM: Search API

From AAT Wiki
Jump to: navigation, search

Introduction

Now that the basics are out the way and you getting more familiar with tour API tools you can start using some of our advanced tools. One being the search option. Using this Search tool you will be able to retrieve the geo-coordinates of any road in South Africa using a simple XML call.


XML Call

https://www.streetmaps.co.za/api/search?key--YOUR KEY HERE--&s1=8 Egerton Road Kimberley

Three Arguments are passed via the URL

KEY (string) You Unique key must always be passed to the server
s1 (String) What to search for, this can be any plain text, for example “Old Main Road, Kloof”
s2 (string) This may contain an area to search for S1 in – If both S1 (road name) and S2 (area name) are specified, the searches will be a bit more accurate as the system doesn’t have to guess how to split S1 up.
type (string) Filter out only this kind of search result. This maybe one of: Point, Park, Water, River, Country, City, Suburb or Road.
match (number) Only display items with a "match" rank of this or higher.
cc (string list) A comma-separated list of countries to search, as specified by their ISO 3166-1 alpha-2 code (http://en.wikipedia.org/wiki/Country_code) eg: BW,KE,ZA

Results From XML Call

Below show is the XML data returned from the above search

<?xml version="1.0"?>
<results xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<match url="" altname="" boundrect="24.77959,-28.7486,24.78359,-28.74467" id="10787" number="8" distance="0" area="Herlear,Kimberley,Northern Cape,South Africa" cc="ZAF" match="10500" y="-28.74866" x="24.7795143" desc="Egerton Road,Herlear,Kimberley,Northern Cape,South Africa" layer="6" type="Road"/>
<match url="" altname="" boundrect="24.77824,-28.7497,24.78304,-28.74507" id="13796" number="8" distance="0" area="Belgravia,Kimberley,Northern Cape,South Africa" cc="ZAF" match="10500" y="-28.74866" x="24.7795143" desc="Egerton Road,Belgravia,Kimberley,Northern Cape,South Africa" layer="6" type="Road"/>
</results>

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

Type In this case the search returned "road" types. The other types that could be returned are:


Roads: Road
Features: one of Park, Water, River, Country, City, Suburb
Points of Interest: Point

desc Returns The Road name then Area then Province separated by a comma(,) .
X and Y Returns the geo coordinates of a Road Searched. The X and Y will mark the centre of that road
number If you specified a street number, and this is populated, it means that an exact number match was found for the record.
Match Compares the Results with your input and give you a number value of success rate. The highest number will be our best match .