nearby.org.uk logo · Coordinate Convertor
· Interactive Feature Map
· Location Searches
· Google Earth & Maps
· UK Placenames
· GB Paper Maps
· API / Downloads
· Blog
· Support Nearby
   

nearby.org.uk Geocoder

Contains Royal Mail data © Royal mail copyright and database right 2010.

This page documents a geocoder/coordinate converter service, that brings together various conversions that this site can perform. It is not a true geocoder(wikipedia) in the true sense of the word, in that its unable to convert full textual address, I think its more of a coordinate converter that happens to perform some basic geocoding function. Currently can handle GB Grid References, Worldwide Lat/Long, US Zipcodes, and UK Postcodes. The postcodes are also useable in reverse geocoding fashion in that you can lookup the nearest postcode to a location. Try out these conversions online in the online coordinate converter

Support nearby.org.uk and help keep it free!

Evolution 1.0 30/04/2010* (c) Barry Hunter
* Added FULL UK postcode support!

Getting an API key
At this stage a key is required to be able trace use of the service.

Signup for a API key HERE
I quite happy for this to be used in non profit applications.

If you wish to use this in a commercial application, then bear in mind I can offer no guarantees about availability.
If however there is interest I will consider creating a commercial version, (maybe even with full postcodes).

Even if you are only interesting in Sector Postcodes, then please Signup to download a CSV with to lat/long only and/or contact me to get various formats of the sector postcodes dumps, as that would probably be less resource hungary than quering a webservice.

Full Unit Postcodes can be obtained direct from OS Code-Point Open

Similarlly if only interested in the Lat/Long to/from Grid Refernce (or other coordinate conversions) as can probably supply source code for php/perl. (but first see the Downloads page)

Interface

Pseudo REST

Connect to the following URL:

http://www.nearby.org.uk/api/convert.php

With the following GET parameters: Items in with this background might not be fully working yet!

Name Purpose Example
key You unique API key [insert-key-here] a4fe23c9d8ce
p coordinate you want to convert! - should be url encoded (ie spaces as + or %20) etc sh434678
in (optional) the type of coordinate, see list below. If you supply this then a conversion to this type is tried first, otherwise will try the auto list. Useful if your coordinate could be ambigious! gr-osgb36
want (optional) seperated list of coordinates you want, as many as possible will be supplied. If missing will supply the most common. special value of all can be used to get all possible. gr-osgb36,en-osgb36
need (optional) coordinate type required. If this one can be provided ONLY this will be returned, otherwise will return as many of the 'want' as possible. ll-wgs84
output (optional) the output format, see list below, defaults to plain text format. text

SOAP

Using nusoap lib have started creating a SOAP server version of the service.

http://www.nearby.org.uk/api/convert-soap.php

This can be considered highly experiemental, click the above link for the WSDL definition. Input parameters are the same as the REST interface. The output is also the same with the relevent text/xml being output in the 'return' perameter, however only the use of text (the default) is recommended. You can test out the servicce here using soapclient.com.

Coordinate Formats

Items in Gray are being developed as you read this!

type-datum example input example output converts to
British National Grid (datum: OSGB36)
gr-osgb36 SH 123678
(spaces are ignored - any length accepted)
<gr datum="osgb36" gr="SH5456" digits="4" />
(returns longest needed to specify the location)
en-osgb36/
postcode-uk
gr10-osgb36 ---- unused (defaults to gr-osgb36) ---- <gr10 datum="osgb36" gr10="TQ 38663 38424" /> (output only)
en-osgb36 435657,654657 <en datum="osgb36" e="254000" n="356000" /> gr-osgb36/
ll-wgs84
Longitude and Latitude (datum: WGS84)
ll-wgs84 51.1307,-0.01584
(decimal degrees ONLY)
<ll datum="wgs84" lat="53.0812" long="-4.1811" /> en-osgb36/
en-irish/
postcode-us/
utm-wgs84
Gazetteer Info (datum: none)
gaz-na ---unimplemented--- <gaz country="United Kingdom" />
<gaz country="United States" city="Portsmouth" state="NH" />
<gaz country="United Kingdom" postcode_area="Redhill" />
(output only)
Determined in various ways the county is ofen very approximate!
Irish Grid (datum: Irish65)
gr-irish G5468
(spaces are ignored - any length accepted)
<gr datum="irish" gr="G5456" digits="4" />
(returns longest needed to specify the location)
en-irish
gr10-irish ---- unused (defaults to gr-irish) ---- <gr10 datum="irish" gr10="S 38663 38424" /> (output only)
en-irish 435657,654657 OSI <en datum="irish" e="254000" n="356000" /> gr-irish/
ll-wgs84
UTM (datum: wgs84)
utm-wgs84 12E 456463.99 3335334.04 <utm datum="wgs84" e="456463.99047613" n="3335334.0478552" lngZone="12" latZone="E" string="12E 456463 3335334" /> ll-wgs84
UK Postcode
postcode-uk RH19 1DZ
ONLY Sector data is read (ie last two chars are ignored)
<postcode datum="uk" postcode="LL27 0" level="Sector" distance="8.4969" bearing="71.251589732408" heading="east-northeast" /> en-osgb36
NEW! use http://api1.nearby.org.uk/api/convert.php to get full unit postcodes (uses the last two digit of the postcode too!)


Contains Royal Mail data © Royal mail copyright and database right 2010. Powered by OS Code-Point Open

(Otherwise the API is unchanged, it just supports the better postcodes database - on a different domain so as not to break existing scripts using the normal url)

· Of course supports both forward and reverse geocoding!
postcode-uk RH19 1DZ <postcode datum="uk" postcode="RH19 1DZ" level="Unit" distance="8.4969" bearing="71.251589732408" heading="east-northeast" /> en-osgb36
US Zipcode
postcode-us 54456 <postcode datum="us" postcode="4013" distance="0.00794" /> ll-wgs84
IARU Locator, Maidenhead Locator System or QTH locator system (datum: WGS84)
iaru-wgs84 IO82AX
REQUIRES: &in=iaru-wgs84
<iaru datum="wgs84" locator="IO82AX" /> ll-wgs84
GeoHash
geohash-wgs84 u1031d9p
REQUIRES: &in=geohash-wgs84
<geohash datum="wgs84" geohash="u1031d9p"/> ll-wgs84
type-datum example input example output converts to
Special Convertions (exceptions to rules above!)
postcode-uk RH19 1DZ
USE: &want=iaru-wgs84
<iaru datum="wgs84" locator="IO82AX" /> iaru-wgs84

nearby.org.uk also has the capalibility to provide information in the following formats, which shows the geek in me! I'll consider adding adding any of these to the geocoder on request.

Coordinates

  • Other formats for lat/long eg DMS or Degrees and Decimal Minues)
  • OSGB36 lat/long
  • Irish lat/long
  • ETRS89 lat/long
    (basically wgs84 but much more accuate than OSGB<=>WGS84 conversion, cm(!?!) accuracy instead of 7m which I have now)
  • Map Tile Reference
  • NAC - Universal Address
  • UTM
  • XYZ
  • IARU Locator
  • Approx <=> Lat/Long

Links

  • Could also return a link direct to a given map/location search/info site. (basically any page linked from here)

Datasets

  • Germany Zip Codes
  • British Isles Placenames (Geographic Names Data Base, OS 50k Gazetteer and others)
  • UK Std Telephone Codes Areas
  • UK Pre 1974 Counties (which county is the point in)
  • UK Post 1974 Counties (which county is the point in)
  • UK Landranger (center of a given map, or which maps a point is on)
  • UK Explorer (center of a given map, or which maps a point is on)
  • Ireland Discover(y) (center of a given map, or which maps a point is on)
  • GB Railway Station (nearest, or location of given station)
  • - GB Nearest feature in the Location Search - plus a few more not visible there ;-)
    • Motorway Junctions (nearest, or location of given junction)
  • - plus a few others where I have the data, but haven't began to process yet!
    • Height above sea level
    • Classification (% of woodland/beach/roads/built up etc in 1km gridsquare)
    • Distance to coastline, nearest road/moterway, railway, major river etc (see this map)

Output Formats

name Example
http://www.nearby.org.uk/api/convert.php?key=insert-key-here&p=rh161dt&output=text
text
en,osgb36,538930,138706
gr10,osgb36,TQ 38930 38706
gr,osgb36,TQ3893038706,10
ll,wgs84,51.130787637252,-0.015848681521876

TIP, first break on newlines "\n", then break on commas
To make it easier to understand laid out as a table: (compare with the XML version to see the 'titles' of each field - each coordinate type has fixed fields)
type datum values
en osgb36 538930 138706
gr10 osgb36 TQ 38930 38706  
gr osgb36 TQ3893038706 10
ll wgs84 51.13079 -0.01585
php example rough demo:
<?php
$input = "rh161dt";
$key = "insert-key-here";
$data = file_get_contents("http://www.nearby.org.uk/api/convert.php?key=$key&p=$input&output=text&want=ll-wgs84");

$lines = explode("\n",$data); //becuase there can be multiple lines...
$data = explode(',',$lines[0]);

print "lat = ".floatval($data[2])."<br/>";
print "long = ".floatval($data[3])."<br/>";
?>
http://www.nearby.org.uk/api/convert.php?key=insert-key-here&p=rh161dt&output=sxml
sxml <?xml version="1.0" encoding="UTF-8"?>
<convert>
 <input>
  <postcode datum="uk" postcode="RH19 1DZ" level="Unit"/>
 </input>
 <output>
  <en datum="osgb36" e="538930" n="138706"/>
  <gr10 datum="osgb36" gr10="TQ 38930 38706"/>
  <gr datum="osgb36" gr="TQ3893038706" digits="10"/>
  <ll datum="wgs84" lat="51.130787637252" long="-0.015848681521876"/>
 </output>
</convert>
Auto Generated XML Schema: convert.xsd and convert.dtd
utility at: http://www.hitsw.com/xml_utilites/


Other Webservices that might be useful:

Tags: geocode, geocoding, postcode, api, uk, webservice, geocoder, gps, lat, mapping, maps, web, zipcode


Further Questions? Contact Me

- Home - Blog - Location Links - Location Search - Search Gateway - Gazetteer - Location Search Index - API -
/nearby.org.uk © 2005-2010 [disclaimer] developed by trigtools.co.uk BackToTop