API

Requests

Please be kind to our server and cache your results. You can obtain geographical information relating to a UK postcode in XML format by accessing the following URL:

http://geopostcode.org.uk/api/{postcode}  

Where {postcode} is a UK postcode or partial postcode. Spaces can be url encoded (ie as '+' or '%20'). For full postcodes spaces can be omitted altogether, but this is not recommended for partial postcodes as it can be ambiguous.

To obtain the data in JSON format, add the file extension '.json'. For example:

http://geopostcode.org.uk/api/SW1A+1AA.json  

The default behaviour if an exact match is not found for the requested postcode is to check increasingly large units until a match is found. For example, if you search on LS20 6JB, if no match is found for that full postcode, a check will be made for the sector, LS20 6. If that doesn't match, the district is tried, LS20. If that too fails a check is made on the area, LS.

If you want an exact match only, you can access the following URL:

http://geopostcode.org.uk/api/exact/{postcode}  

Results

If the postcode is found the server will respond with a 200 OK response code and will send XML or JSON structured as shown in the XML example below.

<postcode>
  <code></code>
  <osgb36>
    <east></east>
    <north></north>
  </osgb36>
  <osie>
    <east></east>
    <north></north>
  </osie>
  <wgs84>
    <lat></lat>
    <lon></lon>
  </wgs84>
  <meta>
    <sourcecode></sourcecode>
    <sourcename></sourcename>
    <licence>
      <type></type>
      <uri></uri>
      <attribution></attribution>
    </licence>
    <quality></quality>
  </meta>
</postcode>

If the postcode can not be found the server will return a 404 response code.

The value of 'code' is the postcode actually matched, not the search criteria sent. Geographic information is returned in up to three formats: 'osgb36' contains the British national grid data; 'osie' the Irish national grid data (only returned for postcodes in Northern Ireland); and 'wgs84' contains the latitude and longitude.

The 'meta' sections contains details of the source of the record and the licence under which it is distributed. You should pay careful attention to the licence details. Our data comes from multiple sources, some of them more open than others. Read more on licencing

Caching data

Please be kind to the server and cache any data your retrieve. The data is updated infrequently—once every three months for England, Scotland and Wales and less frequently elsewhere. We suggest you cache data for at least a week.