JavaScript Autocomplete

Add as-you-type Australian address completion to any HTML form. It attaches to a field you already have and fills the rest of the form — no framework and no build step.

Install from NPM or CDN

npm install getaddress-au-autocomplete

<script src="https://cdn.getaddress.io/scripts/getaddress-au-autocomplete-1.9.0.js"></script>

Usage

<label for="address_line_1">Address line 1</label>
<input id="address_line_1" type="text">

<label for="address_line_2">Address line 2</label>
<input id="address_line_2" type="text">

<label for="suburb">Suburb</label>
<input id="suburb" type="text">

<label for="state">State</label>
<input id="state" type="text">

<label for="postcode">Postcode</label>
<input id="postcode" type="text">

<script>
    getAddressAu.autocomplete('address_line_1', '{your-domain-token}', {
        output_fields: {
            address_line_1: 'address_line_1',
            address_line_2: 'address_line_2',
            locality_name: 'suburb',
            state: 'state',
            postcode: 'postcode'
        }
    });
</script>

From npm:

import { autocomplete } from 'getaddress-au-autocomplete';

autocomplete('address_line_1', '{your-domain-token}', { /* options */ });

Suggestions are free and rate limited. Only resolving a picked suggestion to a full address counts as a look-up; set enable_get: false if you only need the one-line address and the widget never spends one.

Events

input.addEventListener('getaddress-au-autocomplete-suggestions', e => console.log(e.suggestions));
input.addEventListener('getaddress-au-autocomplete-suggestion-selected', e => console.log(e.suggestion));
input.addEventListener('getaddress-au-autocomplete-address-selected', e => console.log(e.address));
input.addEventListener('getaddress-au-autocomplete-address-selected-failed', e => console.log(e.error.message));

Options

Option	Default	What it does
output_fields	–	Address fields to write into your form: field name → element id, CSS selector or element.
selected	–	Called with the full address once resolved.
suggestion_selected	–	Called the moment a suggestion is picked, before the look-up.
error	logs	Called when a request fails.
enable_get	true	Resolve the picked suggestion. false keeps the widget entirely free.
set_input_value	true	Write the first address line back into the attached input.
min_characters	2	Characters before the first request.
debounce_ms	150	Quiet period before a request is sent. Left unset, it lengthens on a slow connection (up to 500). Set it to fix the delay.
max_suggestions	6	Maximum suggestions shown. The API returns at most 6.
state	–	Restrict to one state, e.g. "NSW".
postcode	–	Restrict to one postcode.
location	–	[latitude, longitude] to bias results towards. Nothing is excluded.
inject_styles	true	Inject the default stylesheet.
class_names	–	Override the class names on the elements the widget creates.

Address fields

output_fields keys are the Get API's field names — G-NAF's own: address_label, address_detail_pid, address_site_name, address_status, alias_principal, building_name, cleaning_provenance, date_created, flat_type, flat_number, geocode_type, legal_parcel_id, level_type, level_number, locality_name, lot_number, mb_code, number_first, number_last, postcode, primary_pid, primary_secondary, principal_pid, state, street_name, street_suffix, street_type — plus latitude and longitude.

address_line_1 and address_line_2 are composed from the parts, because G-NAF has no printed lines: a building or unit on line 1 with the street on line 2 ("Unit 2" / "14 Stirling Street"), or the street on line 1 and an empty line 2.

Styling

.getaddress-au-autocomplete {
    --gaau-bg: #fff;
    --gaau-border: #d7d9e3;
    --gaau-text: #1f2033;
    --gaau-hover-bg: #f2f3f9;
    --gaau-match: #4338ca;
    --gaau-radius: 6px;
}

Checking a whole address

For an address that arrives on one line — pasted, imported, or typed into a single box — the same package's validate() confirms it with the Validate API.

const result = await getAddressAu.validate('12 Acland St, St Kilda VIC 3182', '{your-domain-token}');

if (result.status === 'found') console.log(result.address.address_label);   // one look-up
if (result.status === 'ambiguous') console.log(result.candidates);          // ids, free

Reverse geocoding

The same package's nearest() finds the addresses nearest a point — a map pin, or a “use my location” button — with the Nearest API. One look-up when it finds one.

const [here] = await getAddressAu.nearest(latitude, longitude, '{your-domain-token}');

if (here) console.log(here.address, here.distance);   // pass here.id to /get for the full address

Businesses, ABNs and ACNs

The same package's companies() attaches business suggestions — by name, ABN or ACN, from the Companies API — to an input. Each shows the name with its ABN, state and postcode. Suggestions are free; picking one resolves the record with the Company API (one look-up; enable_get: false keeps it free).

<input id="business_name" type="text">
<input id="abn" type="text">

<script>
    getAddressAu.companies('business_name', '{your-domain-token}', {
        state: 'VIC',                                   // optional
        output_fields: { abn: 'abn', acn: 'acn' },
        selected: company => console.log(company.name, company.entity_type, company.gst_registered)
    });
</script>

The business on Google. With the Google add-on on, the widget also looks the picked business up on Google, in the visitor's browser with your own Google key, and adds it as company.google: place_id, name, address, latitude, longitude, type, website and phone. It keeps only a sure match: the place must be in the record's postcode and carry every word of its name, and a chain is matched only to its one head office, never a store. Otherwise company.google is null; many businesses (holding companies, trusts) have no place to find. Google bills your Google account for one Text Search per pick; google_match: false turns it off, and selected waits at most google_timeout_ms (3000) for it. Google's terms apply: show the data with Google's attribution and keep no more than the place id.

company.google.address_record is Google's address in parts, in the same shape get() returns (number, street, suburb, state, postcode, unit, coordinates), marked cleaning_provenance {"Source":"GOOGLE"}; what only G-NAF knows is empty. With google_validate: true the widget also checks it against G-NAF with validate() and adds the official record as company.google.gnaf, with gnaf_level address, or building when G-NAF does not list the unit or floor. That costs one look-up when found, nothing when not; gnaf is null when G-NAF has no single match (a building with several numbered entrances, for one).

Its events are getaddressau-company-suggestions, getaddressau-company-suggestion-selected, getaddressau-company-selected (e.company is the record) and getaddressau-company-selected-failed. Without a widget, suggestCompanies() and company() are promises:

const suggestions = await getAddressAu.suggestCompanies('bbc hardw', '{your-domain-token}', { state: 'VIC' });   // free
const record = await getAddressAu.company('000 003 378', '{your-domain-token}');                                 // one look-up

Distance

The same package's distance() measures straight-line metres between two addresses — their ids, as a suggestion carries — or two points, with the Distance API. Free.

const metres = await getAddressAu.distance(storeId, suggestion.id, '{your-domain-token}');

Use a domain token, not an API key

Anything in browser JavaScript is readable by anyone who opens the page. A domain token only works from the domains you register, so publishing it costs you nothing. Keep API keys on your server.