Skip to main content

Installation guide

This page shows how to add Addressfinder's address autocomplete and verification service to a custom form.

JavaScript snippet

This is the simplest way to add address autocomplete to your website. It only takes a few minutes.

Copy the code snippet below and update the property selectors and licenceKey with your values, then add it within the <body> tags in your webpage - ideally just before the closing </body> tag.

<script>
(function (d) {

  // ADDRESSFINDER ADDRESS VERIFICATION
  // https://addressfinder.com/address-verification

  var conf = {

    debugMode: true, // Set to false once the plugin is working

    licenceKey: "ADDRESSFINDER_DEMO_KEY",

    defaultCountryCode: "AU",

    addressSelector: "#address",
    suburbSelector: null,
    citySelector: "#city",
    stateSelector: "#state",
    postcodeSelector: "#postcode",
    countrySelector: "#country",

    countryConfig: {
      AU: {
        widgetOptions: {
          address_params: {
            "source": "gnaf,paf"
          }
        }
      },
      NZ: {
        widgetOptions: {
          address_params: {
          }
        }
      },
      DEFAULT: {
        widgetOptions: {
        }
      }
    },

  };

  d.addEventListener("DOMContentLoaded",function(){if(d.querySelector(conf.addressSelector)){var e=d.createElement("script");e.src="https://api.addressfinder.io/assets/generic/v1/address.js",e.async=!0,e.onload=function(){new Addressfinder.Address.BootHandler(conf)},d.body.appendChild(e)}});
})(document);
</script>

Once the snippet is added, address autocomplete will automatically start working with your form fields. You can further customise the verification service by adding rules.

Step-by-step guide

You should have a working web form containing address fields.

  1. Copy and paste the code snippet at the bottom of your webpage before the closing </body> tag.
  2. Replace the value of addressSelector with the ID attribute of your main address field (e.g. #address). You can also use a CSS selector such as input[name=street_address].
  3. Replace the value of the other property selectors with the ID attributes of the matching fields. Set the ones you don't need to null.
  4. Replace the value of licenceKey with your credentials, you can find it in the Addressfinder Portal.
  5. Change the default country code using the ISO alpha-2 standard (optional).
  6. Customise the verification service settings by including advanced rules (optional).

To get a license key, sign up for a 30-day free trial.
Already have a subscription? Find your key in the Credentials section in the Portal.

Alternative options

If you only need address autocomplete for Australia and/or New Zealand, you may want to consider using the classic widget instead.

Each configuration comes in two versions:

  • Single line: Choose this option if you capture addresses in a single text field.
  • Multiple lines: Choose this option if you capture address elements separately (e.g. street, city, postcode, etc.).

Australia

Single line version (AU)
<script>
(function() {
    var widget, initAddressFinder = function() {
        widget = new AddressFinder.Widget(
            document.getElementById('address'),
            'ADDRESSFINDER_DEMO_KEY',
            'AU', {
                "address_params": {
                    "source": "gnaf,paf"
                }
            }
        );

        widget.on('address:select', function(fullAddress, metaData) {
            document.getElementById('address').value = metaData.full_address
        });
    };

    function downloadAddressFinder() {
        var script = document.createElement('script');
        script.src = 'https://api.addressfinder.io/assets/v3/widget.js';
        script.async = true;
        script.onload = initAddressFinder;
        document.body.appendChild(script);
    };

    document.addEventListener('DOMContentLoaded', downloadAddressFinder);
})();
</script>
Multiple lines version (AU)
<script>
(function() {
    var widget, initAddressFinder = function() {
        widget = new AddressFinder.Widget(
            document.getElementById('address'),
            'ADDRESSFINDER_DEMO_KEY',
            'AU', {
                "address_params": {
                    "source": "gnaf,paf"
                }
            }
        );

        // TODO - Update the ids in the javascript below to match those in your form.

        widget.on('address:select', function(fullAddress, metaData) {
            document.getElementById('address_line_1').value = metaData.address_line_1;
            document.getElementById('address_line_2').value = metaData.address_line_2 || '';
            document.getElementById('suburb').value = metaData.locality_name;
            document.getElementById('state').value = metaData.state_territory;
            document.getElementById('postcode').value = metaData.postcode;
        });
    };

    function downloadAddressFinder() {
        var script = document.createElement('script');
        script.src = 'https://api.addressfinder.io/assets/v3/widget.js';
        script.async = true;
        script.onload = initAddressFinder;
        document.body.appendChild(script);
    };

    document.addEventListener('DOMContentLoaded', downloadAddressFinder);
})();
</script>

New Zealand

Single line version (NZ)
<script>
(function() {
    var widget, initAddressFinder = function() {
        widget = new AddressFinder.Widget(
            document.getElementById('address'),
            'ADDRESSFINDER_DEMO_KEY',
            'NZ', {
                "address_params": {}
            }
        );

        widget.on('address:select', function(fullAddress, metaData) {
            document.getElementById('address').value = metaData.a;
        });
    };

    function downloadAddressFinder() {
        var script = document.createElement('script');
        script.src = 'https://api.addressfinder.io/assets/v3/widget.js';
        script.async = true;
        script.onload = initAddressFinder;
        document.body.appendChild(script);
    };

    document.addEventListener('DOMContentLoaded', downloadAddressFinder);
})();
</script>
Multiple lines version (NZ)
<script>
(function() {
    var widget, initAddressFinder = function() {
        widget = new AddressFinder.Widget(
            document.getElementById('address'),
            'ADDRESSFINDER_DEMO_KEY',
            'NZ', {
                "address_params": {}
            }
        );

        // TODO - Update the ids in the javascript below to match those in your form.

        widget.on('address:select', function(fullAddress, metaData) {
            document.getElementById('address').value = metaData.address_line_1;
            document.getElementById('address_line_2').value = metaData.address_line_2 || '';
            document.getElementById('suburb').value = metaData.selected_suburb;
            document.getElementById('city').value = metaData.selected_city;
            document.getElementById('postcode').value = metaData.postcode;
        });
    };

    function downloadAddressFinder() {
        var script = document.createElement('script');
        script.src = 'https://api.addressfinder.io/assets/v3/widget.js';
        script.async = true;
        script.onload = initAddressFinder;
        document.body.appendChild(script);
    };

    document.addEventListener('DOMContentLoaded', downloadAddressFinder);
})();
</script>

Both (AU + NZ)

Single line version (AU + NZ)
<script>
(function() {
    var addressField = document.getElementById('address'),
        countrySelect = document.getElementById('country'),
        AF_API_KEY = 'ADDRESSFINDER_DEMO_KEY',
        COUNTRY_NAME_NZ = 'New Zealand',
        COUNTRY_NAME_AU = 'Australia',
        widgets = {
            AU: null,
            NZ: null
        }

    /*
    * Determines which addresses are displayed to your user.
    * When either AU or NZ is selected we only display addresses from that country.

    * It is assumed that the country selector is a select element.
    * If you are using checkboxes or radio buttons, you will need to modify this code
    */
    function countryChangeHandler() {
        var countryName = countrySelect.options[countrySelect.selectedIndex].text;
        switch (countryName) {
            case COUNTRY_NAME_NZ:
                widgets.NZ.enable();
                widgets.AU.disable();
                break;
            case COUNTRY_NAME_AU:
                widgets.AU.enable();
                widgets.NZ.disable();
                break;
            default:
                widgets.NZ.disable();
                widgets.AU.disable();
        }
    }

    /*
     * Performs the following functions:
     * 1. initialises the AddressFinder widget for AU and NZ
     * 2. defines the event handler behaviour for when an address is selected
     * 3. Runs countryChangeHandler to set the inital country
     * 3. Setup of event listener for country changing
     */
    function initAddressFinder() {
        widgets['NZ'] = new AddressFinder.Widget(
            addressField,
            AF_API_KEY,
            'NZ', {
                "address_params": {}
            }
        );
        widgets['AU'] = new AddressFinder.Widget(
            addressField,
            AF_API_KEY,
            'AU', {
                "address_params": {
                    "source": "gnaf,paf"
                }
            }
        );

        widgets['NZ'].on('address:select', function(fullAddress, metaData) {
            document.getElementById('address').value = metaData.a;
        });

        widgets['AU'].on('address:select', function(fullAddress, metaData) {
            document.getElementById('address').value = metaData.full_address
        });

        countryChangeHandler()
        countrySelect.addEventListener('change', countryChangeHandler);
    }

    function downloadAddressFinder() {
        var script = document.createElement('script');
        script.src = 'https://api.addressfinder.io/assets/v3/widget.js';
        script.async = true;
        script.onload = initAddressFinder;
        document.body.appendChild(script);
    };

    document.addEventListener('DOMContentLoaded', downloadAddressFinder);
})();
</script>
Multiple lines version (AU + NZ)
<script>
(function() {
    var addressField = document.getElementById('address'),
        countrySelect = document.getElementById('country'),
        AF_API_KEY = 'ADDRESSFINDER_DEMO_KEY',
        COUNTRY_NAME_NZ = 'New Zealand',
        COUNTRY_NAME_AU = 'Australia',
        widgets = {
            AU: null,
            NZ: null
        }

    /*
    * Determines which addresses are displayed to your user.
    * When either AU or NZ is selected we only display addresses from that country.

    * It is assumed that the country selector is a select element.
    * If you are using checkboxes or radio buttons, you will need to modify this code
    */
    function countryChangeHandler() {
        var countryName = countrySelect.options[countrySelect.selectedIndex].text;
        switch (countryName) {
            case COUNTRY_NAME_NZ:
                widgets.NZ.enable();
                widgets.AU.disable();
                break;
            case COUNTRY_NAME_AU:
                widgets.AU.enable();
                widgets.NZ.disable();
                break;
            default:
                widgets.NZ.disable();
                widgets.AU.disable();
        }
    }

    /*
     * Performs the following functions:
     * 1. initialises the AddressFinder widget for AU and NZ
     * 2. defines the event handler behaviour for when an address is selected
     * 3. Runs countryChangeHandler to set the inital country
     * 3. Setup of event listener for country changing
     */
    function initAddressFinder() {
        widgets['NZ'] = new AddressFinder.Widget(
            addressField,
            AF_API_KEY,
            'NZ', {
                "address_params": {}
            }
        );
        widgets['AU'] = new AddressFinder.Widget(
            addressField,
            AF_API_KEY,
            'AU', {
                "address_params": {
                    "source": "gnaf,paf"
                }
            }
        );

        // TODO - Update the ids in the javascript below to match those in your form.

        widgets['NZ'].on('address:select', function(fullAddress, metaData) {
            document.getElementById('address').value = metaData.address_line_1;
            document.getElementById('address_line_2').value = metaData.address_line_2 || '';
            document.getElementById('suburb').value = metaData.selected_suburb;
            document.getElementById('city').value = metaData.selected_city;
            document.getElementById('postcode').value = metaData.postcode;
        });

        widgets['AU'].on('address:select', function(fullAddress, metaData) {
            document.getElementById('address').value = metaData.address_line_1;
            document.getElementById('address_line_2').value = metaData.address_line_2 || '';
            document.getElementById('suburb').value = metaData.locality_name;
            document.getElementById('state').value = metaData.state_territory;
            document.getElementById('postcode').value = metaData.postcode;
        });

        countryChangeHandler()
        countrySelect.addEventListener('change', countryChangeHandler);
    }

    function downloadAddressFinder() {
        var script = document.createElement('script');
        script.src = 'https://api.addressfinder.io/assets/v3/widget.js';
        script.async = true;
        script.onload = initAddressFinder;
        document.body.appendChild(script);
    };

    document.addEventListener('DOMContentLoaded', downloadAddressFinder);
})();
</script>