Address APIs
Address Finder API Documentation
Use the NZ address finder API to validate and autocomplete addresses
Run any Addy API live with Addy Swagger UI on us for free with 'demo-api-key' API key
Address Finder API Endpoint
| URL | https://api-nz.addysolutions.com/search/ |
| HTTP Request Type | GET |
cURL Request
The example below will make a JSON request to search for "80 Queen" by adding the API key in the request header:
1curl -X GET --header 'Accept: application/json' --header 'addy-api-key: demo-api-key' 'https://api-nz.addysolutions.com/search?s=80+Queen'Lookup "80 Queen" using the API key as a query string parameter:
1curl -X GET --header 'Accept: application/json' 'https://api-nz.addysolutions.com/search?key=demo-api-key&s=80+Queen'Request Parameters
| Parameter | Description | Type | Required | Example |
|---|---|---|---|---|
| s | Search criteria / address fragment to query (minimum of 2 characters) | string | Yes | 85 Queen |
| max | Number of addresses to return (default = 10, max = 50) | integer (1 to 50) | No | 20 |
| exrural | Exclude rural addresses from the search results (default false) | boolean | No | TRUE |
| expostbox | Exclude Post Box addresses from the search results (default false) | boolean | No | TRUE |
| exundeliver | Exclude non-mail delivery addresses from the search results (default false) | boolean | No | TRUE |
| exspelling | Disable spelling correction from address matching (default false) | boolean | No | FALSE |
| exword | Disable extra word removal from address matching (default false) | boolean | No | FALSE |
| exip | Disable address sorting based on IP address proximity (default false) | boolean | No | FALSE |
| expostcode | Exclude addresses within certain postcodes, defined in a dash separated list of postcodes. See the complete list of postcodes | string | No | 0622-1010-2112 |
| inpostcode | Only include addresses within certain postcodes, defined in a dash separated list of postcodes. See the complete list of postcodes | string | No | 0622-1010-2112 |
| exregion | Exclude addresses within certain regions, defined in a dash separated list of region codes. See the complete list of region codes | string | No | 1/2/03 |
| inregion | Only include addresses within certain regions, defined in a dash separated list of region codes. See the complete list of region codes | string | No | 1/2/03 |
| exterritory | Exclude addresses within certain territories, defined in a dash separated list of territory codes. See the complete list of territory codes | string | No | 5-6-7-8 |
| interritory | Only include addresses within certain territories, defined in a dash separated list of territory codes. See the complete list of territory codes | string | No | 5-6-7-8 |
| callback | JSONP callback function name | string | No | callback123 |
Response Properties
| Property | Description | Type | Example |
|---|---|---|---|
| addresses | Array of address results | address array | [{address},{address}] |
| badwords | Invalid matching words that were removed from the search query | string array | Reception Desk |
| matched | Total number of possible addresses that were matches | integer | 559 |
| q | Search criteria used after eliminating bad matching words | string array | 80 Queen |
Address Properties
| Property | Description | Type | Example |
|---|---|---|---|
| a | Full display name of the address | string | 80 Queen Street, Auckland Central, Auckland 1010 |
| id | Unique identifier for the address | integer | 2417575 |
Addy Solutions' Address Autocomplete API works in conjunction with the Address Details API.
Call the Address Details API endpoint (e.g. https://api-nz.addysolutions.com/address/2417575?key=demo-api-key) to retrieve detailed address metadata for a search result.
Response Example:
"80 Queen Street" with no callback
https://api-nz.addysolutions.com/search?key=demo-api-key&s=80 Queen Street
{
"matched": 11,
"addresses": [
{
"id": 2417575,
"a": "80 Queen Street, Auckland Central, Auckland 1010"
},
{
"id": 3828376,
"a": "80 Queen Street, Masterton 5810"
},
{
"id": 1220406,
"a": "80 Queen Street, North Dunedin, Dunedin 9016"
},
{
"id": 2398953,
"a": "80 Queen Street, Northcote Point, Auckland 0627"
},
{
"id": 1541046,
"a": "80 Queen Street, Richmond 7020"
},
{
"id": 2261993,
"a": "80 Queen Street, Te Kuiti 3910"
},
{
"id": 4947299,
"a": "80 Queen Street, Upper Hutt 5018"
},
{
"id": 1907832,
"a": "80 Queen Street, Waimate 7924"
},
{
"id": 4350248,
"a": "80 Queen Street, Waiuku 2123"
},
{
"id": 2358361,
"a": "80 Queen Street, Westport 7825"
},
{
"id": 2405130,
"a": "80/685 Queen Street East, Levin 5510"
}
],
"badwords": [],
"q": null
}
Response Example:
"Reception Desk 80 Queen Street" search criteria with JSONP callback method "done123"
https://api-nz.addysolutions.com/search?key=demo-api-key&callback=done123&s=Reception Desk 80 Queen Street
typeof done123 === 'function' &&
done123({
"matched": 11,
"addresses": [
{
"id": 2417575,
"a": "80 Queen Street, Auckland Central, Auckland 1010"
},
{
"id": 3828376,
"a": "80 Queen Street, Masterton 5810"
},
{
"id": 1220406,
"a": "80 Queen Street, North Dunedin, Dunedin 9016"
},
{
"id": 2398953,
"a": "80 Queen Street, Northcote Point, Auckland 0627"
},
{
"id": 1541046,
"a": "80 Queen Street, Richmond 7020"
},
{
"id": 2261993,
"a": "80 Queen Street, Te Kuiti 3910"
},
{
"id": 4947299,
"a": "80 Queen Street, Upper Hutt 5018"
},
{
"id": 1907832,
"a": "80 Queen Street, Waimate 7924"
},
{
"id": 4350248,
"a": "80 Queen Street, Waiuku 2123"
},
{
"id": 2358361,
"a": "80 Queen Street, Westport 7825"
},
{
"id": 2405130,
"a": "80/685 Queen Street East, Levin 5510"
}
],
"badwords": [
"reception",
"desk"
],
"q": "80 queen street"
})
Address Services
Address AutocompleteAddress CleansingAddress GeocodingPostcode FinderPricingSign inSign upAddress APIs
Address Finder APIAddress Validation APIAddress Details APIAddress Discovery APIPostcode Finder APIGeocode Address APIBounding Box API