Skip navigation

Tutorials

How to build your own UK nearest search using PostCoder Web SOAP

Page 1 of 3

Introduction

We are noticing an increasing demand from customers for a "Find my Nearest" function, particularly when associated with maps.

Providing a "Find my Nearest" function with a map of a location helps your customers to find out where the nearest suppliers of your products are located, is more professional and let's be honest it looks cool to have a map on your web page!

This article outlines how to incorporate a "Find my Nearest" function with maps into your web site or application using the PostCoder Web SOAP service. Code snippets are given in PHP, using the nuSOAP library which is distributed with the PostCoder Web SOAP examples. The database interface is MySQL, but could easily be adapted for other databases.

The example code provided with PostCoder Web SOAP is available in PHP (4 and 5), ASP.NET (C#, VB), ASP, Perl, Java and ColdFusion. The principles in this article can be used with any of the example languages, but here we'll use PHP. In order to finish up with a fully working set of pages, you should create all your pages in the same directory as the PostCoder Web SOAP PHP examples, because there are some dependent style, script and image files included with the examples.

Note: Style and accessibility code has been omitted for clarity.

Build Your Address Database

First of all, you need to set up a (or augment an existing) database which contains details of all the suppliers which you want your customers to be able to search on.

  • Supplier ID
  • Supplier Name
  • Telephone Number
  • E-mail Address
  • Web Site
  • Premise
  • Dependent Street
  • Street
  • Double Dependent Locality
  • Dependent Locality
  • Post Town
  • Postcode
  • Grid Easting
  • Grid Northing
  • Longitude
  • Latitude

The fields highlighted are those which will be populated by the PostCoder Web SOAP service.

Grid references are needed to calculate the distance between postcodes, and the latitude and longitude values are use for hooking into mapping systems such as Google Maps.

MySQL Table Editor

Figure 1 - Example database

The code required to populate the database is beyond the scope of this article, but for convenience here is the SQL to create the schema for the MySQL database illustrated above:

CREATE TABLE `suppliers` (
  `SupplierID` varchar(36) NOT NULL,
  `SupplierName` varchar(40) NOT NULL,
  `Telephone` varchar(25) default NULL,
  `EmailAddress` varchar(255) default NULL,
  `WebSite` varchar(255) default NULL,
  `Premise` text,
  `Dependent_street` varchar(80) default NULL,
  `Street` varchar(80) default NULL,
  `Double_dependent_locality` varchar(35) default NULL,
  `Dependent_locality` varchar(35) default NULL,
  `Post_town` varchar(30) default NULL,
  `Postcode` varchar(12) default NULL,
  `GridEasting` int(11) default '0',
  `GridNorthing` int(11) default '0',
  `Latitude` varchar(16) default NULL,
  `Longitude` varchar(16) default NULL,
  PRIMARY KEY  (`SupplierID`),
  KEY `GridNorthIndex` (`GridNorthing`),
  KEY `GridEastIndex` (`GridEasting`)
) ENGINE=MyISAM DEFAULT CHARSET=latin1;

Populate your database

To populate your database with addresses and/or grid references there are two options:

  • If you have a relatively small number of records, use the PostCoder Web SOAP service to lookup each address and/or grid reference one by one and add them to your database
  • If you have a large number of records, contact Allies Computing Ltd for a data extract or batch processor to populate your records with grid references

Add addresses (optional)

If you have a relatively small number of records, then use the PostCoder Web SOAP getThrfareAddresses function to lookup the address information for each of your suppliers and add your own premise information. Alternatively use the PostCoder Web SOAP getPremiseList function to lookup the full address for each of your suppliers including the premise information. You only need to lookup addresses if you wish to supply address details to users of your "Find my Nearest" search and you do not already have such address information available. You may on the other hand just provide web site addresses, where the target web site contains address details for the supplier and/or an online purchasing system.

The PostCoder Web SOAP examples contain a fully working example of the getThrfareAddresses and getPremiseList functions. However, to populate your database you will only need the server side code such as (for the PHP language) the getThrfareAddressesExample.php and getPremiseListExample.php pages.

Add Geographic Info

If you have a relatively small number of records, then use the PostCoder Web SOAP getGrids function to lookup the geographic information for each of your suppliers.

Aside from the usual code required to set up SOAP (see later in this article for example code "initiate_SOAP_Service") and check for errors, one line of code is required to retrieve the geographic info for a postcode:

$result = $proxy->getGrids($postcode,$identifier,$username,$password);

Then the following code fragment can be used to extract the geographic info from the SOAP payload into your own database (note: you will need to insert the username and password for your database):

<?php
$ACLnumRecords = $result['number_results'];
if (!empty($ACLnumRecords) && $ACLnumRecords != "0")
{
//connect to the database
$db=mysql_connect ("localhost", "username", "password") or exitScript();

//-select the database to use
$mydb=mysql_select_db("nearest");
//-update the customer record
	$update_customer = "UPDATE suppliers SET
GridEasting = '$result[grideast]',
GridNorthing = '$result[gridnorth]',
Latitude = '$result[latitude_erts89]',
Longitude = '$result[longitude_erts89]',
WHERE SupplierID = '$Supplier_ID'";
//-run  the query
$result=mysql_query($update_customer);
}
?>

You will notice that we have also loaded the latitude and longitude co-ordinates, in this case based on the ETRS89 datum. The values correspond to the latitude and longitude values used in Global Positioning Systems in the UK and Europe. Note that many online mapping systems such as Google Maps and Multimap use GPS maps and hence the ETRS89 latitude and longitude co-ordinates should be used for lookups on these systems.

The PHP exitScript function called in the "$db=mysql_connect ("localhost", "username", "password") or exitScript();" line is a generic error handling function called when the server-side script should be terminated and only a simple error message returned:

/*********************************************************************
* exitScript($message)
* Exit script, but in a tidy fashion. Uses default message unless over-ridden
*********************************************************************/
function exitScript($message='Unable to conduct Nearest search, please report to site owner')
{
	showMessage($message);
	toggleFormButton();
	exit("

We will make further use of this function later on in this article.
Back to Top