Documentation

Developer Overview

The Shoothill Postcode API is a RESTful web service that allows Application Developers to turn GB Postcodes into Latitude/Longitude Coordinates. These coordinates can then be used, for instance, to show the postcode as a pin on a map using any online mapping service, or to calculate how near a postcode is to another postcode. It is lightweight and is designed to be used from both in-browser client-side scripting languages such as Javascipt, and from all other programming languages that can access the internet and process XML.

API

Sign-Up

Sign-up for your free api key at http://api.shoothill.com/postcode/signup

When you sign up, you will need to provide an email address (so we can email your api key to you), and the url of the website which will be using the API.

Don't worry if your application won't be running as part of a website. Simply enter your company or organisation website address. Please however ensure that you set this address as the HTTP Referrer when making requests to the service. See Setting the HTTP Referrer for details on this.

Retrieving a location for a postcode

In order to get a postcodes location, you would simply download the relevant file from a url following this pattern:

http://api.shoothill.com/postcode/<Your Api Key>/<Postcode>.<Data Format>

Items in bold should be replaced with the relevant information.

Results

The content of the file returned after a successful request depends on the format you asked for.

However, the basic structure will always be the same. There will be a "Result" object which will contain the following properties:

Property Name

Property Type

Comment

Found

Boolean

true if the postcode was found, false if not.

Postcode

String

The postcode entry as it is formatted in the Code-Point® Open data if it was found. The postcode as it was requested if it was not found.

Latitude

Double Precision Floating Point Number

Latitude of postcode using the WGS84 coordinate system.

Longitude

Double Precision Floating Point Number

Longitude of postcode using the WGS84 coordinate system.

Message

String

Message response from our server. If everything is fine then this field will generally be empty. If there is an error then inspect this field for more detail.

 An XML Schema Document can be downloaded from here.

Other responses

If we could not find the postcode you requested, then the result object you receive back will indicate this. In addition, the HTTP Status Code will be set to 404 - Not Found.

If the api key you used to access the server is invalid or your HTTP referrer is set incorrectly, the HTTP Status Code will be set to 403 - Unauthorized. More detail in this case can be found in the Message property.

If there is an error within the service the HTTP Status Code will be set to 500 - Internal Server Error.

If you have exceeded your hourly quota for requests, which by default is 120, then the HTTP Status Code will be set to 503 - Service Unavailable. More detail in this case can be found in the Message property.

Example - XML

So, for instance if your Api Key is 03A0FE82-013C-4865-8A3C-F0E59AFE118B, and you want the location for SY1 3EH in XML format, you would request the following url:

http://api.shoothill.com/postcode/03A0FE82-013C-4865-8A3C-F0E59AFE118B/SY13EH.xml

The result you receive will look like this:

<?xml version="1.0" encoding="utf-8" ?>

<Result xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://api.shoothill.com/Postcode/Schema">

  <Found>true</Found>

  <Postcode>SY1 3EH</Postcode>

  <Latitude>52.745958121510988</Latitude>

  <Longitude>-2.7432243655742674</Longitude>

  <Message />

</Result>

Example - JSON

However, if you wanted the location returned in JSON format, you would request this:

http://api.shoothill.com/postcode/03A0FE82-013C-4865-8A3C-F0E59AFE118B/SY13EH.json

The result you receive in this case will look like this:

{

  "Found":true,

  "Postcode":"SY1 3EH",

  "Latitude":52.745958121510988,

  "Longitude":-2.7432243655742674,

  "Message":""

}

 

However, you should ensure that the HTTP referrer header of the HTTP request is set to a url whose domain is the same as the url you entered when you registered for your api key.

Setting the HTTP Referrer

If you are making a request to the API from within the JavaScript of a web page then generally this will handle setting the referrer for you. However, you may be making requests for postcode locations direct from your web server, or from a desktop application or other host that does not automatically set the HTTP referrer for you.

Example - C#

Here is an example in C# of how you would programmatically set the HTTP referrer when making an request to the API:

// Create a 'HttpWebRequest' object.

HttpWebRequest myHttpWebRequest = (HttpWebRequest)WebRequest.Create(

    "http://api.shoothill.com/postcode/03A0FE82-013C-4865-8A3C-F0E59AFE118B/SY13EH.xml");

 

// Set referer property  to http://www.mycompany.com .

myHttpWebRequest.Referer = "http://www.mycompany.com";

 

// Assign the response object of 'HttpWebRequest' to a 'HttpWebResponse' variable.

HttpWebResponse myHttpWebResponse = (HttpWebResponse)myHttpWebRequest.GetResponse();

 

// Display the contents of the page to the console.

Stream streamResponse = myHttpWebResponse.GetResponseStream();

StreamReader streamRead = new StreamReader(streamResponse);

 

Char[] readBuffer = new Char[256];

int count = streamRead.Read(readBuffer, 0, 256);

 

Console.WriteLine("The contents of XML are.......");

while (count > 0)

{

    String outputData = new String(readBuffer, 0, count);

    Console.Write(outputData);

    count = streamRead.Read(readBuffer, 0, 256);

}

 

Console.WriteLine();

 

streamRead.Close();

streamResponse.Close();

 

// Release the response object resources.

myHttpWebResponse.Close();

 

Console.WriteLine("Referer to the site is:{0}", myHttpWebRequest.Referer);


 

Example - VB.NET

Here is an example in VB.NET of how you would programmatically set the HTTP referrer when making an request to the API:

' Create a 'HttpWebRequest' object.

Dim myHttpWebRequest As HttpWebRequest = DirectCast(WebRequest.Create("http://api.shoothill.com/postcode/03A0FE82-013C-4865-8A3C-F0E59AFE118B/SY13EH.xml"), HttpWebRequest)

 

' Set referer property to http://www.mycompany.com .

myHttpWebRequest.Referer = "http://www.mycompany.com"

 

' Assign the response object of 'HttpWebRequest' to a 'HttpWebResponse' variable.

Dim myHttpWebResponse As HttpWebResponse = DirectCast(myHttpWebRequest.GetResponse(), HttpWebResponse)

 

' Display the contents of the page to the console.

Dim streamResponse As Stream = myHttpWebResponse.GetResponseStream()

Dim streamRead As New StreamReader(streamResponse)

 

Dim readBuffer As [Char]() = New [Char](255) {}

Dim count As Integer = streamRead.Read(readBuffer, 0, 256)

 

Console.WriteLine("The contents of XML are.......")

While count > 0

    Dim outputData As New [String](readBuffer, 0, count)

    Console.Write(outputData)

    count = streamRead.Read(readBuffer, 0, 256)

End While

 

Console.WriteLine()

 

streamRead.Close()

streamResponse.Close()

 

' Release the response object resources.

myHttpWebResponse.Close()

 

Console.WriteLine("Referer to the site is:{0}", myHttpWebRequest.Referer)


 

API Limitations

Free version

The free version of the api is limited in order to maintain quality of service for users. This limitation is currently set to 120 location requests per hour. If your application goes over this limit, you will receive a 503 - Service Unavailable error as a response from our server. Once the requests you have previously made are more than an hour old they will cease to be counted, and you will be able to make more requests.

Premium version

We offer a paid for version of the service which will upgrade your api key to allow more requests per hour than the 120 limit. Please contact sales@shoothill.com for further information, and to obtain a quote.

 

GEOliath and Shoothill Postcode Geocoding API are Shoothill products and services. Copyright Shoothill© 2010.

This site uses Ordnance Survey data © Crown copyright and database right 2010.

This site uses Royal Mail data © Royal Mail copyright and database right 2010.

Permission has been granted to use this data under the terms of the OS OpenData License.