Documentation

API call requests are designed lightweight. All that is needed is a URI with search query, along with an authentication header to successfully receive a response.

Address Finder API

Address finder API takes any query, and searches through 32 million UK addresses. It automatically detects if the query is in fact a full postcode. If it is, it returns all addresses associated with that postcode. If it’s an ordinary address, the system returns a limited list of matching addresses.

  • Version: 1.0
  • URI: https://api-trial.addressian.co.uk/address/{search_query}
  • Protocol: https
  • Responds With: application/json
  • Request Header: x-api-key
[
  {
   "address": [
     "Flat 2",
     "Wesley Court",
     "2 Beckwith Road"
   ],
    "county": "Greater London",
    "postcode": "SE24 9LJ",
    "citytown": "London"
  },
  {
   "address": [
     "Flat 7",
     "Wesley Court",
     "2 Beckwith Road"
   ],
    "county": "Greater London",
    "postcode": "SE24 9LJ",
    "citytown": "London"
  }
  ...
 ]

Note that the API is smart in distinguishing between a postcode and a partially entered address. This means that it is up to you, how to present it on your website.

For example:

  • /address/flat 19 ox12 (returns a limited list of matching addresses)
  • /address/SW1A 2AA (detects this as a postcode and returns all addresses associated with this postcode)

What if the query doesn’t return any address?

An empty JSON array will be returned:[]

Get Postcode Details API

This API takes a postcode as input, and returns a big chunk of data back, about the postcode. We have selected the most useful the data to return, while keeping the response as lightweight as possible.

  • Version: 1.0
  • URI: https://api-trial.addressian.co.uk/postcode/{postcode}
  • Protocol: https
  • Responds With: application/json
  • Request Header: x-api-key
{
  "country": "England",
  "waterSupplier": "United Utilities",
  "districtCode": "E08000003",
  "altitudeInMeters": 39,
  "indexOfMultipleDeprivation": 11449,
  "latitude": 53.436989,
  "county": "Greater Manchester",
  "receivesManyOrFewMailsPerDay": "few",
  "ward": "Old Moat",
  "msoa": "Manchester 035",
  "northing": 393381,
  "gridRef": "SJ849933",
  "builtUpSubDivision": "Manchester",
  "parishCode": "E43000157",
  "ruralUrban": "Urban major conurbation",
  "parish": "Manchester, unparished area",
  "constituencyCode": "E14000809",
  "wardCode": "E05011375",
  "gridRefQuality": 1,
  "censusOutputAreaCode": "E00026734",
  "longitude": -2.227906,
  "easting": 384957,
  "postcodeArea": "M",
  "postcode": "M20 3EQ",
  "msoaCode": "E02001079",
  "lsoaCode": "E01005273",
  "households": 10,
  "lsoa": "Manchester 035C",
  "creationDate": "1994-05-01",
  "population": 42,
  "postcodeDistrict": "M20",
  "distance_to_station": 1.30968,
  "countyCode": "E11000010",
  "builtUpArea": "Greater Manchester",
  "constituency": "Manchester, Withington",
  "district": "Manchester",
  "isInUse": true,
  "region": "North West",
  "policeForce": "Greater Manchester",
  "nearestStation": "Mauldeth Road"
}

What if the system doesn’t find the postcode at all?

An empty JSON object will be returned:{}

Common HTTP error codes returned

There are not many scenarios where an error is returned. It it does, it usually revolves around a token that is not provided or when API quota limited is reached:

403 – Forbidden

Check that you are providing the x-api-key header and the value is correct (taken from your account). Also make sure the key is not expired. Our keys never expire, unless if you cancel you subscription.

429 – Quota Exceeded

Check that your allowance hasn’t been exhausted. If you need more API calls per month, consider buying a bigger plan. If your needs are even more than our highest plan, simply contact us for a personalised quote.

500 – Internal server error

If anything goes wrong in our end, we will return this code. This should never happen in theory, but good to implement a mechanism against it in your code, such as a retry.