Quick Links

Login

Home

Support

iShareMaps On Demand

Javascript Geocoder - UK Geocoding Website Integration

This section explains how to use the Javascript Geocoder for iShareMaps On Demand. Using this will enable you to tightly integrate geocoding capabilities into your website.

Introduction

To use the Javascript Geocoder you will need a licence key. A licence key is provided when you subscribe to an iShareMaps On Demand service. We offer a free trial so you can try it before you buy it. Please see the subscriptions page for more details.

The only file you will need to include into your web page is our geocoder.js file. Please see example below:

 <script type="text/javascript" src="http://www.astuntechnology.com/isharemaps_on_demand/v2_1/js/geocoder.js">   

</script>

You are now ready to begin Javascript geocoding!

The main Javascript function to search for an address is defined as:

searchFormattedAddress(address, licensekey, recordcount, threshold, coordsys)

This function returns the results in a multi dimensional array.

The following is some sample javascript detailing the call to the web service via Javascript

 //Test function to search for an array of formatted addressesfunction test_searchFormattedAddresses(){
     //Set the method variable
     method = "searchFormattedAddress";
     
     //To search for a Postcode
     add1 = new atAddress("","","","KT18 5AD", ""); 

    //or for a town (globally)
    add1 = new atAddress("","Epsom","Surrey","", "UK");
     
     var licensekey = 'js0000-0000-0000';  // Input your license key here  

     var recordcount = 10;  //an issue exists with this parameter but a max of 20 matches will be returned
 

var threshold = 0.85; //match rate

     var coordsys = 1;              //Call the web service & get the results       

searchFormattedAddress(address, licensekey, recordcount, threshold, coordsys);

}

Input parameters

The input parameters are defined as follows:

addresses

The addresses parameter needs to contain an array of addresses in the following format:

add1 = new atAddress("streetnumber","town","county","postcode", "country")

PLEASE NOTE: streetnumber is not used at present but is reserved for a future version

where add1 is an address variable. e.g.

add1 = new atAddress("","","","KT19 8LN", "");
add2 = new atAddress("","","","so30 3ne", "");
add3 = new atAddress("","Epsom","Surrey","", "UK");

Licence Key

The licencekey parameter must contain a valid licence key which is emailed to you on registration. If you have forgotten your key you may find it by logging on to the isharemaps.com website and clicking on Profile in the USER MENU.

Record Count

The recordcount must always be "1" when geocoding.

Threshold

This threshold should be the geocode percentage below which you do not wish to return results e.g. 0.85. If the geocode score falls below this threshold the returned results will be blank.

Co-ordinate System

This coordsys parameter represents the co-ordinates system that you wish to use. The valid entries are 0=British National Grid and 1=Longitude & Latitude - WGS84.

Results

The results are passed back in a results array.

The following is some sample javascript showing how to handle the results.

 if (result == null)
 {
     alert("It appears that your licence key is invalid");
 }
 else
 {
     // alert('Array Length: ' + result.length);
     var searchResultArea = document.getElementById("searchResultArea");
 
     var sMessage = "";
 
     //Show all the arrays
     for (i=0; i<result.length; ++i)
     {
         sMessage += 'Array No: ' + (i+1) + '\n<br>';
         sMessage += 'Entity Name: ' + result[i]['EntityName'] + '\n<br>';
         sMessage += 'x: ' + result[i]['x'] + '\n<br>';
         sMessage += 'y: ' + result[i]['y'] + '\n<br>';
         sMessage += 'score: ' + result[i]['score'];
                                 (sMessage);
                                 
         // display search results
         // alert(sMessage);
         searchResultArea.innerHTML += "<div class=\'searchResult\'>" + sMessage + "</div>";
         sMessage = "";
     }
 }
 

The results array is defined as follows:

Entity Name

EntityName contains the location result’s entity name (display name).

X

x is the longitude or British National Grid X co-ordinate, depending on co-ordinate system used.

Y

y is the latitude or British National Grid Y co-ordinate, depending on co-ordinate system used.

Score

The score represents the geocode matching score and is composed of a letter (A-C) followed by a percentage score e.g. A0.nn. The higher the score, the more accurate the result. The letter scores have the following meaning:

Prefix	Description
A	Postcode level - A match is found in the UK postcode database. This is the most detailed level
B	UK city level - A match is found in the UK city database.
C	World-wide city level - A match is found in the world-wide city database.

Example

Input

add1 = new atAddress("","","","KT19 8LN", "")
add2 = new atAddress("","","","so30 3ne", "");
add3 = new atAddress("","Epsom","Surrey","", "UK");
Additional Parameters Passed
var licensekey = 'your trial licence key here in the script';
var recordcount = 1;
var threshold = 0.85;
var coordsys = 1;

Results

Array No: 1

Entity Name: KT19 8LN
x: -0.278538985205
y: 51.3376276153
score: A0.95

Array No: 2
Entity Name: SO30 3NE
x: -1.34111680772
y: 50.9284424978
score: A0.95

Array No: 3
Entity Name: Epsom, Surrey
x: -0.26582364949
y: 51.3355603429
score: C0.95

Files

Download the whole javascript sample file here.

< Prev

[ Back ]