Location

The Location API suggests locations for a given term.

Step 1.

Request

GET POST https://api.getAddress.io/location/{term}?api-key={api-key} 

Response

{
    "suggestions": 
    [
        {
            "location": "Northallerton, North Yorkshire",
            "url": "/get-location/NDg5YmQ5NzY5Zjk0YmI5IDUxMTQ3MTI1",
            "id": "NDg5YmQ5NzY5Zjk0YmI5IDUxMTQ3MTI1"
        },
        {
            "location": "North Otterington, Northallerton, North Yorkshire",
            "url": "/get-location/MDZlNWYxYTUyMDA0NDUyIDUxMDY1ODM0",
            "id": "MDZlNWYxYTUyMDA0NDUyIDUxMDY1ODM0"
        },
        {
            "location": "North Cowton, Northallerton, North Yorkshire",
            "url": "/get-location/ZDNhNGJhMmY5YjU0ZWRlIDUxMTQ2ODU2",
            "id": "ZDNhNGJhMmY5YjU0ZWRlIDUxMTQ2ODU2"
        },
        {
            "location": "Appleton Wiske, Northallerton, North Yorkshire",
            "url": "/get-location/NWRmYWUxMWY2N2E0NGQyIDUxMDM5NDcx",
            "id": "NWRmYWUxMWY2N2E0NGQyIDUxMDM5NDcx"
        },
        {
            "location": "Little Smeaton, Northallerton, North Yorkshire",
            "url": "/get-location/ZGQyYTFjMGI0YTkzZjRjIDUxMTE5NDg3",
            "id": "ZGQyYTFjMGI0YTkzZjRjIDUxMTE5NDg3"
        }
    ]
}

Step 2.

The selected 'Id' is passed to the 'Get-Location' API to return the full location details.

Request

GET https://api.getAddress.io/get-location/{id}?api-key={api-key}  

Response

{
    "latitude": 51.6086605,
    "longitude": 0.21630145,
    "area":  "Havering",
    "town_or_city":  "Romford",
    "county":  "Essex",
    "country":  "England",
    "postcode": "RM3 7XL",
    "outcode": "RM3"
}

Filter

A filter limits results to specific criteria.

Request

{
    "filter":
    {
        "county":"{county name}",
        "country":"{country name}",
        "area":"{area}",
        "town_or_city":"{town or city name}",
        "postcode":"{postcode}",
        "outcode":"{outcode}",
        "radius":{
            "km":"{max distance from lat/long in kilometres}",
            "longitude":{longitude},
            "latitude":{latitude}
        }
    }
}

Example

Filtering 'town_or_city' to 'London' will only return addresses in London

Request

{
    "filter":
    {
        "town_or_city":"London",
    }
}

Location

Instructs the service to prefer suggestions closer to the specified location.

Request

{
    "location":
    {
        "latitude":{latitude},
        "longitude":{longitude}
    }
}

Other Parameters

Rate Limiting

Your subscription will limit the number of requests per 5 minute span. Exceeding your plan's rate limit will return a HTTP 429 response.
The Retry-After HTTP header contains the number of seconds until a successful retry can be made.