API Resources
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:
[ { "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 ]
[]
{ "message": "Limit Exceeded" }
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:
[ { "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 ]
[]
{ "message": "Limit Exceeded" }
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:
{ "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" }
{}
{ "message": "Limit Exceeded" }
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:
|
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.