addy

NZ
AU

addy

NZ
AU

Services

Pricing

Documentation

Contact

FAQ

Login

Integrations

Address & Postcode Widgets
Address Validation with HTML
JavaScript Code Generator
Address Validation with JavaScript
jQuery Autocomplete

JavaScript Autocomplete for Addresses

Integration guide to find and validate addresses using JavaScript

JavaScript Integration Guide


This is a step-by-step guide to add an address autocomplete widget onto a website within minutes using lightweight open source JavaScript code. A range of address form combinations are covered to demonstrate how to simplify and speed up a checkout / registration form by auto-suggesting addresses while users type.

Address validation happens in real-time by calling Addy's address finder API to find addresses and ensuring address fields are complete and accurate with suburb, city and postcode.

Contact us if you need help and we will be happy to assist.

Use the JavaScript Code Generator for fast and easy address autocomplete integration.

500 FREE completed address fields per month. Busy month? Choose a plan to meet your needs.

Examples


Autocomplete address form demo

This demo caters for a typical scenario where two address lines are available on a registration or checkout form.

Billing and shipping address demo

This demo caters for multiple address fields on a single page such as a billing and shipping address form. It is recommended to simplify the order page with an option to use the same billing and shipping address to improve checkout efficiency.

  • Use multiple address forms on a single page
  • Exclude PO Boxes and Private Bags (e.g. the shipping address)
  • Include Regions
Shipping Address
Billing Address

Single line address with a territory and region demo

Address lookup by country demo

In this demo, address suggestions will only show up when the selected country is New Zealand.

Address Fields


Form Fields Configuration

This section describes how to assign address fields to a web form by using the JavaScript address lookup widget.

Only the "input" address field parameter as defined in the first constructor parameter is mandatory. Fields can be passed into the second constructor parameter or defined through the fields property.

<script type="text/javascript">
      // Address Autocomplete Instance
      var addyComplete = new AddyComplete(document.getElementById("address1"));
      
      // Map the fields to address controls
      addyComplete.fields = {
          address1: document.getElementById("address1"),
          address2: document.getElementById("address2"),
          ...
      }
  </script>

The supported address fields are defined below:

NameDescriptionJSON Mapping
addressThe display name of the addressdisplayline
address1Address line 1. Often used in combination with address2address1
address2Address line 2. Often used in combination with address1address2
suburbThe name of the suburbsuburb
cityThe name of the city or mail towncity
territoryThe name of the territory. See districts of New Zealandterritory
regionThe name of the region. See regions of New Zealandregion
postcodeThe postal codepostcode
line1Address Line 1address1
line2Address Line 2address2
line3Address Line 3address3
line4Address Line 4address4

Populated Address Fields

This section describes the address fields that will be populated when an address is selected.

Examples:

  • Apartment / Building Address - Floor 23, 151 Queen Street, Auckland Central, Auckland 1010
  • Standard Address - 1 Fitzroy Road, Bluff Hill, Napier 4110
  • Rural Address - 115 Ngarongo Road, RD 13, Hawera 4673
  • PO Box Address - PO Box 1, Taupo, 335

Single Address Field

addresssuburbcityregionpostcode
Floor 23, 151 Queen StreetAuckland CentralAucklandAuckland1010
1 Fitzroy RoadBluff HillNapierHawke's Bay4110
115 Ngarongo Road, RD 13<Empty>HaweraTaranaki4673
PO Box 1<Empty>TaupoWaikato3351

Two Address Fields

address 1address 2suburbcitypostcode
Floor 23151 Queen StreetAuckland CentralAuckland1010
1 Fitzroy Road<Empty>Bluff HillNapier4110
115 Ngarongo RoadRD 13<Empty>Hawera4673
PO Box 1<Empty><Empty>Taupo3351

Four Address Fields

line 1line 2line 3line 4
Floor 23151 Queen StreetAuckland CentralAuckland 1010
1 Fitzroy RoadBluff HillNapier 4110<Empty>
115 Ngarongo RoadRD 13Hawera 4673<Empty>
PO Box 1Taupo 3351<Empty><Empty>

Two Address Field - No Suburb Field

address 1address 2citypostcode
Floor 23, 151 Queen StreetAuckland CentralAuckland1010
1 Fitzroy RoadBluff HillNapier4110
115 Ngarongo RoadRD 13Hawera4673
PO Box 1<Empty>Taupo3351

Configuration


URL Parameters

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

<script src="https://www.addy.co.nz/scripts/addy.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>
Remember to replace demo-api-key with your own API key.
URL ParameterDefault ValueDescription
keyN/AAddy API Key
callbackN/AAn optional callback method name that should be executed when the addycomplete script has loaded
excludePostBoxfalseExclude PO Boxes and Private Bag addresses
excludeRuralfalseExclude rural addresses
excludeUndeliverfalseExclude non-mail delivery addresses
excludeSpellingfalseDisable spelling correction from address matching
excludeWordfalseDisable extra word removal from address matching
excludeIpfalseDisable address sorting based on IP address proximity
excludePostcodesExclude addresses within certain postcodes, defined in a dash separated list of postcodes
E.g. "1010-0622-7542". See the complete list of postcodes filters
includePostcodeOnly 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
excludeRegionExclude 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
includeRegionOnly 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
excludeTerritoryExclude 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
includeTerritoryOnly 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
tagAdd a logging tag to every request
E.g. A department name such as "Sales"
uniqueidAdd a unique Identifier to every request
E.g. An internal customer ID such as "12345"
maxItems10An optional parameter to specify the maximum number of address items to return
loadcssfalseLoad the default addycomplete.min.css stylesheet
enableLocationfalseEnable reverse geocoding to return "Addresses near me"

JavaScript Configuration

URL parameters can be used as discussed above, which would apply the options to all of the address control instances on the page. The example below shows how to configure options in JavaScript for the addressComplete instance:

PropertyDefault ValueDescription
options.excludePostBoxfalse An optional parameter to exclude PO Boxes and Private Bag numbers from the address results.
options.maxItems10Maximum number of address suggestions to display.

Advanced JavaScript Configuration

The example below shows how to register for the "address selected" event to enable full control over how to render and populate address fields on your website.

View the Address Details API documentation to learn more about the available address properties.

Styling


CSS Branding Options

Use the CSS stylesheet elements below to control the theme, such as the colours and fonts, that will match your brand.

Styles and Content via JavaScript

Use the JavaScript below to modify the CSS class names or to change the content of the messages.

Source Code


The code used in these examples, including third party dependencies (reqwest and neat-complete) are open source and available on GitHub.

There are no dependencies on heavy weight libraries such as jQuery and jQuery UI .

Sign up

Full support

Sign up

Full support

Address Services

Address AutocompleteAddress CleansingAddress GeocodingPostcode FinderPricingSign inSign up
© 2021 Addy LimitedTerms & Conditions
Made in Auckland, New Zealand
Looking for Addy Australia?