Find
Try itPostal 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 |
expand | No | Expands addresses in to individual named components, such as building number and thoroughfare. | True/False |
fuzzy | No | Searches for the address with fuzzy logic, including synonyms, partial words and acronyms. | 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"] }
Request with expand
GET https://api.getAddress.io/find/nn13er/10?api-key={api-key}&expand=true
Response 200
{ "postcode": "NN1 3ER", "latitude": 52.24593734741211, "longitude": -0.891636312007904, "addresses": [ { "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" } ] }
Testing
These postcodes yield both successful and unsuccessful responses to your request.
- XX2 00X or TR19 7AA or KW1 4YT Returns a 'successful' response
200
. Your request was successful. - XX4 04X Returns 'not found' response
404
. No addresses could be found for this postcode. - XX4 00X Returns 'bad request' response
400
. Your postcode is not valid. - XX4 01X Returns 'unauthorized' response
401
. Your api-key is not valid. - XX4 03X Returns 'forbidden' response
403
. Your api-key is valid but you do not have permission to access to the resource. - XX4 29X Returns 'too many requests' response
429
. You have made more requests than your allowed limit. - XX5 00X Returns 'server error' response
500
. Server error, you should never see this.
Request made with these postcodes will not affect your usage.
(See: https://en.wikipedia.org/wiki/List_of_HTTP_status_codes for more details on HTTP status codes.)
Autocomplete
Try itThe 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.
Request Body
{ "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}" } } }
Request Body
{ "filter": { "town_or_city":"London", } }
Other Parameters
Property | Default | Description | Type |
top | 6 | Sets the number of suggestions to retrieve (max 20) | Text |
all | false | Returns all suggestions when search term contains a postcode | true/false |
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, "addresses": [ { "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 } ] }
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.
Typeahead
Try itThe 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.
Request Body
{ "search":["postcode, line_1, line_2, line_3, locality, town_or_city, district, county, country"] }
Request Body
{ "search":["postcode"] }
Filter
A filter limits results to specific criteria.
Request Body
{ "filter": { "county":"{county name}", "locality":"{locality}", "district":"{district name}", "town_or_city":"{town or city name}", "postcode":"{postcode}", "residential":"{true or false}" } }
Request Body
{ "search":["town_or_city"], "filter": { "county":"Cambridgeshire", } }
Other Parameters
Property | Default | Description | Type |
top | 6 | Sets the number of results to retrieve (max 20) | Text |
Usage
Try itYour API usage and daily limits.
Get
Returns the current day's usage and usage limits.
GET https://api.getAddress.io/v3/usage
Query Parameters
Property | Required | Description | Type |
api-key | Yes | Your administration API key | Text |
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
Property | Required | Description | Type |
api-key | Yes | Your administration API key | Text |
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
Property | Required | Description | Type |
api-key | Yes | Your administration API key | Text |
Response 200
{ { "date": 2019-12-26T00:00:00, "count": 29 }, { "date": 2019-12-27T00:00:00, "count": 19 } }
Subscription
Try itYour Subscription Details
Subscription Details
GET https://api.getAddress.io/subscription
Returns the subscription's payment terms, limits and expiry date.
Query Parameters
Property | Required | Description | Type |
api-key | Yes | Your administration API key | Text |
Examples
Request
GET https://api.getAddress.io/subscription?api-key={api-key}
Response 200
{ "expiry_date": 2019-04-20T14:44:33.7395348Z, "first_daily_limit": 2000, "second_daily_limit": 3000, "amount": 100, "term": "Yearly" }
Private Address List
Try itAdd 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" } ]
Distance
Try itGets 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
Property | Required | Description | Type |
api-key | Yes | Your API key | Text |
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 }
Domain Whitelist (optional)
Try itRestrict 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 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
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 (optional)
Try itRestrict 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 itGets 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}
Response 400
{ "message": "account: '{your new email address}' already exists." }
.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");
IAddressService addressService = new AddressService(apiKey);
var result = await addressService.Get(new GetAddressRequest("POSTCODE", "OPTIONAL HOUSE NAME"));
if (result.IsSuccess)
{
var successfulResult = result.SuccessfulResult;
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 ADMINISTRATION KEY");
IUsageService usageService = new UsageService(adminKey);
var result = await usageService.Get();
if (result.IsSuccess)
{
var successfulResult = result.SuccessfulResult;
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 ADMINISTRATION KEY");
IUsageService usageService = new UsageService(adminKey);
var result = await usageService.Get(new GetUsageRequest(DAY,MONTH,YEAR));
if (result.IsSuccess)
{
var successfulResult = result.SuccessfulResult;
var count = successfulResult.Usage.Count;
var limit1 = successfulResult.Usage.Limit1;
var limit2 = successfulResult.Usage.Limit2;
}
JQuery
Try itThe jQuery plug-in is the simplest way to integrate your web page with our API.
Basic Integration
HTML<!-- 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">
Javascript
<!-- 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>
Additional Output Fields
Property | Description |
latitude | Latitudedinal coordinates +/-90. |
longitude | Longitudinal coordinates +/-180. |
building_number | The building's number. |
building_name | The building's name. |
building_name_or_number | The building's name or, if the name is not availible, the number. |
sub_building_number | The sub-building's number. |
sub_building_name | The sub-building's name. |
sub_building_name_or_number | The sub-building's name or, if the name is not availible, the number. |
thoroughfare | The street or road. |
Basic Usage
Securiy (optional)
Style Options
Postcode TextboxProperty | Default | Description |
input_label | "Enter your Postcode" | Placeholder text |
input_class | "" | CSS class name |
input_id | "getaddress_input" | textbox id |
input_name | "getaddress_input" | textbox name |
Property | Default | Description |
button_label | "Find your Address" | Button text |
button_class | "" | CSS class name |
button_disabled_message | "Fetching Addresses..." | Button text when fetching addresses |
button_id | "getaddress_button" | Button id |
Property | Default | Description |
button_label | "Find your Address" | Button text |
dropdown_class | "" | CSS class name |
dropdown_select_message | "Select your Address" | First line text |
dropdown_id | "getaddress_dropdown" | dropdown id |
Property | Default | Description |
error_message_id | "getaddress_error_message" | Error message id |
error_message_postcode_invalid | "Please recheck your postcode, it seems to be incorrect" | Invalid postcode message |
error_message_postcode_not_found | "Your postcode could not be found. Please type in your address" | Postcode not found message |
error_message_default | "We were not able to find your address from your Postcode. Please input your address manually" | Default look-up failed message |
error_message_class | "" | Error message CSS class |
$('#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
Example$('#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
Example<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
Try itFirst 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" }
Test
Sends a webhook to each endpoint.
POST https://api.getAddress.io/webhook/first-limit-reached/test
Content-Type: application/json
Query Parameters
Property | Required | Description | Type |
api-key | Yes | Your administration API key | Text |
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 (Final) Limit Reached
Try itSecond 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
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/second-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/second-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/second-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" }
Test
Sends a webhook to each endpoint.
POST https://api.getAddress.io/webhook/second-limit-reached/test
Content-Type: application/json
Query Parameters
Property | Required | Description | Type |
api-key | Yes | Your administration API key | Text |
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
Try itPayment 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
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/payment-failed/{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/payment-failed
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/payment-failed/{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" }
Test
Sends a webhook to each endpoint.
POST https://api.getAddress.io/webhook/payment-failed/test
Content-Type: application/json
Query Parameters
Property | Required | Description | Type |
api-key | Yes | Your administration API key | Text |
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.
Account Expired
Try itAn 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
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/expired/{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/expired
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/expired/{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" }
Test
Sends a webhook to each endpoint.
POST https://api.getAddress.io/webhook/expired/test
Content-Type: application/json
Query Parameters
Property | Required | Description | Type |
api-key | Yes | Your administration API key | Text |
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
Try itTrack 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
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/track/{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/track
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/track/{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" }
Test
Sends a webhook to each endpoint.
POST https://api.getAddress.io/webhook/track/test
Content-Type: application/json
Query Parameters
Property | Required | Description | Type |
api-key | Yes | Your administration API key | Text |
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.
Autocomplete Limit Reached
Try itFired 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
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/suggest-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/suggest-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/suggest-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" }
Test
Sends a webhook to each endpoint.
POST https://api.getAddress.io/webhook/suggest-limit-reached/test
Content-Type: application/json
Query Parameters
Property | Required | Description | Type |
api-key | Yes | Your administration API key | Text |
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.
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/openapiTools
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 itGets 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}" }
CC Invoices
Try itCopy (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
Property | Required | Description | Type |
api-key | Yes | Your administration API key | Text |
Request Body
{ "email-address": "recipient-email-address" }
Response 200
{ "email-address": "'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
Property | Required | Description | Type |
api-key | Yes | Your administration API key | Text |
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
Property | Required | Description | Type |
api-key | Yes | Your administration API key | Text |
Response 200
{ "id": 1, "email-address": "recipient-email-address" }
List
Lists all copied recipients.
GET https://api.getAddress.io/cc/invoices
Query Parameters
Property | Required | Description | Type |
api-key | Yes | Your administration API key | Text |
Response 200
[ {"id": 1,"email-address": "recipient-email-address"}, {"id": 2,"email-address": "recipient-email-address"} ]
CC Expired Emails
Try itCopy (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
Property | Required | Description | Type |
api-key | Yes | Your administration API key | Text |
Request Body
{ "email-address": "recipient-email-address" }
Response 200
{ "email-address": "'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
Property | Required | Description | Type |
api-key | Yes | Your administration API key | Text |
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
Property | Required | Description | Type |
api-key | Yes | Your administration API key | Text |
Response 200
{ "id": 1, "email-address": "recipient-email-address" }
List
Lists all copied recipients.
GET https://api.getAddress.io/cc/expired
Query Parameters
Property | Required | Description | Type |
api-key | Yes | Your administration API key | Text |
Response 200
[ {"id": 1,"email-address": "recipient-email-address"}, {"id": 2,"email-address": "recipient-email-address"} ]
Invoices
Try itYour invoices
Get
Gets an invoice
GET https://api.getAddress.io/invoices/{number}
Query Parameters
Property | Required | Description | Type |
api-key | Yes | Your administration API key | Text |
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
Property | Required | Description | Type |
api-key | Yes | Your administration API key | Text |
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
Property | Required | Description | Type |
api-key | Yes | Your administration API key | Text |
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 } ]
Typeahead.JS
Try itThe 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);
});
})
Select2
Try itThe 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);
});
});