Integration guide (International)

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.

For Australia and New Zealand, see the classic integration guide.

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.

We will attach the plugin to the 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 individual address elements. Write down each field ID name like the table below:

Field label	Element ID
Address	address
City	city
State	state
Postal code	postcode
Country (optional)	country

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].

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.

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

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

    defaultCountryCode: "AU",

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

    // STEP 3 (optional): customise the addresses returned by updating the address_params values
    countryConfig: {
      AU: {
        widgetOptions: {
          address_params: {
            gnaf: 1
          }
        }
      },
      NZ: {
        widgetOptions: {
          address_params: {
            post_box: 0
          }
        }
      },
      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>

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 AU which is probably suitable.

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.

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.

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.com, and we will have a look. Be sure to include a link to your website, so we can see the page with the problem.