How to set up an international store locator
Make a location list
The easiest way to use our Store Finder service is to set up a location list to hold the details of your stores, and it's this that will be queried with each search made.
If you don't already have one, you'll need to create a location list now. In your account click 'Add Service' at the top of the account section and choose 'Location List'.
Next, choose a meaningful name for your location list, then set the geographic coverage (international in this case). Finally, make the list prepaid (pay as you upload locations, then searches cost the same regardless of the number of locations returned) as a normal list is UK only.
What's in a list?
Each location in your list has four components:
- Location
- Country
- ID (to uniquely identify the item)
- Name (for your reference)
- Description (to display in the window - this may contain contact information, opening hours, and even HTML tags for formatting)
Uploading locations
The easiest way to upload your locations is with a CSV file. The file should have the following columns:
- Location
- Country
- Unique ID
- Name
- Description
Locations should be added in the form of 'street name, town', for example:
- Oxford St, London
- Rue Saulnier, Paris
Create a Store Finder key
All of our services require 'keys' on your account in order to work. You can set up a key for any of our services in your account by clicking on 'Add Service' on the account section. Choose 'Store Finder' to get started.
Your key will be created for you and you can now edit its settings (such as name, daily limit and security restrictions), or just get started with adding a store finder to your site.
Before you get coding though, be sure to click 'Location List', choose your new list from the dropdown menu and click 'Save' to assign your location list to your new key. Now you're ready to go.
Inserting the code
Now we have everything we need to put together into one functioning web-based lookup.
The international 'where’s my nearest' service 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 look-up look exactly as you want later in your CSS.
So, to start with, we need to give the user somewhere to enter their 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>
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, we have used the 'selected' property to select the UK 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 we will demonstrate this later.
Finally we need somewhere to put the data when we've found it. For the purpose of this tutorial we're just going to put in a simple label, so we 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 we haven't filled in, so if you wish you can replace the blank '' with options from the following (in this order):
| Variable | Description | Example |
|---|---|---|
| MaximumItems | The maximum number of items to return. If blank or 0, all items are returned. | 1 |
| MaximumRadius | The maximum search distance in KM between the origin and a store. If blank or 0, all items are returned. | 10,000 |
| MaximumTime | The maximum drive time in minutes between the origin and a store. Ignored for StraightLine DistanceType. If blank or 0, all items are returned. | 120 |
| DistanceType | Specifies how the distances between the stores are calculated. | There are only three options for this one: ‘StraightLine’, ‘FastestByRoad’, or ‘ShortestByRoad’. |
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.
The search button
The last thing we need is a button to start the search. 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
)">
And that's it. You should now have a basic international store finder ready for you to adapt to whatever requirements you may have.
Extra settings
Now you've finished, why not take a look at the extra settings for your Store Finder? It's a good idea to add some URL Restrictions, activate the IP Limiter, or adjust your Daily Limit for extra security.
Need some help?
Don't forget, if you get stuck and need a hand you can contact our support team and we'll be happy to help.