Dev: SM: Example - Searching Streets

From AAT Wiki
Jump to navigation Jump to search


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 KEY HERE--&s1=quentin smythe&s2=durban

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 ( eg: BW,KE,ZA

Results From XML Call

Below show is the XML data returned from the above search

<?xml version="1.0" ?> 
<results type="search">
    <match type="Road" desc="Smythe Road, Springs, Gauteng" x="28.4860045" y="-26.2513125" match="50" /> 
    <match type="Road" desc="Quentin Close, Sandton, Gauteng" x="28.05841" y="-26.083383" match="50" /> 
    <match type="Road" desc="Quentin Street, Soweto, Gauteng" x="27.847426" y="-26.288074" match="50" /> 
    <match type="Road" desc="Smythe Avenue, Centurion, Gauteng" x="28.24026" y="-25.848188" match="50" /> 
    <match type="Road" desc="Quentin Avenue, Roodepoort, Gauteng" x="27.882732" y="-26.16856" match="50" /> 
    <match type="Road" desc="Quentin Road, Johannesburg, Gauteng" x="28.020471" y="-26.259423" match="50" /> 
    <match type="Road" desc="Smythe Street, Napier, Western Cape" x="19.890088" y="-34.47203" match="50" /> 
    <match type="Road" desc="Smythe Road, Kingsburgh, Kwazulu Natal" x="30.8596735" y="-30.0877165" match="50" /> 
    <match type="Road" desc="Smythe Street, Vanderbijlpark, Gauteng" x="27.858133" y="-26.718383" match="50" /> 
    <match type="Road" desc="Quentin Smythe Road, Kloof, Kwazulu Natal" x="30.8526775" y="-29.7730215" match="75" />

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
Match Compares the Results with your input and give you a percentage value of success rate. In this case the match to our search was only a 50% match.