Implementing the International Store Locator

Our store locator service is not just limited to locations within the UK. However, setting up our international store locator involves a slightly different process to our UK solution. In light of this we have put together the following tutorial to guide you through the process.

Step 1: Preparation

Ok, before we start implementing the international store locator we’re going to need to prepare all of our ingredients.

Create The Location List and Add The Locations

This is done in a very similar way to the UK locations lists, except you will need to select ‘prepaid’ in the ‘Credits’ dropdown, and ‘International’ in the ‘Coverage’ dropdown.

Then, when adding the locations to the list you will need to add them using Country and Location, rather than just postcode.

Locations should be added in the form of ‘street name, town’, so an example would be:

• Oxford St, London
or
• Rue Saulnier, Paris

Create a key linked to the list.

This is done by clicking on ‘Set-up your account’ under ‘Manage’.

Choose ‘I want to add a store locator to my site’ on the first page, and the ‘Web service’ on the second, giving the key an appropriate and memorable name, and selecting the relevant daily limit. The bottom option on this page allows you to select the location list you wish to associate with the key, so select the list you made earlier, and click ‘Create’. This will supply you with a 16 digit key.

Ok, at this point you should have created a location list, and a key to link to it with.

Step 2: Coding

Now we’ve got all the bits and pieces we need to put them all together into one functioning web based lookup!

The international where’s my nearest actually consists of two separate web service calls, an international geocode, and an interrogation of your location list.

Setting Up Your Form

For the purposes of this example we’re just going to put together a very basic international locator form. The benefit of using a web service in this way is that you can always make the lookup look exactly as you want later in your CSS.

So, to start with we need to give the user somewhere to put there details, create a basic form like so:

<form>
<table>
      	<tr>
	  	<td>Country</td>
	  	<td> <select id=country>
</select>
	  	</td>
         		<td>Location</td>
         		<td><input type=text id=location size=40>
</td>
      	</tr>
</table>  
</form>

That’s great, nice and simple. But we still need to add a list of countries into the ‘Country’ drop down menu we have created. Depending on which countries you want to use, add the following code between the select tags:

<option value="DEU">Germany</option>
<option value="GBR" selected=selected>United Kingdom</option>
<option value="USA">United States of America</option>

In the above code, I have used the ‘selected’ tag to set the UK as selected by default. You can use this in a country of your choice, or leave it out altogether. You might want to tie your locator down to a single country, this can be done by leaving out the dropdown country menu and hard coding the country, but I will demonstrate this later.

Finally we need somewhere to put the data when we’ve found it. For the purpose of this tutorial I’m just going to put in a simple label, so I add in the following:

<form>
<tr>
<td>
<label id="label1"></label>
</td>
</tr>
</form>

Adding the Functions

As mentioned earlier this process actually uses two separate functions, so copy both of the following into your page:

International Geocode:

<script>
function Geocoding_International_Geocode_v1_00Begin(Key, Country, Location)
   {
      var scriptTag = document.getElementById("PCA8e5d05c3076c4c08918c5566d3530a98");
      var headTag = document.getElementsByTagName("head").item(0);
      var strUrl = "";

      //Build the url
      strUrl = "http://services.postcodeanywhere.co.uk/Geocoding/International/Geocode/v1/00/json.ws?";
      strUrl += "&Key=" + escape(Key);
      strUrl += "&Country=" + escape(Country);
      strUrl += "&Location=" + escape(Location);
      strUrl += "&CallbackFunction=Geocoding_International_Geocode_v1_00End";

      //Make the request
      if (scriptTag) 
         {
            try
              {
                  headTag.removeChild(scriptTag);
              }
            catch (e)
              {
                  //Ignore
              }
         }
      scriptTag = document.createElement("script");
      scriptTag.src = strUrl
      scriptTag.type = "text/javascript";
      scriptTag.id = "PCA8e5d05c3076c4c08918c5566d3530a98";
      headTag.appendChild(scriptTag);
   }
function Geocoding_International_Geocode_v1_00End(response)
   {
      //Test for an error
      if (response.length==1 && typeof(response[0].Error) != 'undefined')
         {
            //Show the error message
            alert(response[0].Description);
         }
      else
         {
            //Check if there were any items found
            if (response.length==0)
               {
                  alert("Sorry, no matching items found");
               }
            else
               {
			
                         var coordinates=response[0].Latitude + ', ' + response[0].Longitude;
                         StoreFinder_Interactive_RetrieveNearest_v1_00Begin
                         (
                         'AA11-AA11-AA11-AA11', 
                           coordinates,'','','','',
                          '1111');
               }
         }
   }

</script>

Replace the red code with your key, and the code or name of your location list.

As you can see there are three extra variables that I haven't filled in, so if you wish you can replace the blank '' with options from the following (in this order):

Store Finder:

<script>
function StoreFinder_Interactive_RetrieveNearest_v1_00Begin(Key, Origin, MaximumItems, MaximumRadius, MaximumTime, DistanceType, LocationLists)
   {
      var scriptTag = document.getElementById("PCAffcfc86d01db4cf8992dde4cb71a37bc");
      var headTag = document.getElementsByTagName("head").item(0);
      var strUrl = "";

      //Build the url
      strUrl = "http://services.postcodeanywhere.co.uk/StoreFinder/Interactive/RetrieveNearest/v1.00/json.ws?";
      strUrl += "&Key=" + escape(Key);
      strUrl += "&Origin=" + escape(Origin);
      strUrl += "&MaximumItems=" + escape(MaximumItems);
      strUrl += "&MaximumRadius=" + escape(MaximumRadius);
      strUrl += "&MaximumTime=" + escape(MaximumTime);
      strUrl += "&DistanceType=" + escape(DistanceType);
      strUrl += "&LocationLists=" + escape(LocationLists);
      strUrl += "&CallbackFunction=StoreFinder_Interactive_RetrieveNearest_v1_00End";

      //Make the request
      if (scriptTag) 
         {
            try
              {
                  headTag.removeChild(scriptTag);
              }
            catch (e)
              {
                  //Ignore
              }
         }
      scriptTag = document.createElement("script");
      scriptTag.src = strUrl
      scriptTag.type = "text/javascript";
      scriptTag.id = "PCAffcfc86d01db4cf8992dde4cb71a37bc";
      headTag.appendChild(scriptTag);
   }

function StoreFinder_Interactive_RetrieveNearest_v1_00End(response)
   {
      //Test for an error
      if (response.length==1 && typeof(response[0].Error) != 'undefined')
         {
            //Show the error message
            alert(response[0].Description);
         }
      else
         {
            //Check if there were any items found
            if (response.length==0)
               {
                  alert("Sorry, no matching items found");
               }
            else
               {
document.getElementById('label1').innerHTML = "Closest Store: <br /><br />" + response[0].Name + ",<br />" + response[0].Description + ",<br />" + response[0].Distance + " KM.";		  
               }
         }
   }

</script>

Again, replace the highlighted code to handle the returned data in any way you like.

The returned fields are entitled:

• 'YourId' - Your ID for the store.
• 'Name' - Your Name for the store
• 'Description' - Your Description for the store.
• 'Distance' - The distance in KM from the origin to the store.
• 'Time' - The time in minutes from the origin to the store. (Only supplied for road based Distance Type calculations)
• 'Latitude' - The WGS84 latitude coordinate of the location.
• 'Longitude' - The WGS84 Longitude coordinate of the location.

Step 3: Hooking it all up!

Ok, we’re almost there, we just need one last bit of code to kick it all off, we need to add a button. Add the following directly after the location box:

<input type=button value="Find" 
   onclick="Javascript:Geocoding_International_Geocode_v1_00Begin
      ( 
       'AA11-AA11-AA11-AA11', document.getElementById('country').value, document.getElementById('location').value
      )">

Remember to add your own key in the red section. As mentioned earlier you can tie down your search to a single country. This is done by replacing the green highlighted section with the ISO code of your chosen country. So for example a search tied down to Germany would look like this:

<input type=button value="Find" 
   onclick="Javascript:Geocoding_International_Geocode_v1_00Begin
      ( 
       'AA11-AA11-AA11-AA11',  “DEU”, document.getElementById('location').value
      )">

Step 4: All Finished!

We’re done! You should now have an up and running international store locator. Remember this is a very simple example, and you can do almost anything with the returned data, just remember to keep an eye on your element ID’s.