Find

Returns all addresses for a UK postcode.

GET https://api.getAddress.io/find/{postcode}?api-key={api-key}

GET https://api.getAddress.io/find/{postcode}/{house name or number}?api-key={api-key}

Optional Parameters

Property	Description	Type
format	Formats the addresses as an arrays.	true/false
sort	Numerically sorts the addresses.	true/false
expand	Expands addresses in to individual named components, such as building number and thoroughfare.	true/false
fuzzy	Searches for the address with fuzzy logic, including synonyms, partial words and acronyms.	true/false

Examples

Request

GET https://api.getAddress.io/find/nn13er?api-key={api-key}

Response 200

{
    "latitude": 52.24593734741211,
    "longitude": -0.891636312007904,
    "addresses":
    [
    "10 Watkin Terrace, , , , , Northampton, Northamptonshire",
    "12 Watkin Terrace, , , , , Northampton, Northamptonshire",
    "14 Watkin Terrace, , , , , Northampton, Northamptonshire",
    "16 Watkin Terrace, , , , , Northampton, Northamptonshire",
    "18 Watkin Terrace, , , , , Northampton, Northamptonshire",
    "2 Watkin Terrace, , , , , Northampton, Northamptonshire",
    "20 Watkin Terrace, , , , , Northampton, Northamptonshire",
    "22 Watkin Terrace, , , , , Northampton, Northamptonshire",
    "24 Watkin Terrace, , , , , Northampton, Northamptonshire",
    "26 Watkin Terrace, , , , , Northampton, Northamptonshire",
    "26a Watkin Terrace, , , , , Northampton, Northamptonshire",
    "26b Watkin Terrace, , , , , Northampton, Northamptonshire",
    "26c Watkin Terrace, , , , , Northampton, Northamptonshire",
    "26d Watkin Terrace, , , , , Northampton, Northamptonshire",
    "28 Watkin Terrace, , , , , Northampton, Northamptonshire",
    "2a Watkin Terrace, , , , , Northampton, Northamptonshire",
    "30 Watkin Terrace, , , , , Northampton, Northamptonshire",
    "32 Watkin Terrace, , , , , Northampton, Northamptonshire",
    "36 Watkin Terrace, , , , , Northampton, Northamptonshire",
    "38 Watkin Terrace, , , , , Northampton, Northamptonshire",
    "4 Watkin Terrace, , , , , Northampton, Northamptonshire",
    "40 Watkin Terrace, , , , , Northampton, Northamptonshire",
    "40b Watkin Terrace, , , , , Northampton, Northamptonshire",
    "42 Watkin Terrace, , , , , Northampton, Northamptonshire",
    "44 Watkin Terrace, , , , , Northampton, Northamptonshire",
    "46 Watkin Terrace, , , , , Northampton, Northamptonshire",
    "48 Watkin Terrace, , , , , Northampton, Northamptonshire",
    "50 Watkin Terrace, , , , , Northampton, Northamptonshire",
    "8 Watkin Terrace, , , , , Northampton, Northamptonshire",
    "Flat 1, 6 Watkin Terrace, , , , Northampton, Northamptonshire",
    "Flat 1, Watkin Court, Watkin Terrace, , , Northampton, Northamptonshire",
    "Flat 2, 6 Watkin Terrace, , , , Northampton, Northamptonshire",
    "Flat 2, Watkin Court, Watkin Terrace, , , Northampton, Northamptonshire",
    "Flat 3, 6 Watkin Terrace, , , , Northampton, Northamptonshire",
    "Flat 3, Watkin Court, Watkin Terrace, , , Northampton, Northamptonshire",
    "Flat 4, 6 Watkin Terrace, , , , Northampton, Northamptonshire",
    "Flat 4, Watkin Court, Watkin Terrace, , , Northampton, Northamptonshire",
    "Flat 5, Watkin Court, Watkin Terrace, , , Northampton, Northamptonshire",
    "Flat 6, Watkin Court, Watkin Terrace, , , Northampton, Northamptonshire",
    "Flat 7, Watkin Court, Watkin Terrace, , , Northampton, Northamptonshire",
    "Flat 8, Watkin Court, Watkin Terrace, , , Northampton, Northamptonshire",
    "Flat 9, Watkin Court, Watkin Terrace, , , Northampton, Northamptonshire"
    ]
}

Request with expand=true

GET https://api.getAddress.io/find/nn13er/10?api-key={api-key}&expand=true

Response 200

{
    "postcode": "NN1 3ER",
    "latitude": 52.24593734741211,
    "longitude": -0.891636312007904,
    "addresses":
    [
    {
    "formatted_address": [
        "10 Watkin Terrace",
        "",
        "",
        "Northampton",
        "Northamptonshire"
     ],
        "thoroughfare":  "Watkin Terrace",
        "building_name":  "",
        "sub_building_name":  "",
        "sub_building_number":  "",
        "building_number":  "10",
        "line_1":  "10 Watkin Terrace",
        "line_2":  "",
        "line_3":  "",
        "line_4":  "",
        "locality":  "",
        "town_or_city":  "Northampton",
        "county":  "Northamptonshire",
        "district":  "Northampton",
        "country":  "England"
    }
    ]
}

Testing

These postcodes yield both successful and unsuccessful responses to your request.

XX2 00X or TR19 7AA or KW1 4YT Returns a 'successful' response 200. Your request was successful.
XX4 00X Returns 'bad request' response400. Your postcode is not valid.
XX4 01X Returns 'unauthorized' response 401. Your api-key is not valid.
XX4 03X Returns 'forbidden' response 403. Your api-key is valid but you do not have permission to access to the resource.
XX4 29X Returns 'too many requests' response 429. You have made more requests than your allowed limit.
XX5 00X Returns 'server error' response 500. Server error, you should never see this.

Request made with these postcodes will not affect your usage.

(See: List of HTTP status codes for more details on HTTP status codes.)