Advanced options
The widget is highly customisable which require more system expertise for accurate configuration within your frameworks.
Event listeners
You can subscribe to event notifications from the widget using the on() listener function. This method simply takes the event name, and a callback function.
(function(){
var widget,
initAF = function() {
widget = new AddressFinder.Widget(
document.getElementById('address_field'),
'YOUR_KEY',
'AU'
);
widget.on('result:select', function(value, item) {
alert('You’ve selected: ' + value);
});
};
function downloadAF(f){
var script = document.createElement('script');
script.src = 'https://api.addressfinder.io/assets/v3/widget.js';
script.async = true;
script.onload = f;
document.body.appendChild(script);
};
document.addEventListener('DOMContentLoaded', function(){
downloadAF(initAF);
});
})();
Take a look at the JavaScript reference docs to see what kind of events you can set listeners for.
Custom styling
Typically our JavaScript library embeds a stylesheet with some simple styling. However if you wish to apply your own CSS, that can be done with a few simple tweaks.
First, when initialising the widget, you’ll need to pass an option specifying not to embed its own stylesheet:
(function(){
var widget,
initAF = function() {
widget = new AddressFinder.Widget(
document.getElementById('address_field'),
'YOUR_KEY',
'AU',
{manual_style:true}
);
};
function downloadAF(f){
var script = document.createElement('script');
script.src = 'https://api.addressfinder.io/assets/v3/widget.js';
script.async = true;
script.onload = f;
document.body.appendChild(script);
};
document.addEventListener('DOMContentLoaded', function(){
downloadAF(initAF);
});
})();
Then include some CSS in a stylesheet like so:
ul.af_list {
list-style: none;
padding: 0;
margin: 0;
border: solid 1px #666;
background: white;
}
li.af_item {
cursor: pointer;
}
li.af_hover {
background-color: steelblue;
color: white;
}
li.af_footer {
font-size: 0.8em;
color: #666;
text-align: right;
}
Adding third-party search services
It’s possible to include additional search results in the autocomplete results, by providing a function to carry out the searching. The search function will be passed two arguments, the query and a callback function. The callback function requires you to pass back the original query and an array of formatted results.
(function(){
var widget,
store_service,
stores = ['Queen Street, Brisbane','Cuba Road, Tasmania', 'Oxford Street, Sydney', 'Eureka Tower, Melbourne'],
initAF = function() {
widget = new AddressFinder.Widget(
document.getElementById('address_field'),
'YOUR_KEY',
'AU'
);
store_service = widget.addService('store-search',function(query, response_fn){
var regex = new RegExp(query, 'gi');
var matches = stores.filter(function(store){
return regex.test(store);
});
var results = matches.map(function(match){
return { value: match }
});
response_fn(query, results);
});
store_service.setOption('renderer', function(value){
return "<div class="store_result">" + value + "</div>"
});
};
function downloadAF(f){
var script = document.createElement('script');
script.src = 'https://api.addressfinder.io/assets/v3/widget.js';
script.async = true;
script.onload = f;
document.body.appendChild(script);
};
document.addEventListener('DOMContentLoaded', function(){
downloadAF(initAF);
});
})();
Support for Asynchronous Module Definition (AMD)
By default the widget.js package includes dependencies which can cause problems with AMD libraries such as Require.js, especially when the Addressfinder is loaded after the AMD library. As the core library needs to be loaded from our remote server, we’re providing a special core.js library, which allows you to include the dependencies (reqwest and neat-complete) in your own project.
The best point reference is our example project on GitHub.
The core.js is compatible with all modern browsers. Internet Explorer is supported for versions 10+.
Australia autocomplete options
Source database options
The widget can be configured to search addresses from the PAF, GNAF or both databases. To do this, include in the widget code the source address param and specify the database/s you wish to search. The options include: gnaf, paf and gnaf,paf.
"address_params": {
"source": "gnaf"
}
Include / Exclude PO Box addresses
PO Box addresses only exist in the PAF data so will be included by default when the PAF data is included as a database source. To search PAF addresses but exclude PO Box addresses, include the "post_box": "0" address_param in the widget code.
"address_params": {
"source": "paf",
"post_box": "0"
}
Include / Exclude alias addresses from the search results
Alias addresses are addresses which are created and displayed for the purposes of helping a user find their address. These addresses commonly use a nearby suburb in place of the cononical suburb. Less common types of alias addresses may include those with common misspellings or a single number in place of a range. If/when a user selects an alias address, the canonical address is returned and populated into the fields of form.
Alias addresses are included in the autocomplete results by default. To exclude alias addresses from appearing in the search results, include the "canonical": "1" address_param in the widget code.
"address_params": {
"source": "gnaf",
"canonical": "1"
}
Limit the search results by State/Territory
By default, the widget will seach addresses from across Australia. To limit the results to one or more States or Territories, include the state_codes address_param and the desired state/territory abbreviation/s, in the widget code.
"address_params": {
"source": "gnaf",
"state_codes": "QLD,NSW"
}
Limit the number of search results to display in the drop down
By default, the widget will return and display a maximum of 10 addresses in the search results. To display more or less than the default, include the max address_param and the number of addresses you wish to display, in the widget code. Also include the max_results widget param in the code as this gives the widget permission to display these extra addresses. Use any whole number between 1 and 100.
{
"address_params": {
"source": "gnaf",
"max": "20"
},
"max_results": "20"
}
Australian metadata options
Collect the DPID
The Delivery Point Identifier, (DPID) is an identifier associated with postal addresses. The DPID is used postal activities such as barcoding and bulk mailouts and therefore is of value to some organisations. The DPID is included in the response, along with the selected address data, when the "source": "paf" address_param is include in the widget code. To collect the DPID specify, within the widget code, where to populate the DPID on selection of the address.
{
"address_params": {
"source": "paf"
}
}
);
widget.on("address:select", function (fullAddress, metaData) {
document.getElementById("your_dpid_field_id").value = metaData.dpid;
Collect GPS coordinates
The GPS Coordinates are not included in the repsonse by default. To have them included, add the "gps": "1" address_metadata_param into the widget code. Then, within the widget code, specify where to populate the latitude and longitude.
{
"address_params": {
"source": "gnaf,paf"
},
"address_metadata_params": {
"gps": "1"
}
}
);
widget.on("address:select", function (fullAddress, metaData) {
document.getElementById("your_address_field_id_here").value =
metaData.latitude + ", " + metaData.longitude;
Collect census data related to the selected address
Census data (meshblock, SA1 and SA2) is returned along with addresses from the GNAF data source. To collect census data, first specifify the "source": "gnaf" address_param and then specify, in the widget code, where the census data should be populated. Data from the most recent census is returned.
To collect data from a specific census year (optional), sepecify the year in the address_metadata_params.
{
"address_params": {
"source": "gnaf"
},
"address_metadata_params": {
"census": "2016"
}
}
);
widget.on('address:select', function(fullAddress, metaData) {
document.getElementById('addrs_2').value = metaData.sa2_id;
To view a list of census, LGA and other metadata available for collection, when GNAF is the source data, view the metadata reponse.
Collect the selected address split out into its elements
On selection of an address, the response returns the address in a variety of formats. These include a single field format (the full_address), four field format (address_line_combined, locality, state_territory and postcode) and the five field format (address_line_1, address_line_2, locality, state_territory and postcode). In addition to these, the address is also split our into it's elements - see the metadata reponse. The widget can be instructed to populate each of these elements into seperate fields. View a a code example of this here.
New Zealand autocomplete options
Source database options
The widget can be configured to search addresses delievered to by NZ Post or all addresses (NZ Post delivered addresses & LINZ addresses). By default, all addresses are searched. To limit the autocomplete results to NZ Post delivered addresses, include the "delivered": "1" address_param in the widget code.
"address_params": {
"delivered": "1"
}
Include / Exclude PO Box addresses
PO Box addresses are included by default so if you wish to exclude these from being returned in the search results, include the `"post_box": "0" address_param in the widget code.
"address_params": {
"post_box": "0"
}
Include / Exclude rural addresses
Rural addresses are included by default so if you wish to exclude these from being returned in the autocomplete results, include the `"rural": "0" address_param in the widget code.
"address_params": {
"rural": "0"
}
Limit search results by the Region
By default, the widget will seach addresses from across the whole country. To limit the results to a single region, include a region_code address_param and associated region option in the widget code. This filter is unable to be applied to more than one region at a time. View the region codes listed in the parameters of the NZ Address Autocomplete API docs page.
"address_params": {
"region_code": "1"
}
Limit the number of search results to display in the drop down
By default, the widget will return and display a maximum of 10 addresses in the search results. To display more or less than the default, include the max address_param and the number of addresses you wish to display. Also include the max_results widget param in the code as this gives the widget permission to display these extra addresses. Use any whole number between 1 and 100.
{
"address_params": {
"source": "gnaf",
"max": "20"
},
"max_results": "20"
}
New Zealand metadata options
Collect the DPID
The Delivery Point Identifier, (DPID) is an identifier associated with postal addresses. The DPID is included in the metadata response for every NZ Post delivered address, so to have this returned include the "delivered": "1" address_param in the widget code. Then to collect the DPID, specify, within the widget code, where to populate the DPID on selection of the address.
{
"address_params": {
"delivered": "1"
}
}
);
widget.on('address:select', function(fullAddress, metaData) {
document.getElementById('your_dpid_field_id_here').value = metaData.dpid;
Collect GPS coordinates
The GPS Coordinates are included in the response by default. To collect them, specify in the widget code, where to populate them on selection of the address.
widget.on('address:select', function(fullAddress, metaData) {
document.getElementById('your_longitude_field_id_here').value = metaData.x;
document.getElementById('your_latitude_field_id_here').value = metaData.y;
Collect census data related to the selected address
Census related metadata in included in the response by default. To collect them, specify in the widget code, where to populate them on selection of the address. To collect data from a specific census year (optional), sepecify the year in the address_metadata_params.
{
"address_metadata_params": {
"census": "2023"
}
}
);
widget.on('address:select', function(fullAddress, metaData) {
document.getElementById('your_meshblock_field_id_here').value = metaData.meshblock;
document.getElementById('your_sa1_field_id_here').value = metaData.sa1_id;
document.getElementById('your_sa2_field_id_here').value = metaData.sa2_id;
Collect the selected address split out into its elements
As the address autocomplete service returns the address information in multiple formats, you can collect the address, split into its base elements. To do this, specify in the widget code, where to populate each element on selection of the address. View this example showing the address being split into 10 different elements.
Collect the Postal address and Physical address seperately at the same time
As the address autocomplete service returns both the postal and physical address in the response, on selection of a postal address you can collect both the postal and physical addresses. NB: For most addresses, the portal and physical addresses will be identicle but for some addresses (primarily rural addresses) they are different. View this example showing both the postal and physical address being captured.
Replace macron containing characters with ASCII characters
Many New Zealand addresses now include macrons. If your system, or downstream third-party systems, are unable to handle macron containing addresses, include "ascii": "1" in both the address_params and metadata_address_params in the widget code.
{
"address_params": {
"ascii": "1"
},
"address_metadata_params": {
"ascii": "1"
}
}
If you are looking for something not mentioned in this page, review the code examples page or reach out to use at support@addressfinder.com.