Home »

A geo-location and postcode search API based on problems I’ve solved for other projects

9. June 2009 by Dave Hawes 0 Comments

This article goes through a simple api I have created and released to enable people to integrate postcode lookup features in their own applications. In a nutshell people give me the ids and postcodes of their items, which I store. Then these id’s can be searched for by providing a postcode and a radius.

I created this service after having had a couple of enquires to my business about people wanting to have the postcode lookup feature I have got on my on my www.safetytrainingnetwork.co.uk and www.trainingcoursebooker.com websites in their software.

I have just extended the service to us the free http://www.freethepostcode.org/ service which I think is a great idea and I hope it continues to grow as it removes the licencing headaches I was having by using Multimap open api. My service can still use Multimap for the Geolocation data as long as the user has a valid Multimap account (contact me if you need more details).  I have also recently found more open geo-location data at New Popular Editions Map thanks to a blog article I read from Mark Embling.

My initial thought was to be hired to do a bit of work on their projects but this has not always been as easy as it first seams, especially with geographical location problems! So I decided it would be best to create an easy and simple api for people to signup and use. I released the first version yesterday and I’ll give a brief outline of how it is put together here.

The first consideration is that I need to store the user’s data in my database to enable me to search for items within a certain radius. But why would I want all the data? Some of it might be commercially sensitive and not allowed to be stored in a 3rd party’s database. The only thing I really need is the an id and the postcode of whatever the user is wanting to make searchable. I can return these Id’s to them as part of a search enabling them to retrieve the data from their database.

To capture the data I need to make it easy for users to give and maintain their data in my system. I needed a simple Create, Retrieve, Update and Delete (CRUD) for my service. As this is a web service I decided to use a simple querystring API.

Creating and Updating Data

Lets deal with the Create and Updates first. To add data you need an account (please contact me if you want one – i’ll be coming up with a subscription package over the next few weeks). You can then create a ‘Group’ and you add items to that group. I’ve created a demo account for people to play with, to add an item to the database use the following url:


So the accountId parameter is what you get when you subscribe.

The groupId parameter is so you can have different collections in our account that you can query.

The externalId is the Id of the object in the users system.

The postcode is, well, the postcode of the item.

That’s it. If you want to update an items location just send in the query string again with the same externalId parameter.

Retrieving Data

This is the useful bit of the whole service. The query string is this:


This query will return all items in group 1 within 60 miles of the postcode PO49JS as a simple xml document:

It gives the user a list of id’s and the distance that id is from the source postcode. The user can then use this list of id’s to retrieve the relevant items from their own database and display to their users.

Deleting Data

I won’t put an actual url in that deletes data because the next google bot that visits this site will start removing things from my database!! I suppose they will but them back if I put the add link at the end of the article!


Final thoughts

While it is poor technical practice and breaks the idea of a Restful webservice to delete data using an http get request I have implemented it this way as I believe it will make my service easier for people to use. Most developers I have met do not know the http verbs PUT, POST, GET and DELETE and their differences but they all know how to create a url GET request. Perhaps I will create a proper RESTful version of this webservice for those who want to use it!

Comments are closed