The Autocomplete API suggests partial address results for a given term.

Step 1.

Request

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

Response

{
"suggestions": 
[
    {
        "address": "Westminster Gallery, Westminster Central Hall, Westminster, London",
        "url": "/get/NDg5YmQ5NzY5Zjk0YmI5IDUxMTQ3MTI1",
        "id": "NDg5YmQ5NzY5Zjk0YmI5IDUxMTQ3MTI1"
    },
    {
        "address": "Westminster School Lawrence Hall, Greycoat Street, Westminster, London",
        "url": "/get/MDZlNWYxYTUyMDA0NDUyIDUxMDY1ODM0",
        "id": "MDZlNWYxYTUyMDA0NDUyIDUxMDY1ODM0"
    },
    {
        "address": "Knight Frank Victoria & Westminster, 51 Victoria Street, Westminster, London",
        "url": "/get/ZDNhNGJhMmY5YjU0ZWRlIDUxMTQ2ODU2",
        "id": "ZDNhNGJhMmY5YjU0ZWRlIDUxMTQ2ODU2"
    },
    {
        "address": "Easy R M S, 8 Westminster City Hall, Westminster, London",
        "url": "/get/NWRmYWUxMWY2N2E0NGQyIDUxMDM5NDcx",
        "id": "NWRmYWUxMWY2N2E0NGQyIDUxMDM5NDcx"
    },
    {
        "address": "Howick Place Westminster, 7 Howick Place, Westminster, London",
        "url": "/get/ZGQyYTFjMGI0YTkzZjRjIDUxMTE5NDg3",
        "id": "ZGQyYTFjMGI0YTkzZjRjIDUxMTE5NDg3"
    }
]
}

Filter

A filter limits results to specific criteria.

{
    "filter":
    {
        "county":"{county name}",
        "locality":"{locality}",
        "district":"{district name}",
        "town_or_city":"{town or city name}",
        "postcode":"{postcode}",
        "residential":"{true or false}"
        "radius":{
            "km":"{max distance from lat/long in kilometres}",
            "longitude":{longitude},
            "latitude":{latitude}
        }
    }
}

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

Location

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

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

Response

{
    "suggestions": 
    [
        {
            "address": "1a Homestead Road, London",
            "url": "/get/NDg5YmQ5NzY5Zjk0YmI5IDUxMTQ3MTI1",
            "id": "NDg5YmQ5NzY5Zjk0YmI5IDUxMTQ3MTI1"
        },
        {
            "address": "1b Homestead Road, London",
            "url": "/get/MDZlNWYxYTUyMDA0NDUyIDUxMDY1ODM0",
            "id": "MDZlNWYxYTUyMDA0NDUyIDUxMDY1ODM0"
        }
    ]
}

{
    "location":
    {
        "latitude":53.42416763305664,
        "longitude":-1.45220148563385
    }
}

Response

{
    "suggestions": 
    [
        {
            "address": "2 Homestead Road, Sheffield, South Yorkshire",
            "url": "/get/YzUyZDZlOWIyZTUyODdkIDczMTQzMjggNzMyODU3YTM5ZDc4OTE5",
            "id": "YzUyZDZlOWIyZTUyODdkIDczMTQzMjggNzMyODU3YTM5ZDc4OTE5"
        },
        {
            "address": "4 Homestead Road, Sheffield, South Yorkshire",
            "url": "/get/YzRmNDMxMjEwZTMzZmQ5IDczMTQzMjUgNzMyODU3YTM5ZDc4OTE5",
            "id": "YzRmNDMxMjEwZTMzZmQ5IDczMTQzMjUgNzMyODU3YTM5ZDc4OTE5"
        }
    ]
}

Other Parameters

Step 2.

The selected 'Id' is passed to the Get API to return the full address.

Request

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

Response

{
    "postcode": "NN1 3ER",
    "latitude": 52.24593734741211,
    "longitude": -0.891636312007904,
    "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"
    "residential":  true
}

The Typeahead API helps users complete forms and issue better search queries by completing partial search terms.

Request

GET or POST https://api.getAddress.io/typeahead/{term}

Response

{
    [
     "Cambridgeshire",
     "Camargue",
     "Campbell",
     "Cambridge",
     "Cambs",
     "Cambmac"
    ]
}

Search

Restricts search to specific fields.

{
    "search":["postcode, line_1, line_2, line_3, locality, town_or_city, district, county, country"]
}

{
    "search":["postcode"]
}

Filter

A filter limits results to specific criteria.

{
    "filter":
    {
        "county":"{county name}",
        "locality":"{locality}",
        "district":"{district name}",
        "town_or_city":"{town or city name}",
        "postcode":"{postcode}"
    }
}

{
    "search":["town_or_city"],
    "filter":
    {
        "county":"Cambridgeshire",
    }
}

Other Parameters

Your API usage and daily limits.

Get

Returns the current day's usage and usage limits.

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

Query Parameters

Response 200

{
    "usage_today": 99,
    "daily_limit": 2000,
    "monthly_buffer": 1000,
    "monthly_buffer_used": 100
}

Get

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

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

Query Parameters

Response 200

{
    "usage_today": 99,
    "daily_limit": 2000,
    "monthly_buffer": 1000,
    "monthly_buffer_used": 100
}

Get

Returns the usage for a given date range

GET https://api.getAddress.io/usage/from/{from-day}/{from-month}/{from-year}/To/{to-day}/{to-month}/{to-year}  

Query Parameters

Response 200

{
    {
    "date": 2019-12-26T00:00:00,
    "count": 29
    },
    {
    "date": 2019-12-27T00:00:00,
    "count": 19
    }
}

Your Subscription Details

Subscription Details

GET https://api.getAddress.io/subscription 

Returns the subscription's payment terms, limits and expiry date.

Query Parameters

Examples

Request

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

Response 200

{
    "next_billing_date": "2019-04-20T14:44:33.7395348Z",
    "plan":{
        "term": "monthly",
        "daily_lookup_limit_1": 2000,
        "daily_lookup_limit_2": 3000,
        "amount": 100,
        "multi_application": true
    }
    "status": "active",
    "name": "subscription name",
    "payment_method": "direct_debt",
    "start_date": "2018-04-20T14:44:33.7395348Z"
}

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

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

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

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

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

Gets the distance in meters between two postcodes

Get

The Haversine formula is used to calculate the distance between two postcodes

GET https://api.getAddress.io/distance/{postcode_from}/{postcode_to} 

Query Parameters

Response 200

{
    "from": {
         "latitude": 50.065551,
         "longitude": -5.714262,
         "postcode": "TR19 7AA"
    },
    "to": {
         "latitude": 58.63568878173828,
         "longitude": -3.061519145965576,
         "postcode": "KW1 4YT"
    },
    "metres": 968978.0931119365
}

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

Request Body

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

Response 201

{
    "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

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

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

Response 200

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

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

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

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

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

Response 200

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

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

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

Request Body

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

Response 204

 {no content}

Response 400

{
    "message": "account: '{your new email address}' already exists."
}

.NET SDK for working with security and resources.

Install

Install from Nuget.

PM> Install-Package getAddress.Sdk

Dependency Injection

services.AddSingleton(s => new GetAddress.ApiKeys("<ADDRESS LOOKUP KEY>", "<ADMINISTRATION KEY>"));
services.AddHttpClient<GetAddress.Api>();

Find

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

public void Find(GetAddress.Api api)
{
    var result = await api.Find("TR19 7AA");
  
    if (result.IsSuccess)
    {
        foreach(var address in result.Success.Addresses)
        {
            var line1 = address.Line1;
            var line2 = address.Line2;
            var line3 = address.Line3;
            var line4 = address.Line4;
            var buildingName = address.BuildingName;
            //....
        }
    }
    else
    {
        var errorMessage = result.Failed.Message;
    }
}

Autocomplete

Autocomplete and lookup address

public void Autocomplete(GetAddress.Api api)
{
  var autocompleteResult = await api.Autocomplete("High St");

  if (autocompleteResult.IsSuccess)
  {
      foreach(var suggestion in autocompleteResult.Success.Suggestions)
      {
          var getResult = await api.Get(suggestion);

          if (getResult.IsSuccess)
          {
              var address = getResult.Success;
              var line1 = address.Line1;
              var line2 = address.Line2;
              var line3 = address.Line3;
              var line4 = address.Line4;
              var buildingName = address.BuildingName;
              //....
          }
      }
  }
  else
  {
      var errorMessage = autocompleteResult.Failed.Message;
  }
}

The jQuery plug-in is the simplest way to integrate your web page with our API.

Basic Integration

<!-- Postcode field -->
<div id="postcode_lookup"></div>  

<!-- Add to your existing form -->
<label>First Address Line</label>
<input id="line1" type="text"> 

<label>Second Address Line</label>
<input id="line2" type="text">   

<label>Third Address Line</label>
<input id="line3" type="text">  

<label>Town</label>
<input id="town" type="text">

<label>County</label>
<input id="county" type="text">

<label>Postcode</label>
<input id="postcode" type="text">
                            

<!-- Include JQuery v2+ -->
<script src="jquery.js"></script>
<!-- Include plugin file -->
<script src="https://cdn.getaddress.io/scripts/jquery.getAddress-4.0.0.min.js"></script>

<!-- Add after your form -->
<script>
$('#postcode_lookup').getAddress(
    {
    api_key: 'YOUR_API_KEY',  
    output_fields:{
        line_1: '#line1',
        line_2: '#line2',
        line_3: '#line3',
        post_town: '#town',
        county: '#county',
        postcode: '#postcode'
    }
});
</script>

Securiy (optional)

Style Options

$('#postcode_lookup').getAddress(
    {
    api_key: 'YOUR_API_KEY',  
    output_fields:
        {
        line_1: '#line1',
        line_2: '#line2',
        line_3: '#line3',
        post_town: '#town',
        county: '#county',
        postcode: '#postcode'
        },
    input_label:'Please enter your postcode',
    input_class:'form-control',
    button_label:'Search',
    button_class:'btn btn-primary'
});

Callbacks

$('#postcode_lookup').getAddress(
    {
    api_key: 'YOUR_API_KEY',  
    output_fields:
        {
        line_1: '#line1',
        line_2: '#line2',
        line_3: '#line3',
        post_town: '#town',
        county: '#county',
        postcode: '#postcode'
        },
    <!--  Optionally register callbacks at specific stages -->
    onLookupSuccess: function(data){/* Your custom code */},
    onLookupError: function(){/* Your custom code */},
    onAddressSelected: function(elem,index){/* Your custom code */}
});
});

Multiple Forms

<script>
$('#postcode_lookup_1').getAddress(
    {
    api_key: 'YOUR_API_KEY',  
    output_fields:{
        line_1: '#line1_1',
        line_2: '#line2_1',
        line_3: '#line3_1',
        post_town: '#town_1',
        county: '#county_1',
        postcode: '#postcode_1'
    }
});

$('#postcode_lookup_2').getAddress(
    {
    api_key: 'YOUR_API_KEY',  
    output_fields:{
        line_1: '#line1_2',
        line_2: '#line2_2',
        line_3: '#line3_2',
        post_town: '#town_2',
        county: '#county_2',
        postcode: '#postcode_2'
    }
});
</script>

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

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

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

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

Response 200

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

Test

Sends a webhook to each endpoint.

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

Content-Type: application/json

Query Parameters

Response 200

{
    "message": "Webhook has been sent"
}

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

Tools

PIPE DREAM

Reliably inspect any HTTP traffic to observe and debug your apps and webhook integrations. Create an endpoint to get started for free.

NGROK

One command for an instant, secure URL to your localhost server through any NAT or firewall.

Second limit reached webhook is fired when a plan's daily usage limit is reached. Subsequent requests will receive a 429 response.

Add

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

POST https://api.getAddress.io/webhook/second-limit-reached 

Content-Type: application/json

Query Parameters

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/second-limit-reached/{id} 

Query Parameters

Response 200

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

List

Lists webhook URLs.

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

Query Parameters

Response 200

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

Get

Gets webhook URL.

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

Query Parameters

Response 200

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

Test

Sends a webhook to each endpoint.

POST https://api.getAddress.io/webhook/second-limit-reached/test 

Content-Type: application/json

Query Parameters

Response 200

{
    "message": "Webhook has been sent"
}

Data

Data sent as JSON in the POST request body

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

Tools

PIPE DREAM

Reliably inspect any HTTP traffic to observe and debug your apps and webhook integrations. Create an endpoint to get started for free.

NGROK

One command for an instant, secure URL to your localhost server through any NAT or firewall.

Payment failed webhook is fired when a Credit Card or Direct Debit payment failed to process.

Add

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

POST https://api.getAddress.io/webhook/payment-failed 

Content-Type: application/json

Query Parameters

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/payment-failed/{id} 

Query Parameters

Response 200

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

List

Lists webhook URLs.

GET https://api.getAddress.io/webhook/payment-failed 

Query Parameters

Response 200

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

Get

Gets webhook URL.

GET https://api.getAddress.io/webhook/payment-failed/{id} 

Query Parameters

Response 200

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

Test

Sends a webhook to each endpoint.

POST https://api.getAddress.io/webhook/payment-failed/test 

Content-Type: application/json

Query Parameters

Response 200

{
    "message": "Webhook has been sent"
}

Data

Data sent as JSON in the POST request body

{
    "version":"1.0.0.0",
    "action":"payment_failed",
    "created_at":"2019-02-14T12:58:01.0006757Z",
    "details":
    {
        "update_card_details_link":"https://getaddress.io/updatecarddetails?emailaddress=your-email-address@domain.com"
    },
    "type":"billing"
}

Tools

PIPE DREAM

Reliably inspect any HTTP traffic to observe and debug your apps and webhook integrations. Create an endpoint to get started for free.

NGROK

One command for an instant, secure URL to your localhost server through any NAT or firewall.

An Account expired webhook is fired when an application has made an API call to our service with an expired account.

Add

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

POST https://api.getAddress.io/webhook/expired 

Content-Type: application/json

Query Parameters

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/expired/{id} 

Query Parameters

Response 200

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

List

Lists webhook URLs.

GET https://api.getAddress.io/webhook/expired 

Query Parameters

Response 200

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

Get

Gets webhook URL.

GET https://api.getAddress.io/webhook/expired/{id} 

Query Parameters

Response 200

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

Test

Sends a webhook to each endpoint.

POST https://api.getAddress.io/webhook/expired/test 

Content-Type: application/json

Query Parameters

Response 200

{
    "message": "Webhook has been sent"
}

Data

Data sent as JSON in the POST request body

{
    "version":"1.0.0.0",
    "action":"expired",
    "created_at":"2019-02-14T12:58:01.0006757Z",
    "details":
    {
        "update_card_details_link":"https://getaddress.io/updatecarddetails?emailaddress=your-email-address@domain.com"
    },
    "type":"billing"
}

Tools

PIPE DREAM

Reliably inspect any HTTP traffic to observe and debug your apps and webhook integrations. Create an endpoint to get started for free.

NGROK

One command for an instant, secure URL to your localhost server through any NAT or firewall.

Track account activity.

Add

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

POST https://api.getAddress.io/webhook/track 

Content-Type: application/json

Query Parameters

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/track/{id} 

Query Parameters

Response 200

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

List

Lists webhook URLs.

GET https://api.getAddress.io/webhook/track 

Query Parameters

Response 200

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

Get

Gets webhook URL.

GET https://api.getAddress.io/webhook/track/{id} 

Query Parameters

Response 200

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

Test

Sends a webhook to each endpoint.

POST https://api.getAddress.io/webhook/track/test 

Content-Type: application/json

Query Parameters

Response 200

{
    "message": "Webhook has been sent"
}

Data

Data sent as JSON in the POST request body

{
    "version":"1.0.0.0",
    "action":"track",
    "created_at":"2019-12-14T12:58:01.0006757Z",
    "details":
    {
        "ip_address":"192.168.0.1"
        "postcode":"SW1 A2AA"
        "referer":"https://api.getaddress.io"
    },
    "type":"usage"
}

Tools

PIPE DREAM

Reliably inspect any HTTP traffic to observe and debug your apps and webhook integrations. Create an endpoint to get started for free.

NGROK

One command for an instant, secure URL to your localhost server through any NAT or firewall.

Fired when the Autocomplete API rate limit is exceeded.

Add

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

POST https://api.getAddress.io/webhook/suggest-limit-reached 

Content-Type: application/json

Query Parameters

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/suggest-limit-reached/{id} 

Query Parameters

Response 200

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

List

Lists webhook URLs.

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

Query Parameters

Response 200

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

Get

Gets webhook URL.

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

Query Parameters

Response 200

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

Test

Sends a webhook to each endpoint.

POST https://api.getAddress.io/webhook/suggest-limit-reached/test 

Content-Type: application/json

Query Parameters

Response 200

{
    "message": "Webhook has been sent"
}

Data

Data sent as JSON in the POST request body

{
    "version":"1.0.0.0",
    "action":"suggest_limit_reached",
    "created_at":"2020-08-14T12:58:01.0006757Z",
    "details":
    {
        "plan_limit":200
        "upgrade_link":https://getaddress.io/upgrade
    },
    "type":"usage"
}

Tools

PIPE DREAM

Reliably inspect any HTTP traffic to observe and debug your apps and webhook integrations. Create an endpoint to get started for free.

NGROK

One command for an instant, secure URL to your localhost server through any NAT or firewall.

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

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.

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

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

Response 201

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

Copy (CC) recipients to your emailed invoices

Add

Adds copied recipient to your emailed invoices

POST https://api.getAddress.io/cc/invoices 

Content-Type: application/json

Query Parameters

Request Body

{
    "email-address": "recipient-email-address"
}

Response 200

{
    "message": "'recipient-email-address' will be CC'd in your invoice emails.",
    "id": 1
}

Remove

Removes a copied recipient.

DELETE https://api.getAddress.io/cc/invoices/{id}

Query Parameters

Response 200

{
    "message": "'recipient-email-address' has been removed from your invoice CC list."
}

Get

Gets copied recipient.

GET https://api.getAddress.io/cc/invoices/{id}

Query Parameters

Response 200

{
    "id": 1,
    "email-address": "recipient-email-address"
}

List

Lists all copied recipients.

GET https://api.getAddress.io/cc/invoices  

Query Parameters

Response 200

[
    {"id": 1,"email-address": "recipient-email-address"},
    {"id": 2,"email-address": "recipient-email-address"}
]

Copy (CC) recipients to your expired account emails

Add

Adds copied recipient to your expired account emails

POST https://api.getAddress.io/cc/expired 

Content-Type: application/json

Query Parameters

Request Body

{
    "email-address": "recipient-email-address"
}

Response 200

{
    "message": "'recipient-email-address' will be CC'd in your expired account emails.",
    "id": 1
}

Remove

Removes a copied recipient.

DELETE https://api.getAddress.io/cc/expired/{id}

Query Parameters

Response 200

{
    "message": "'recipient-email-address' has been removed from your expired account CC list."
}

Get

Gets copied recipient.

GET https://api.getAddress.io/cc/expired/{id}

Query Parameters

Response 200

{
    "id": 1,
    "email-address": "recipient-email-address"
}

List

Lists all copied recipients.

GET https://api.getAddress.io/cc/expired  

Query Parameters

Response 200

[
    {"id": 1,"email-address": "recipient-email-address"},
    {"id": 2,"email-address": "recipient-email-address"}
]

Your invoices

Get

Gets an invoice

GET https://api.getAddress.io/invoices/{number}

Query Parameters

Response 200

{
    "date": "2018-01-01T00:02:37Z",
    "number": "invoice number",
    "address_1": "address line 1",
    "address_2": "address line 2",
    "address_3": "address line 3",
    "address_4": "address line 4",
    "address_5": "address line 5",
    "address_6": "address line 6",
    "total": 12,
    "tax": 2,
    "invoice_lines": [
    {
      "quantity": 1,
      "details": "getAddress.io subscription",
      "unit_price": 10,
      "subtotal": 10
    }
    ],
    "pdf_url": https://getaddress.io/invoice/invoice number
}

List

Returns the invoices for a given date range

GET https://api.getAddress.io/invoices/from/{from-day}/{from-month}/{from-year}/To/{to-day}/{to-month}/{to-year}

Query Parameters

Examples

Request

GET https://api.getAddress.io/invoices/from/1/2/2018/To/1/2/2018

Response 200

[
    {
    "date": "2018-01-01T00:02:37Z",
    "number": "invoice number 1",
    "address_1": "address line 1",
    "address_2": "address line 2",
    "address_3": "address line 3",
    "address_4": "address line 4",
    "address_5": "address line 5",
    "address_6": "address line 6",
    "total": 12,
    "tax": 2,
    "invoice_lines": [
    {
      "quantity": 1,
      "details": "getAddress.io subscription",
      "unit_price": 10,
      "subtotal": 10
    }
    ],
    "pdf_url": https://getaddress.io/invoice/invoice number 1
    },
    {
    "date": "2018-02-01T00:02:37Z",
    "number": "invoice number 2",
    "address_1": "address line 1",
    "address_2": "address line 2",
    "address_3": "address line 3",
    "address_4": "address line 4",
    "address_5": "address line 5",
    "address_6": "address line 6",
    "total": 12,
    "tax": 2,
    "invoice_lines": [
    {
      "quantity": 1,
      "details": "getAddress.io subscription",
      "unit_price": 10,
      "subtotal": 10
    }
    ],
    "pdf_url": https://getaddress.io/invoice/invoice number 
    }
]

List

Lists all invoices

GET https://api.getAddress.io/invoices  

Query Parameters

Response 200

[
    {
    "date": "2018-01-01T00:02:37Z",
    "number": "invoice number 1",
    "address_1": "address line 1",
    "address_2": "address line 2",
    "address_3": "address line 3",
    "address_4": "address line 4",
    "address_5": "address line 5",
    "address_6": "address line 6",
    "total": 12,
    "tax": 2,
    "invoice_lines": [
    {
      "quantity": 1,
      "details": "getAddress.io subscription",
      "unit_price": 10,
      "subtotal": 10
    }
    ],
    "pdf_url": https://getaddress.io/invoice/invoice number 1
    },
    {
    "date": "2018-01-01T00:02:37Z",
    "number": "invoice number 2",
    "address_1": "address line 1",
    "address_2": "address line 2",
    "address_3": "address line 3",
    "address_4": "address line 4",
    "address_5": "address line 5",
    "address_6": "address line 6",
    "total": 12,
    "tax": 2,
    "invoice_lines": [
    {
      "quantity": 1,
      "details": "getAddress.io subscription",
      "unit_price": 10,
      "subtotal": 10
    }
    ],
    "pdf_url": https://getaddress.io/invoice/invoice number 
    }
]

Slack

All getAddress() webhooks integrate directy with the Incoming Webhooks App.

The code below shows the basic steps required to configure the popular autocomplete library Typeahead.js.

Result

A live example can be found here. This example requires your API key in the Script.JS file.

Link Typeahead.js, Bloodhound and JQuery

<script src="https://code.jquery.com/jquery-3.5.1.min.js"></script>
<script src="//s3-us-west-2.amazonaws.com/s.cdpn.io/346442/bloodhound.js"></script>
<script src="//s3-us-west-2.amazonaws.com/s.cdpn.io/346442/typeahead.jquery.js"></script>

Create a search field

<input class="typeahead" type="text" placeholder="Find your address" />

Create and configure a new Bloodhound suggestion engine

var suggestionEngine = new Bloodhound({
    datumTokenizer: Bloodhound.tokenizers.obj.whitespace('value'),
    queryTokenizer: Bloodhound.tokenizers.whitespace,
    remote: {
        url: '//api.getaddress.io/suggest/',
        replace: function(url, query) {
            return url + query + "?api-key=Your API Key";
        },
        transform: function(response) {
            return response.suggestions;
        },
        ajax: {
            type: "GET"
        }
    }
 });

Connect your search field and suggestion engine to Typeahead

var suggestionTemplate = function (suggestion) {
    return '<div>' + suggestion.address + '</div>';
}

$('.typeahead').typeahead(
    {
        highlight: true,
    },
    {
        display: 'title',
        name: 'addresses',
        source: suggestionEngine,
        templates: {
            notFound: '<div> Not found </div>',
            suggestion: suggestionTemplate
        }
    });
});

Fetch an address when a suggestion is selected

$('.typeahead').on('typeahead:select', function(evt, suggestion) {
    var id = suggestion.id;
    $.get('https://api.getaddress.io/get/' + id, {'api-key':'your API key'}, function (address, status)
    {
        console.log(address);
    });
})

The code below shows the basic steps required to configure the popular autocomplete library Select2.

Result

A live example can be found here. This example requires your API key in the Script.JS file.

Link Select2 CSS+JavaScript and JQuery

<link rel=stylesheet href="https://cdn.jsdelivr.net/npm/select2@4.1.0-beta.1/dist/css/select2.min.css"></link>
<script src="https://code.jquery.com/jquery-3.5.1.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/select2@4.1.0-beta.1/dist/js/select2.min.js"></script>

Create a search field

<select class="select2-example"></select>

Connect your search field and configure Select2

$('.select2-example').select2({
    width: '100%',
    minimumInputLength: 2,
    placeholder: "Find your address",
    language: {
        inputTooShort: function() {
            return '';
        }
    },
    ajax: {
        url: function (params) {
            if(params.term) return 'https://api.getaddress.io/suggest/' + params.term;
            return '';
        },
        dataType: 'json',
        data: function (params) {
            var query = { 'api-key': yourApiKey };
            return query;
        },
        processResults: function (data) {
            var results = [];

            if (data.suggestions && data.suggestions.length > 0) {

                for (var i = 0; i < data.suggestions.length; i++) {
                    var suggestion = data.suggestions[i];
                    var result = {
                        id:suggestion.id,
                        text:suggestion.address
                    }
                    results.push(result);
                }
            }

            return {
                results: results
            };
        }
    }
});

Fetch an address when a suggestion is selected

$('.select2-example').on('select2:select', function (e) {
    var data = e.params.data;
    var id = data.id;
    $.get('https://api.getaddress.io/get/' + id, {'api-key':yourApiKey}, function (address, status)
    {
        console.log(address);
    });
});