PostCoder® Addressing Software Knowledge Base For Technical Support & Frequently Asked Questions

Once your database has been primed with the grid references, the database can be queried for the nearest suppliers to a given postcode.

For the purposes of this example, we are going to use two pages - a client-side (html) page which contains the basic GUI code, and a server-side (php) page which handles the communication with the PostCoder Web SOAP service and the database.

Client-Side Page

The client-side page contains two forms, one hidden form used to communicate with the server-side page:

<!-- Hidden form to allow easy communication with server-side page -->
<form name="PostCoderForm" method="post" action="NearestExample.php" target="nearest_result">
<input type="hidden" name="postcode" />
<input type="hidden" name="radius" />
<input type="hidden" name="limit_results" />
<input type="hidden" name="identifier" value="Example - Find My Nearest" />
</form>

And another form used to collect the user's Postcode, the radius to limit the search to and the number of results to return:
<form name="NearestForm">
	<fieldset>
	<legend>Nearest Search</legend>
	<div style="float:left;">
		<div class="row">
			<label>Postcode:</label>
			<input maxlength="10" tabindex="1" type="text" name="pcode" size="9" onkeypress="if ((window.event) && (window.event.keyCode==13)) findaddress(this.value)" />
			<input id="searchbutton" tabindex="4" type="button" class="button" value="Find my Nearest"
					onclick="findaddress(this.form.pcode.value,this.form.radius.value,this.form.limit_results.value)" />
		</div>
    		<div class="row">
			<label>Radius (miles):</label>
			<input maxlength="4" tabindex="2" type="text" name="radius" size="4" value="1"/>
 		</div>
 		<div class="row">
			<label>Max Items:</label>
			<input maxlength="4" tabindex="3" type="text" name="limit_results" size="4" value="10"/>
		</div>
		<div class="row">
			<div align="center" id="message" class="message"> </div>
		</div>
		<iframe src="blank.html" class="nearestframe" id="nearest_result" name="nearest_result" width="340" height="340">
		</iframe>
	</div>
	</fieldset>
</form>

Note that we have included an element called "message" to handle error messages received from the server-side page:

On a production site, you might want to make it easier for the user to choose by offering options for radius and number of results on drop-downs with suitable bands.

Note that within this form there is an iframe called "nearest_results" which receives the results of the call to the server-side page - which would be a list of suppliers and associated information as retrieved from your database, in ascending order of distance from the supplied Postcode.

The javascript function "findaddress" and associated helper functions "showMessage" and "toggleFormButton" need to be included in you client-side page (between <script type="text/javascript"></script> tags):

The "findaddress" function loads the "PostCoderForm" form with the parameters for the SOAP request and triggers the submission of the form.

The "showMessage" function is used to display any error/warning messages in the "message" slot we cunningly included in the form earlier.

The "toggleFormButton" function provides feedback to the user that the search is in progress by changing the text on the "Find My Neareast" button.

Server-side Page

The server-side page (which we called "NearestExample.php" in the client-side page) accepts the following parameters from the client-side page, and returns either a list of matching records from your database, or a suitable error message:

The following php code is used to input these parameters from the client-side page:

The next step is to initialise the SOAP service. This is fairly standard code for setting up a SOAP service using nuSOAP:

Next, after the call to initiate_SOAP_Service($proxy);, we add some php code to lookup the grid references for the Postcode using the PostCoder Web SOAP service and if successful search the database for the nearest items and generate the results for the client-side page:

Note that we use the $proxy object returned from the "initiate_SOAP_Service" function. And as this is the last part of the main body of this script, we call a function which resets the client side form button.

The getGrids function is fairly simple, most of the code being error handling. The $proxy object is called to handle the call the SOAP service, being passed the postcode, identifier (of the client-side page, useful for statistics), and username/password for the SOAP service. The result passed back is an array of values including grid references and latitude/longitude co-ordinates.

The getNearestItems function takes the grid references, radius and limit_results parameters, queries the database for the matching items and assembles the results into the client-side page:

Most of the code should be self-explanatory because it is straightforward mySQL database access code. The SQL query which is used to extract the relevant data:

SELECTs the relevant columns FROM the "suppliers" database. The distance of each customer from the input postcode is calculated using Pythagoras' Theorem which in slightly plainer English is:

yielding a result in 10 metre units. This result is then compared with the radius in ten metre units in the "HAVING distance <= $radius_tenm" clause, limiting the results to those suppliers within the desired radius.

The LIMIT $limit_results" clause limits the number of results returned to the client-side page.

The code within the loop which outputs the results to the client-side page is as follows.

First set up the string for the distance in miles and then generate the HTML code for it:

Then set up the strings for the other database fields and generate the HTML code for them:

You should now have a set of pages which will display something like this, depending on how you style your page:

Would you like a Google Map with that?

We deliberately included the latitude and longitude co-ordinates in our database so that we had a hook into a mapping system. If you would like to add a link to a Google Map (links to other mapping systems will be similar), simply add an iframe to receive the map in your client-side code:

And add the following code in your server-side page, after the 'Website' field (or wherever you would prefer it to be!):

This calls another server-side php script "google_map.php which handles the call to the Google Maps API:

You should now have a set of pages which will display something like this, depending on how you style your page:

Conclusion

With the knowledge gained from this article, developers should be able to adapt the code presented to their specific needs.

For details on the PostCoder Web SOAP service and to sign-up for a completely free trial with full access to example source code and technical support, visit Allies Computing Ltd. Phone/Fax: +44(0)1508 494488 / +44(0)1508 494481

Full source code for client-side page

Here is the full source code for the client-side page "NearestExample.html", including styles:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"  >
<head>
<!--
********************************************************************************
	Released under the GNU General Public License

	The following copyright announcement is in compliance
	to section 2c of the GNU General Public License, and
	thus can not be removed, or can only be modified
	appropriately.

	Please leave this comment intact together with the
	following copyright announcement.

	Copyright(c) 2008 Allies Computing Ltd

	The authors provide no warranty.

	PostCoder Web SOAP - Nearest Search Example version 1.01
	By 	Allies Computing Ltd - www.allies-computing.co.uk
	Last Modified 08/10/2008

********************************************************************************
This page and its associated server-side page NearestExample.php
demonstrate how to retrieve grid reference information from the
PostCoder Web SOAP Service and search for the nearest items in a MySQL database

Insert a valid Postcoder Web Nearest user name and password into
findMyNearestExample.php, and insert a valid Google maps ID into
google_mapExample.php page before use.
********************************************************************************
-->
	<title>PostCoder Web SOAP - Nearest Example</title>
<style type="text/css">
<!--
 body, html{
	font : 11px, verdana, sans-serif;
	color				:#000080;
	background : #FFF;
}

div.main {
	width: 720px;
	padding: 5px;
}

div.row {
	clear				:both;
	padding-top			:10px;
}

iframe.nearestframe, iframe.mapframe{
	width				:340px;
	height				:340px;
	border				:1px solid #CDCDCD;
}

iframe.nearestframe{
	float				:left;
	scrolling			:auto;
	frameborder			:1;
}
iframe.mapframe{
	float				:right;
	margin-left			:10px;
}

label {
	float				:left;
	width				:10em;
	text-align			:right;
	padding				:5px 5px 0px 0px;
	font-weight			:bold;
}

fieldset {
	border				:1px solid #000080;
	padding				:10px;
}

legend {
	padding				:2px 5px;
	border				:1px solid #000080;
	text-align			:right;
}

input{
	padding				:2px;
	border				:inset 1px #330066;
}

input.button{
	font : 11px, verdana, sans-serif;
	background-color	:#E5E5E5;
	border				:inset 1px #000080;
	width				:110px;
}

div.message{
	padding				:1px;
	margin				:0px;
	font-weight			:bold;
	color				:#0000FF;
}
-->
</style>
<script type="text/javascript">
function findaddress(pcode, radius, limit_results){
	if (pcode != ''){
	    // clear the message if any
		showMessage(' ');
		// disable the button
		toggleFormButton(true);
		// submit the form and data
	    document.PostCoderForm.postcode.value = pcode;
	    document.PostCoderForm.radius.value = radius;
	    document.PostCoderForm.limit_results.value = limit_results;
		document.PostCoderForm.submit();
	}
}
function showMessage(str){
	if(document.getElementById){
		document.getElementById('message').innerHTML = str;
	}
	else if (document.all){
    		document.all['message'].innerHTML = str;
	}
}

function toggleFormButton(status) {
	var theform = document.NearestForm;
	if (status == true)
			theform.searchbutton.value = 'Searching...';
		else
			theform.searchbutton.value = 'Find my Nearest';
}
function clearMapFrame() {
	map_result.document.body.innerHTML = "";
}
</script>
</head>

<body>
<!-- Hidden form to allow easy communication with server-side page -->
<form name="PostCoderForm" method="post" action="NearestExample.php" target="nearest_result">
<input type="hidden" name="postcode" />
<input type="hidden" name="radius" />
<input type="hidden" name="limit_results" />
<input type="hidden" name="identifier" value="Example - Find My Nearest" />
</form>

<div class="main">
<form name="NearestForm">
	<fieldset>
	<legend>Nearest Search</legend>
	<div style="float:left;">
		<div class="row">
			<label>Postcode:</label>
				<input maxlength="10" tabindex="1" type="text" name="pcode" size="9" onkeypress="if ((window.event) && (window.event.keyCode==13))findaddress(this.value)" />
				<input id="searchbutton" tabindex="4" type="button" class="button" value="Find my Nearest"
							onclick="findaddress(this.form.pcode.value,this.form.radius.value,this.form.limit_results.value)" />
    	</div>
    	<div class="row">
			<label>Radius (miles):</label>
				<input maxlength="4" tabindex="2" type="text" name="radius" size="4" value="1"/>
    	</div>
    	<div class="row">
			<label>Max Items:</label>
				<input maxlength="4" tabindex="3" type="text" name="limit_results" size="4" value="10"/>
    	</div>
		<div class="row">
			<div align="center" id="message" class="message"> </div>
		<div>
		<iframe src="blank.html" class="nearestframe" id="nearest_result" name="nearest_result">
		</iframe>
		<iframe src="blank.html" class="mapframe" id="map_result" name="map_result"></iframe>
	</div>
	</fieldset>
</form>
</div>
</body>
</html>

Full source code for server-side page

(Note: Please ensure you enter your PostCoder Web SOAP username and password, and also the hostname, database name, username and password for your MySQL database in this code before use.)

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

Introduction

Build Your Address Database

Populate your database

Add addresses (optional)