Documentation

EasyPostcodes is a web-based address lookup API for retrieving the list of addresses for any given UK postcode. The database is based on the Royal Mail PAF file.

How it works.

All you need is your API Key which can be obtained by creating a trial account. You will not need your credit card for that. With your trial account you get a bundle of 100 requests for you to use for testing during the integration stage.

Once you have your trial account, just log into the portal and navigate to your keys from the menu on the left. Use one in your production environment and the other for development. At any point you can rotate the keys in accordance to your requirements.

Below you will see code examples to aid you with development. We have intentionally tried to keep it very simple. However, if you still find that you need to talk to us, then we would love to hear from you. The email address to use is dev@poolesoftware.com

Making a request.

Making a request is simple. You can use any technology stack you like which can make web requests. Here we will look at two examples, one in C# .NET and the other in JavaScript.

C# .NET Example

                
                  private readonly 
                  IHttpClientFactory 
                  _httpClientFactory;
                
              

                
                  public async 
                  Task<IEnumerable<AddressModel>> 
                  GetPostcodeAddresses(string postcode)
                
              

                
                  {
                
              

                
                  var 
                  uri 
                  = 
                  new 
                  Uri
                  (
                  $"https://api.easypostcodes.com/addresses/{
                  postcode
                  }"
                  )
                  ;
                
              

                
                  var 
                  client 
                  = 
                  _httpClientFactory
                  .
                  CreateClient
                  (
                  )
                  ;
                
              

                
                  client
                  .
                  DefaultRequestHeaders
                  .
                  Add
                  (
                  "Key"
                  , 
                  "API_KEY_GOES_HERE"
                  )
                  ;
                
              

                
                  var 
                  response 
                  = 
                  await 
                  client
                  .
                  GetAsync
                  (
                  uri
                  )
                  ;
                
              

                
                  var 
                  responseBody 
                  = 
                  await 
                  response
                  .
                  Content
                  .
                  ReadAsStringAsync
                  (
                  )
                  ;
                
              

                
                  return 
                  JsonConvert
                  .
                  DeserializeObject
                  <
                  IEnumerable
                  <
                  AddressModel
                  >>
                  (
                  responseBody
                  )
                  ;
                
              

                
                  }
                
              

Of course you would want to enhance the above example further, by ensuring the response was successful before deserializing the addresses. Also, you may want to implement a retry mechanism just in case of network errors, and so on.

Another thing you could do here is to define Typed or Named HttpClients. Either way, ensure you do not add the 'Key' header multiple times, as it is easy to make that mistake here.

Finally, you will want to read the API Key and the Uri from a configuration setting somewhere as those can change over time.

JavaScript Example

                
                  function 
                  getAddresses
                  (
                  postcode
                  ) 
                  {
                
              

                
                  let 
                  xhr 
                  = 
                  new 
                  XMLHttpRequest
                  (
                  )
                  ;
                
              

                
                  xhr
                  .
                  open
                  (
                  'GET'
                  , 
                  `https://api.easypostcodes.com/addresses/"
                  ${
                  postcode
                  }
                  `
                  , 
                  false
                  )
                  ;
                
              

                
                  xhr
                  .
                  setRequestHeader
                  (
                  'Key'
                  , 
                  'API_KEY_GOES_HERE'
                  )
                  ;
                
              

                
                  xhr
                  .
                  send
                  (
                  null
                  )
                  ;
                
              

                
                  return 
                  xhr
                  .
                  responseText
                  ;
                
              

                
                  }
                
              

This is a very simple pure JavaScript example, but you can use axios or jQuery, or whatever other JS framework that you like. One word of warning with client-side JS frameworks is the challenge of hiding the key. Some would say, it is better to keep the key at server side, otherwise your key could be compromised.

Handling the result.

Upon a successful request, you will get back an array of addresses that pertain to the given postcode used in the request. Below is the Address Model.

[
{

                  buildingName
                  : ""
                  ,
                
                  buildingNumber
                  : "169"
                  ,
                
                  departmentName
                  : ""
                  ,
                
                  dependentLocality
                  : ""
                  ,
                
                  dependentThoroughfareAndDescriptor
                  : ""
                  ,
                
                  doubleDependentLocality
                  : ""
                  ,
                
                  organisationName
                  : ""
                  ,
                
                  poBox
                  : ""
                  ,
                
                  postCode
                  : "AB10 1AU"
                  ,
                
                  postTown
                  : "ABERDEEN"
                  ,
                
                  subBuildingName
                  : "Flat 99"
                  ,
                
                  thoroughfareAndDescriptor
                  : "Netherkirkgate"
                  ,
                
                  northing
                  : "806323"
                  ,
                
                  easting
                  : "394271"
                  ,
                
                  latitude
                  : "57.147740"
                  ,
                
                  longitude
                  : "-2.096323"
                  ,
                
                  envelopeAddress
                  : {
                
                  organisation
                  : ""
                  ,
                
                  addressLine1
                  : "Flat 99, 169 Netherkirkgate"
                  ,
                
                  addressLine2
                  : ""
                  ,
                
                  town
                  : "ABERDEEN"
                  ,
                
                  postCode
                  : "AB10 1AU"
                  ,
                
                  summaryLine
                  : "Flat 99, 169 Netherkirkgate, ABERDEEN, AB10 1AU"
                  ,
                
                  }
                
                  }
                
                  ]

Please note that the geolocation information like the Northing, Easting, Latitude, and Longitude are not provided for the newest postcodes. This is on our features roadmap. For now the geolocation data is only for postcodes that the Ordnance Survey provides, which is about 99.97% coverage.

Final thoughts.

On this page we have only provided a couple of examples to get you going. If you find that the guide is not adequate or if you find mistakes in it, do let us know. We are here to help if you need us. We can even help you integrate EasyPostcodes into your application. Just let us know. We hope our address lookup API service will be to your satisfaction, but if it is not, then send us some feedback please.

We’d love to hear from you.