Documentation

Addresses

Postal addresses for single UK postcode.


Postcode to Addresses

GET https://api.getAddress.io/v2/uk/{postcode}  

Returns a list of addresses for a postcode.

GET https://api.getAddress.io/v2/uk/{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

Examples

Request

GET https://api.getAddress.io/v2/uk/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

Private addresses are merged with your standard responses.


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"}
]