Categorised Store Locator

Prepare your lists

To begin with you will need to set up separate location lists for each category you want your customers to be able to select from. If you are unsure how to do this, this tutorial will help you set up a location list.

In this example we will create a list for hammer stockists and a list for nail stockists - it might be desirable to create a list for both, but we're not doing that here. Once you have created your location lists you will need to know their unique IDs. These can be found in the account section - the ID of each list is given as the key of the service in the table shown. In this example our IDs are:

  • Hammers: 4148
  • Nails: 4150

Next you will need to generate an API Key. In your account click the Add Service button at the top of the account section then create an API key.

Account Navigation Screenshot

Putting the lists together

Now you have all your bits and pieces for you selective store locator, you are ready to put them together. The glue that holds these together will be a JavaScript function:

function StoreFinder_Interactive_RetrieveNearest_v1_00Begin(Key, Origin, MaximumItems, MaximumRadius, MaximumTime, DistanceType, LocationLists)
 {
    var scriptTag = document.getElementById("PCA4a21c5fbe054461c888b23d07e65fe87");
    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 = "PCA4a21c5fbe054461c888b23d07e65fe87";
    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
             {
                //Put your code here
                //FYI: The output is an array of key value pairs (e.g. response[0].YourId), the keys being:
                //YourId
                //Name
                //Description
                //Distance
                //Time
                //Easting
                //Northing
                //Latitude
                //Longitude
             }
       }
 }

However, before we come to this we need a form in which to place our search:

<form>
<input type="Text" id="Postcode" />
<select id="Stock">
<option value="4148">Hammers</option>
<option value="4150">Nails</option>
</select>
<input type="button" id="Go" value="Click to find" />
<br />
<br />
<label id="label1"></label>
</form>

As you can see we have a textbox for the postcode to be entered into, a selection box for the stockist options, and a button to trigger the search. (The label will be used to return the closest store data).

Notice that the drop down menu values are set to the IDs of the location lists.

Now we need an on-click event to trigger the search, so we add this in to the button tag in the form:

<input type="button" id="Go" value="Click to find" onclick="Javascript:StoreFinder_Interactive_RetrieveNearest_v1_00Begin
('AA11-AA11-AA11-AA11', document.getElementById('Postcode').value,'','','','', document.getElementById('Stock').value)">

This will trigger the function shown above, inputting the postcode, and the location list ID from the form. Don't forget to replace the key with your own web service key.

Finally we need to do something with the returned data, so we add the following into the "//Put your code here" section of the function:

document.getElementById('label1').innerHTML = "Closest Store: <br /><br />" + response[0].Name + ",<br />" + response[0].Description + ",<br />" + response[0].Distance + " KM.";

This will return the address and details of the store closest to the entered postcode, selected from the list of stockists specified by the drop down menu. Now all you need to do is customise it so that it works exactly how you want it to.

Need 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.