Documentation

Find

Try it

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

Email Address

Try it

Gets or updates your account's primary email address


Get

Gets the account's primary email address.

GET https://api.getAddress.io/email-address 

Query Parameters

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

Response 200

{
    "email-address": "{your account's email address}"
}

Update

Updates the account's primary email address with a new email address.

PUT https://api.getAddress.io/email-address 
Content-Type: application/json

Query Parameters

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

Request Body

{
    "new-email-address": "{your new email address}",
}

Response 204

 {no content}

.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;
            }
        }
        

First Limit Reached

Try it

First limit reached webhook is fired when a plan's daily limit is reached.


Add

Adds URL to be called. Webhook data is sent as JSON in the POST request body.

POST https://api.getAddress.io/webhook/first-limit-reached 
Content-Type: application/json

Query Parameters

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

Request Body

{
    "url": "https://your-domain.com/action"
}

Response 200

{
    "message": Webhook : 'https://your-domain.com/action' has been created.,
    "id": "123"
}

Remove

Removes webhook.

DELETE https://api.getAddress.io/webhook/first-limit-reached/{id} 

Query Parameters

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

Response 200

{
    "message": "'https://your-domain.com/action' has been removed from your webhooks."
}

List

Lists webhook URLs.

GET https://api.getAddress.io/webhook/first-limit-reached 

Query Parameters

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

Response 200

[
    {
        "id": "123",
        "url": "https://your-domain.com/action"
    }
]

Get

Gets webhook URL.

GET https://api.getAddress.io/webhook/first-limit-reached/{id} 

Query Parameters

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

Response 200

{
    "id": "123",
    "url": "https://your-domain.com/action"
}

Data

Data sent as JSON in the POST request body

{
    "version":"1.0.0.0",
    "action":"first_limit_reached",
    "created_at":"2017-08-14T12:58:01.0006757Z",
    "details":
    {
        "limit":50,
        "time_penaly":5000,
        "next_limit":100,
        "upgrade_link":"https://getaddress.io/upgrade?emailaddress=your-email-address@domain.com"
    },
    "type":"usage"
}

Open API (Swagger)

The OpenAPI specification (formerly known as the Swagger Specification) is a powerful definition format to describe RESTful APIs. The specification creates a RESTful interface for easily developing and consuming an API by effectively mapping all the resources and operations associated with it. It’s easy-to-learn, language agnostic, and both human and machine readable.

URL

https://getaddress.io/contract/openapi

Tools

SWAGGER CODEGEN

Build APIs quicker and improve consumption of your Swagger-defined APIs in every popular language with Swagger Codegen. Swagger Codegen can simplify your build process by generating server stubs and client SDKs from your Swagger specification, so your team can focus better on your API’s implementation and adoption.

SWAGGER UI

Swagger UI allows anyone — be it your development team or your end consumers — to visualize and interact with the API’s resources without having any of the implementation logic in place. It’s automatically generated from your Swagger specification, with the visual documentation making it easy for back end implementation and client side consumption.

SWAGGER EDITOR

Design, describe, and document your API on the first open source editor fully dedicated to Swagger-based APIs. The Swagger Editor is great for quickly getting started with the Swagger specification. It’s clean, efficient, and armed with a number of features to help you design and document your RESTful interfaces, straight out of the box.

API Key

Try it

Gets or creates a new API key


Get

Gets the account's current API key.

GET https://api.getAddress.io/security/api-key 

Query Parameters

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

Response 200

{
    "api-key": "{your current API key}"
}

Update

Updates the account's current API key with a new API key.

PUT https://api.getAddress.io/security/api-key 
Content-Type: application/json

Query Parameters

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

Response 201

{
    "api-key": "{your new API key}"
}