Documentation

Resources

Find

Postal addresses for single UK postcode.

Postcode to Addresses

GET https://api.getAddress.io/find/{postcode}

Returns a list of addresses for a postcode.

GET https://api.getAddress.io/find/{postcode}/{house}

Returns an address for a postcode and house name/number.

Query Parameters

Property Required Description Type
api-key Yes Your API key Text
format No Formats the addresses as an arrays. True/False
sort No Numerically sorts the addresses. 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"]
}

Response Format

The Addresses property contains an array of addresses representing every address in the postcode.

{
    "latitude": 52.24593734741211,
    "longitude": -0.891636312007904,
    "addresses":["Line1,Line2,Line3,Line4,Locality,Town/City,County"]
}

Testing

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

  • XX2 00X Returns a 'successful' response 200. Your request was successful.
  • XX4 04X Returns 'not found' error 404. No addresses could be found for this postcode.
  • XX4 00X Returns 'bad request' error 400. Your postcode is not valid.
  • XX4 01X Returns 'forbidden' error 401. Your api-key is not valid.
  • XX4 29x Returns 'too many requests' error 429. You have made more requests than your allowed limit.
  • XX5 00X Returns 'server error' error 500. Server error, you should never see this.

See: https://en.wikipedia.org/wiki/List_of_HTTP_status_codes for more details on HTTP status codes.

Usage

Try it

Your API usage and daily limits.

Daily Usage.

GET https://api.getAddress.io/v2/usage

Returns the current day's usage and usage limits.

GET https://api.getAddress.io/v2/usage/{day}/{month}/{year}

Returns the usage and limits for a given day, month and year.

Query Parameters

Property Required Description Type
api-key Yes Your administration API key Text

Examples

Request

GET https://api.getAddress.io/v2/usage?api-key={api-key}

Response 200

{
    "count": 99,
    "limit1": 2000
    "limit2": 3000
}

Private Address List

Try it

Add addresses directly to your returned results.

Add

Adds an address to your private address list.

POST https://api.getAddress.io/private-address/{postcode}
Content-Type: application/json

Query Parameters

Property Required Description Type
api-key Yes Your administration API key Text

Request Body

{
    "line1": "address line 1",
    "line2": "address line 2",
    "line3": "address line 3",
    "line4": "address line 4",
    "locality": "locality",
    "townOrCity": "town or city",
    "county": "county"
}

Response 200

{
    "message": "'postcode/id' has been added to your private address list.",
    "id": "zxy"
}

Remove

Removes an address from your private address list.

DELETE https://api.getAddress.io/private-address/{postcode}/{id}

Query Parameters

Property Required Description Type
api-key Yes Your administration API key Text

Response 200

{
    "message": "'{id}' has been removed from your private address list."
}

Get

Get an address from your private address list.

GET https://api.getAddress.io/private-address/{postcode}/{id}

Query Parameters

Property Required Description Type
api-key Yes Your administration API key Text

Response 200

{
    "id": "{id}",
    "line1": "address line 1",
    "line2": "address line 2",
    "line3": "address line 3",
    "line4": "address line 4",
    "locality": "locality",
    "townOrCity": "town or city",
    "county": "county"
}

List

Lists addresses from your private address list.

GET https://api.getAddress.io/private-address/{postcode}

Query Parameters

Property Required Description Type
api-key Yes Your administration API key Text

Response 200

[
{
    "id": "{id}",
    "line1": "address line 1",
    "line2": "address line 2",
    "line3": "address line 3",
    "line4": "address line 4",
    "locality": "locality",
    "townOrCity": "town or city",
    "county": "county"
},
{
    "id": "{id}",
    "line1": "address line 1",
    "line2": "address line 2",
    "line3": "address line 3",
    "line4": "address line 4",
    "locality": "locality",
    "townOrCity": "town or city",
    "county": "county"
}
]

Domain Whitelist

Try it

Restrict API calls to allowed domains.

Add

Adds domain to white list.

POST https://api.getAddress.io/security/domain-whitelist
Content-Type: application/json

Query Parameters

Property Required Description Type
api-key Yes Your administration API key Text

Request Body

{
    "name": "your-domain-name"
}

Response 200

{
    "message": "'your-domain-name' has been added to your domain whitelist.",
    "id": "zxy"
}

Remove

Removes a domain from your white list.

DELETE https://api.getAddress.io/security/domain-whitelist/{id}

Query Parameters

Property Required Description Type
api-key Yes Your administration API key Text

Response 200

{
    "message": "'your-domain-name' has been removed from your domain whitelist."
}

Get

Get a domain from your white list.

GET https://api.getAddress.io/security/domain-whitelist/{id}

Query Parameters

Property Required Description Type
api-key Yes Your administration API key Text

Response 200

{
    "id": "xyz",
    "name": "domain-name-1"
}

List

Lists all domains in your white list.

GET https://api.getAddress.io/security/domain-whitelist

Query Parameters

Property Required Description Type
api-key Yes Your administration API key Text

Response 200

[
    {"id": "zxf","name": "domain-1"},
    {"id": "abs","name": "domain-2"}
]

IP Address Whitelist

Try it

Restrict API calls to allowed IP Addresses.

Add

Adds an IP address to your white list.

POST https://api.getAddress.io/security/ip-address-whitelist
Content-Type: application/json

Query Parameters

Property Required Description Type
api-key Yes Your administration API key Text

Request Body

{
    "value": "your-ip-address"
}

Response 200

{
    "message": "'your-ip-address' has been added to your IP address whitelist.",
    "id": "zxy"
}

Remove

Removes an IP address from your white list.

DELETE https://api.getAddress.io/security/ip-address-whitelist/{id}

Query Parameters

Property Required Description Type
api-key Yes Your administration API key Text

Response 200

{
    "message": "'your-ip-address' has been removed from your IP address whitelist."
}

Get

Get an IP address from your white list.

GET https://api.getAddress.io/security/ip-address-whitelist/{id}

Query Parameters

Property Required Description Type
api-key Yes Your administration API key Text

Response 200

{
    "id": "xyz",
    "value": "192.168.7.2"
}

List

Lists all IP addresses in your white list.

GET https://api.getAddress.io/security/ip-address-whitelist

Query Parameters

Property Required Description Type
api-key Yes Your administration API key Text

Response 200

[
    {"id": "zxf","value": "192.168.192.0"},
    {"id": "abs","value": "192.168.192.1"}
]

.NET SDK

.NET SDK for working with security and resources.

Install

Install from Nuget.


        PM> Install-Package getAddress.Sdk

Find

Find postal addresses for a UK postcode and optional house name/number.


        var apiKey = new ApiKey("YOUR API KEY");

        using (var api = new GetAddesssApi(apiKey))
        {
            var result = await api.Address.Get(new GetAddressRequest("POSTCODE", "OPTIONAL HOUSE NAME"));

            if (result.IsSuccess)
            {
                var successfulResult =  (GetAddressResponse.Success)result;

                var latitude = successfulResult.Latitude;

                var Longitude = successfulResult.Longitude;

                foreach (var address in successfulResult.Addresses)
                {
                    var line1 = address.Line1;
                    var line2 = address.Line2;
                    var line3 = address.Line3;
                    var line4 = address.Line4;
                    var locality = address.Locality;
                    var townOrCity = address.TownOrCity;
                    var county = address.County;
                }
            }
        }

Usage

Returns the current day's usage and usage limits.


        var adminKey = new AdminKey("Your Admin Key");

        using (var api = new GetAddesssApi(adminKey))
        {
            var result = await api.Usage.Get();

            if (result.IsSuccess)
            {
                var successfulResult = (GetUsageResponse.Success)result;

                var count = successfulResult.Usage.Count;

                var limit1 = successfulResult.Usage.Limit1;

                var limit2 = successfulResult.Usage.Limit2;
            }
        }

Returns the usage and limits for a given day, month and year.


        var adminKey = new AdminKey("Your Admin Key");

        using (var api = new GetAddesssApi(adminKey))
        {
            var result = await api.Usage.Get(DAY,MONTH,YEAR);

            if (result.IsSuccess)
            {
                var successfulResult = (GetUsageResponse.Success)result;

                var count = successfulResult.Usage.Count;

                var limit1 = successfulResult.Usage.Limit1;

                var limit2 = successfulResult.Usage.Limit2;
            }
        }