Enabling International Address Autocomplete with the common address plugin

About the common address plugin

The common address plugin includes additional functionality for the support of searching for addresses from both Australia and New Zealand, as well as all of the additional countries supported by the International Autocomplete API.

By completing the steps below you will add functionality for international address autocomplete on your website or forms.

Overview

This page shows how to add the common address plugin to an address form.

The basic steps are:

1. Identify the identifiers of each of the address form elements
2. Paste the provided configuration script into your webpage
3. Adjust the configuration to match your form elements

Identify the element ID values

You should have an existing address form. It should already be working well - just with manual address entry. We will enhance this form to enable address autocompletion from different countries.

Here is an example of a simple form that contains address elements. We will attach the plugin to the street address field. The plugin will need to monitor the country field, and use this to decide which results to display to the end user.

When the user selects an address, we will populate the remaining address elements with the indivual address elements. Write down each field ID name like the table below:

If you do not have ID values assigned to the form elements, you can also use CSS selectors to identify the elements. For example, you might identify the city element using selectors such as input[name=city].

  
<script>
(function (d) {
  // **************************************************
  // Addressfinder settings
  // **************************************************

  // STEP BY STEP integration instructions here:
  // https://addressfinder.nz/docs/plugins/common-address/

  var conf = {
    // STEP 1: paste in your licence key
    licenceKey: "ADDRESSFINDER_DEMO_KEY",

    defaultCountryCode: "NZ",

    // STEP 2 - update the property selectors using the ID attributes of your form fields
    addressSelector: "#address",
    suburbSelector: "#suburb",
    citySelector: "#city",
    stateSelector: "#state",
    postcodeSelector: "#postcode",
    countrySelector: "#country",

    // STEP 3 (optional): customise the addresses returned by updating the address_params values
    // Examples at: https://addressfinder.nz/docs/widget_code_generator/
    countryConfig: {
      NZ: {
        widgetOptions: {
          address_params: {
            delivered: 1,
            post_box: 0
          }
        }
      },
      AU: {
        widgetOptions: {
          address_params: {
            gnaf: 1
          }
        }
      },
      DEFAULT: {
        widgetOptions: {
          max_results: 15
        }
      }
    },

    // STEP 4: once the plugin is working, you can set debugMode to false
    debugMode: true
  };

  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>
  

Paste the provided configuration script

You should paste the configuration script into the source code of your webpage. We suggest that you include it at the bottom of the page.

Adjust the configuration

You should now set each of the ID values in the script. Notice that the ID values have a # prefix which needs to be retained. If you are using a CSS selector, then this is not necessary.

Next, update the licenceKey value to use your key. You can obtain this value from the credentials link in the Portal sidebar.

The defaultCountryCode is set to NZ which is probably suitable.

Advanced settings

You may choose to adjust the datasets and other filters applied by the plugin. These settings are passed as address_params for each of the countries. You can see the possible options for each of these at the following links:

• Australian address params
• New Zealand address params
• International address params

You can find examples of different configuration options on the Code Examples page.

Testing the plugin

By default, the plugin is set to have debugMode enabled. With this set, the plugin will report on any problems that it encounters. These messages are sent to the Javascript console.

After you have published your changes, you should see the autocomplete activating when you type into the address field. Make sure that you have selected a country first.

Alternative options

Below is a list of Common Plugin code examples which demonstrate different set up options.

• Automatic Country Selection
• Configuring Different Options For Different Countries
• Map Countries and States To Custom HTML Select Values
• Address Metadata Collection
• Disabling And Enabling The Common Plugin
• When No Addresses Are Returned

Troubleshooting

If you still have the debugMode enabled, then you can view error messages within your browser's Javascript console.

The most likely problem is a mis-configuration of the field IDs. The code above will give you a useful error message if it is unable to find the correct field.

If this happens, you should double-check the values you wrote down in the table above. Have these values been copied into the code correctly? Is the required # prefix included?

Still having trouble? Send us an email at support@addressfinder.nz, and we will have a look. Be sure to include the URL of the page, so we can debug the problem.