Murray Picton

Free UK Postcode Lookup Using the Google Maps API

Google Maps has a well know API that can be used for great things. The most common one of course – putting a map on your website and placing markers to show where things are. One thing I never realised is that as well as the standard Javascript API that is most commonly used, Google offers a Web Service that offers a lot of the functionality but can be used on the server-side. It’s this web service functionality that will provide us with free UK postcode lookup, something you normally have to pay for due to Royal Mail’s restrictive copyright policies.

Note: In the following scripts I am assuming use of the Google Maps API Version 3.0

Google Maps Web Service

The Google Maps Web Service is a REST based service. This means that it uses standard HTTP protocols to communicate and therefore it makes it really easy to integrate with. REST services don’t have any specific return format, and in the case of this one Google has chosen to return either XML or JSON formats depending on what is needed.

REST opens up specific URLs to send a standard HTTP GET request to get the data required. In the case of the Google Maps Web Service, it opens up URLS that look something like the following:


http://maps.googleapis.com/maps/api/service/output?parameters

For more information on the Google Web Service format and requirements take a look at the documentation. Requests to the Geocoding API that we are going to use in our code doesn’t require any signing or client IDs and is available to be used by anyone that is able to script it correctly. Of course, as everything free, it comes with usage limits and terms and conditions.

The Geocoding API

The trick to postcode lookup is geocoding the location from postcode into full address. Google makes this possible with the Geocoding API. As described earlier, the API takes the form of a REST web service that offers a JSON or XML response. The format of the request needs to take the format of:

http://maps.googleapis.com/maps/api/geocode/output?parameters

output” should be replaced with the output format we would like (XML or JSON) in lowercase. ”parameters” should be replaced with the parameters involved in our geocoding request – in our case we are just going to worry about the “address” parameter but there are others you can use. One thing to remember is you ALWAYS have to pass in a “sensor” parameter that is either set to true or false, this defines whether or not the web service is to use the client’s built in GPS sensor when it makes the request. In the case of this post, I am always going to set it as false because I am requesting from a server which doesn’t have a GPS sensor and, is in a different location to the client’s machine so would be inaccurate anyway.

(I assume that) Due to Royal Mail’s copyright over the postcode database, Google is unable to perform a 100% accurate postcode lookup for free. Therefore, we can’t return the “full” address from the postcode passed in, but we can return everything except for the first line. So, this just means that instead of capturing “House number” and “postcode” as is common, we will have to capture “First line of address” and “postcode”. So, let’s take a look at how we find the full address for “10 Downing Street, SW1A 2AA”. Here is the REST URL we will use (remember to urlencode() your URLs):

Note: I am going to request an XML response from now on as it is easy to use in PHP


http://maps.googleapis.com/maps/api/geocode/xml?address=10+Downing+Street,+SW1A+2AA&sensor=false

I am not going to post the response as it is quite long, if you want to take a look at it, just paste the URL into your browser and then take a look at the source.

Decoding the Geocoding API Response

The response that is received contains the information we need to geocode our postcode into a full address. The first step is to parse the XML using the simpleXML function within PHP:

<?php
$url = 'http://maps.googleapis.com/maps/api/geocode/xml?address=10+Downing+Street,+SW1A+2AA&sensor=false';
$parsedXML = simplexml_load_file($url);
?>

This will give us a simpleXML object that can be used to pull out the information we require. Firstly, lets check if we have received the ‘OK’ status within the response.

<?php
if($parsedXML->status != "OK") {
	echo "There has been a problem: " . $parsedXML->status;
}
?>

Once we have checked the response from Google is has an “OK” status then it means it contains the information we want and can be retrieved. In general, because we have passed in a postcode we will get a single address in the response, I will assume this in the following code. The steps needed to get our our address information is to loop through our address_component elements and retrieve the information.

<?php
$myAddress = array();
foreach($parsedXML->result->address_component as $component) {
	if(is_array($component->type)) $type = (string)$component->type[0];
	else $type = (string)$component->type;

	$myAddress[$type] = (string)$component->long_name;
}
print_r($myAddress);
?>

The output of this looks like:

Array
(
[street_number] => 10
[route] => Downing St
[locality] => London
[administrative_area_level_3] => Westminster
[administrative_area_level_2] => Greater London
[administrative_area_level_1] => England
[country] => United Kingdom
[postal_code] => SW1A 2
)

As you can see, I have decoded my postcode into a full address very easily and most importantly, it’s FREE! It is just as easy to use the web service through AJAX and getting it to return a JSON object to put it straight into a form. For more information on the Google Geocoding Web Service, take a look at the documentation, it has a full list of the fields you will receive in the response.

If you have found this useful, please take a look at my older posts and sign up to my RSS feed to get all my future posts sent straight to you. Thanks for reading!