Address Autocomplete


version 2

API Details:
URL: https://api.addressian.co.uk/v2/autocomplete/{search_query}
Request header: {x-api-key: "YOUR API KEY"}
Response type: application/json
Notes:

We have added extra "class", "company", "buildingname" and "street" fields in the response. Also renamed "citytown" to "city".

We have taken company name from the first line of the address, and assigned it to "company".

Responses:
Code
Body
200 - Successful. An array of top 20 matching addresses.
[
  {
    "address": [
      "2 Fiona Walk"
    ],
    "county": "Merseyside",
    "postcode": "L10 4YW",
    "city": "Liverpool",
    "street": "Fiona Walk",
    "class": "residential",
    "buildingnumber": "2"
  },
  {
    "address": [
      "Yellow Tower",
      "Ffordd Amazon",
      "Crymlyn Burrows"
    ],
    "postcode": "SA1 8QR",
    "city": "Swansea",
    "company": "Amazon",
    "street": "Ffordd Amazon",
    "class": "commercial",
    "buildingname": "Yellow Tower"
  },
  {
    "address": [
      "Amazon Way",
      "Dunfermline East Business Parks"
    ],
    "postcode": "KY11 8ST",
    "city": "Dunfermline",
    "company": "Amazon Returns",
    "street": "Amazon Way",
    "class": "commercial"
  },

  ...more results
]
200 - Successful. If the API cannot find any matching address, it returns an empty array. 
[]
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 your subscription.
no body
429 - API quota reached. 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. 
{
    "message": "Limit Exceeded"
}
500 – Internal server error. If anything goes wrong at 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.
no body
Field definitions:
Field Description
address A JSON array of address lines where the lines are in order. For example address[0] corresponds to line 1, address[1] line 2 and so on. Company name is not one of the address lines and should be taken from "company" (if exists). This field is always returned in the response.
postcode The UK postcode associated with this address. It comes in upper-case, and always formatted as on the Royal Mail database. This field is always returned in the response.
city The city or town of this address. This field is present in most results.
county The county associated with this address. In some results, this field is not returned.
street The street name of the address. This field, if exists, is already a part of the "address" array. This field is present in most results.
class Classification of the address. Two possible values are "residential" and "commercial". This field is always returned in the response.
company If here is a company name on file, it will be returned in the response. This filed is not a part of the "address" array.
buildingname The building name of the address. This field is present in most results.
Example:
  • GET /v2/autocomplete/flat 19 ox12
    (returns a limited list of matching addresses)
  • GET /v2/autocomplete/SW1A 2AA
    (detects this as a postcode and returns all addresses associated with this postcode)

version 1

API Details:
URL: https://api.addressian.co.uk/v1/autocomplete/{search_query}
Request header: {x-api-key: "YOUR API KEY"}
Response type: application/json
Notes:

First release of the autocomplete API. It is designed to be very simple and should cover most use-cases. The response from this api, at max, has 4 fields.

Responses:
Code
Body
200 - Successful. An array of top 20 matching addresses.
[
  {
    "address": [
      "1 Wesley Court",
      "Wesley Close"
    ],
    "county": "Devon",
    "postcode": "TQ2 8RA",
    "citytown": "Torquay"
  },
  {
    "address": [
      "2 Wesley Court",
      "Wesley Close"
    ],
    "county": "Devon",
    "postcode": "TQ2 8RA",
    "citytown": "Torquay"
  },
  {
    "address": [
      "4 Wesley Court",
      "Wesley Close"
    ],
    "county": "Devon",
    "postcode": "TQ2 8RA",
    "citytown": "Torquay"
  },
  {
    "address": [
      "3 Wesley Court",
      "Wesley Close"
    ],
    "county": "Devon",
    "postcode": "TQ2 8RA",
    "citytown": "Torquay"
  },

  ...more results
]
200 - Successful. If the API cannot find any matching address, it returns an empty array. 
[]
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 your subscription.
no body
429 - API quota reached. 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. 
{
    "message": "Limit Exceeded"
}
500 – Internal server error. If anything goes wrong at 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.
no body
Field definitions:
Field Description
address A JSON array of address lines where the lines are in order. For example address[0] corresponds to line 1, address[1] line 2 and so on. Company name, if the address is registered with a company name, is returned in the first item of the address array (i.e. address[0]). This field is always returned in the response.
postcode The UK postcode associated with this address. It comes in upper-case, and always formatted as on the Royal Mail database. This field is always returned in the response.
citytown The city or town of this address. This field is present in most results.
county The county associated with this address. In some results, this field is not returned.
Example:
  • GET /v1/autocomplete/flat 19 ox12
    (returns a limited list of matching addresses)
  • GET /v1/autocomplete/SW1A 2AA
    (detects this as a postcode and returns all addresses associated with this postcode)

Postcode Details


version 1

API Details:
URL: https://api.addressian.co.uk/v1/postcode/{search_query}
Request header: {x-api-key: "YOUR API KEY"}
Response type: application/json
Responses:
Code
Body
200 - Successful. A JSON object containing simple key values
{
  "postcode": "M20 3EQ",
  "isInUse": true,
  "latitude": 53.436989,
  "longitude": -2.227906,
  "easting": 384957,
  "northing": 393381,
  "gridRef": "SJ849933",
  "gridRefQuality": 1,
  "county": "Greater Manchester",
  "district": "Manchester",
  "ward": "Old Moat",
  "districtCode": "E08000003",
  "wardCode": "E05011375",
  "country": "England",
  "countyCode": "E11000010",
  "constituency": "Manchester, Withington",
  "constituencyCode": "E14000809",
  "creationDate": "1994-05-01",
  "parish": "Manchester, unparished area",
  "parishCode": "E43000157",
  "population": 42,
  "households": 10,
  "builtUpArea": "Greater Manchester",
  "builtUpSubDivision": "Manchester",
  "lsoa": "Manchester 035C",
  "lsoaCode": "E01005273",
  "msoa": "Manchester 035",
  "msoaCode": "E02001079",
  "ruralUrban": "Urban major conurbation",
  "region": "North West",
  "altitudeInMeters": 39,
  "censusOutputAreaCode": "E00026734",
  "indexOfMultipleDeprivation": 7500,
  "receivesManyOrFewMailsPerDay": "few",
  "nearestStation": "Mauldeth Road",
  "distance_to_station": 1.30968,
  "postcodeArea": "M",
  "postcodeDistrict": "M20",
  "policeForce": "Greater Manchester",
  "waterSupplier": "United Utilities"
}
200 - Successful. If the API cannot find any matching postcode, it returns an empty object. 
{}
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 your subscription.
no body
429 - API quota reached. 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. 
{
    "message": "Limit Exceeded"
}
500 – Internal server error. If anything goes wrong at 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.
no body
Field definitions:
Field Description
postcode The UK postcode associated with this address. It comes in upper-case, and always formatted as on the Royal Mail database.
isInUse true/false flag to indicate that this Postcode is currently in use. Refer to columns [creationDate] and [terminationDate] for further information.
latitude Latitude of centroid of the Postcode for this row in decimal format i.e. 51.50205.
longitude Longditude of centroid of the Postcode for this row in decimal format. i.e -0.07864. Negative values are those to the West of the zero (Greenwich) meridian.
easting Co-ordinate of the East-West plane on the British National Grid. Reference
northing Co-ordinate of the North-South plane on the British National Grid.
gridRef Ordnance Survey grid reference in format xxnnnnnn i.e. TQ365751. Reference
gridRefQuality A Data Quality Flag for this record. Values are as follows:
  1. within the building of the matched address closest to the postcode mean.
  2. as for status value 1, except by visual inspection of Landline maps (Scotland only).
  3. approximate to within 50 metres.
  4. postcode unit mean (mean of matched addresses with the same postcode, but not snapped to a building).
  5. imputed by ONS, by reference to surrounding postcode grid references.
  6. postcode sector mean, (mainly PO Boxes).
  7. deliberately left blank.
  8. postcode terminated prior to Gridlink initiative, last known ONS postcode grid reference.
  9. no grid reference available.
county Name of the Ceremonial County that this Postcode sits within. Some of these counties map directly to County Councils. Part of the hierarchy of: County->District->Ward.
district Name of the Local authority district (LAD)/unitary authority (UA)/ metropolitan district (MD)/ London borough (LB)/ council area (CA)/district council area (DCA) that this Postcode sits within. Part of the hierarchy of: County->District->Ward.
ward Name of the local authority Ward that this Postcode sits within. Part of the hierarchy of: County->District->Ward.
districtCode Code of the District that this Postcode sits within. Part of the hierarchy of: County->District->Ward.
wardCode Code of the Ward that this Postcode sits within. Part of the hierarchy of: County->District->Ward.
country Name of the Country that this Postcode sits within. Values are: England, Scotland, Wales, Northern Ireland.
countyCode Code of the County that this Postcode sits within. Part of the hierarchy of: County->District->Ward.
constituency Name of the Paliamentary Constituency that this Postcode sits within.
constituencyCode Code of the Paliamentary Constituency that this Postcode sits within. e.g. E14000789.
creationDate Date that this Postcode was introduced.
terminationDate Date that this Postcode was withdrawn from use.
parish Name of the Parish this this Postcode sits within. n.b Not all areas are designated a Parish.
parishCode Code of the Parish that this Postcode sits within. n.b Not all areas are designated a Parish. e.g. E43000213.
nationalPark Name of the National Park that this Postcode sits within, where applicable.
population Population of the area covered by the Postcode (from the 2011 census).
households Number of Households in the area covered by the Postcode (from the 2011 census).
builtUpArea Name of the built-up area this postcode is part of.
builtUpSubDivision Name of the built-up area sub-division this postcode is part of.
lsoa Name of the Lower Layer Super Output Area (LSOA) that this Postcode sits within. Refer to: [lsoaCode].
lsoaCode Code for the Lower Layer Super Output Area (LSOA) that this Postcode sits within. Reference
msoa Name of the Middle Layer Super Output Area (MSOA) that this Postcode sits within. Refer to: [msoaCode].
msoaCode Code for the Middle Layer Super Output Area (MSOA) that this Postcode sits within. Reference
ruralUrban Description of the area covered by the Postcode i.e. Urban major conurbation, Remote small town, Urban city and town etc.
region Broad region of the UK i.e. London, South West, West Midlands, Yorkshire and The Humber etc.
altitudeInMeters Height above sea level measured in Metres.
londonZone Transport for London (TfL) Travel Zone indicator (London area only).
localAuthority County Council area that this Postcode sits within. For Unitary Authorties, London etc this value will not be populated. Reference
censusOutputAreaCode Code for the Census Output Area e.g. E00016581.
indexOfMultipleDeprivation The deprivation rank for the postcode, where 1 is the most deprived. The range of values is as follows:
1 - 32844 = England
1 - 1909 = Wales
1 - 6976 = Scotland
1 - 890 = Northern Ireland
receivesManyOrFewMailsPerDay Shows whether the postcode is a small or large mail user. Possible values are "few" for less than 25 mail per day, and "many" for more than 25.
nearestStation The nearest train station to the postcode. For London, also includes Underground and tram stops.
distance_to_station The distance in kilometres to the nearest station from the postcode.
postcodeArea The area of the postcode (e.g. KT).
postcodeDistrict The district of the the postcode (e.g. KT1).
policeForce The name of the police force responsible for this postcode.
waterSupplier The name of the water company responsible for this postcode.

Billing

We bill your account on every request you send to us.

If you are implementing an address autocomplete in your website/service, be sure to use cooling-off strategies, so your code doesn't make a request on every keypress. All Javascript autocomplete libraries have this feature as "delay". This way the autocomplete field will wait a short amount of time (500 milliseconds for example) before sending the request.
This will ensure your request quota is not drained quickly, while providing no benefit to the end user.