Address Finder Plugin


Integration guide to add Addy's address validation plugin to your website

Address Validation Integration

Integration can be completed within minutes by simply updating the HTML on your website.

No programming skills such as jQuery or JavaScript is required.

Add Addy's postal address checker to your ecommerce website in 4 easy steps:

Step 1 - Create a free account

Sign up for a free account to get your own Addy API Key that will be used for address lookup requests.

Step 2 - Add the address finder plugin reference

Add a reference to the autocomplete validation widget at the bottom of your address form page (above the </body> tag).

<script src="https://cdn.addy.co.nz/neatcomplete/2.1.0/addycomplete.min.js?key=demo-api-key&loadcss=true" async defer>
</script>

Step 3 - Tag address fields with a class name

Tag each address field with a unique CSS class name that will tell Addy which fields to use for address searching and which fields to populate once an address selection is made.

For example, to turn a text input field into a predictive address search, simply add the addy-line1 class name to your HTML:

<input type="text" class="addy-line1" id="address1" />

View all of the HTML Markup and CSS tags.

Step 4 - Release to production

Save and deploy your changes.

1,500 FREE completed address fields per month. Busy month? Just pay as you go for extras.

NZ Address Validation Demo

Below is a live address validation demo in JSFiddle using HTML only:

Enable Reverse geocoding to "find addresses near me"

Makes it fast and easy for users to fill in your address form accurately without typing a single character on a keyboard. Simply enable the location feature in Addy, which will use the built in GPS in a user's mobile device to suggest a list of nearby addresses.

As described in the integration section above (Step 2), change the script by adding the "&enableLocation=true" parameter to the script reference:

<script src="https://cdn.addy.co.nz/neatcomplete/2.1.0/addycomplete.min.js?key=demo-api-key&loadcss=true&enableLocation=true" async defer>
</script>

Configuration Options

Additional configuration options are provided to customise how the address validation widget should behave on your website.

URL Parameters

The example below shows the options that are available as URL parameters:

<script src="https://cdn.addy.co.nz/neatcomplete/2.1.0/addycomplete.min.js?key=demo-api-key&callback=initAddy&excludePostBox=false&excludeRural=false&excludeUndeliver=false&excludeSpelling=false&excludeWord=false&excludeIp=false&maxItems=10&loadcss=true&enableLocation=true&excludePostcodes=0622-1010&includePostcode=0622-1010&excludeRegion=1-2&includeRegion=3-4&excludeTerritory=1-2-3&includeTerritory=5-6-7&tag=sales&uniqueid=12345" async defer></script>

URL Parameter Default Value Description
key N/A Addy API Key
callback N/A An optional callback method name that should be executed when the addycomplete script has loaded
excludePostBox false Exclude PO Boxes and Private Bag addresses
excludeRural false Exclude rural addresses
excludeUndeliver false Exclude non-mail delivery addresses
excludeSpelling false Disable spelling correction from address matching
excludeWord false Disable extra word removal from address matching
excludeIp false Disable address sorting based on IP address proximity
excludePostcodes Exclude addresses within certain postcodes, defined in a dash separated list of postcodes
E.g. "1010-0622-7542". See the complete list of postcodes filters
includePostcode Only include addresses within certain postcodes, defined in a dash separated list of postcodes.
E.g. "1010-0622-7542". See the complete list of postcodes filters
excludeRegion Exclude addresses within certain regions, defined in a dash separated list of region codes
E.g. "1-2-6" for Northland, Auckland and Taranaki. See the complete list of region code filters
includeRegion Only include addresses within certain regions, defined in a dash separated list of region codes
E.g. "1-2-6" for Northland, Auckland and Taranaki. See the complete list of region code filters
excludeTerritory Exclude addresses within certain territories, defined in a dash separated list of territory codes
E.g. "22-14" for Kapiti Coast District and Hamilton City. See the complete list of territory code filters
includeTerritory Only include addresses within certain territories, defined in the dash separated list of territory codes
E.g. "22-14" for Kapiti Coast District and Hamilton City. See the complete list of territory code filters
tag Add a logging tag to every request
E.g. A department name such as "Sales"
uniqueid Add a unique Identifier to every request
E.g. An internal customer ID such as "12345"
maxItems 10 An optional parameter to specify the maximum number of address items to return
loadcss false Load the default addycomplete.min.css stylesheet
enableLocation false Enable reverse geocoding to return "Addresses near me"

HTML Markup and CSS

The following class names can be used for instructing the address autocomplete widget to add search and autofill functionality to your address fields.

Field Class Name Description Field Type
line1 addy-line1 Mandatory field used for address searching and populating address line 1 text/search
line2 addy-line2 Field to populate with address line 2 text
suburb addy-suburb Field to populate with the suburb name text
city addy-city Field to populate with the city or mail town name text
postcode addy-postcode Field to populate with the 4 digit postal code text
territory addy-territory Field to populate with the territory name. See districts of New Zealand text/select
region addy-region Field to populate with the region name. See regions of New Zealand text/select
id addy-id Field to populate with the unique Addy identifier text/hidden
dpid addy-dpid Field to populate with the DPID (Unique NZ Post Deposit Identifier) text/hidden
x addy-x Field to populate with the longitude coordinate in WGS84 format text/hidden
y addy-y Field to populate with the latitude coordinate in WGS84 format text/hidden

Secondary address fields

Up to 4 address form fields are supported on the same page, such as shipping and billing addresses.

To add additional address fields requires the "addy-2-line1", "addy-3-line1" or "addy-4-line1" pattern as shown below.

Field Address Form 2 Address Form 3 Address Form 4
line1 addy-2-line1 addy-3-line1 addy-4-line1
line2 addy-2-line2 addy-3-line2 addy-3-line2
suburb addy-2-suburb addy-3-suburb addy-4-suburb
city addy-2-city addy-3-city addy-4-city
postcode addy-2-postcode addy-3-postcode addy-4-postcode
territory addy-2-territory addy-3-territory addy-4-territory
region addy-2-region addy-3-region addy-4-region
id addy-2-id addy-3-id addy-4-id
dpid addy-2-dpid addy-3-dpid addy-4-dpid
x addy-2-x addy-3-x addy-4-x
y addy-2-y addy-3-y addy-4-y