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:
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.