Loading...
Sign in to see the examples with your own API key.

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

OptionDefaultWhat 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.
errorlogsCalled when a request fails.
enable_gettrueResolve the picked suggestion. false keeps the widget entirely free.
set_input_valuetrueWrite the first address line back into the attached input.
min_characters2Characters before the first request.
debounce_ms150Quiet period before a request is sent. Left unset, it lengthens on a slow connection (up to 500). Set it to fix the delay.
max_suggestions6Maximum 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_stylestrueInject 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

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.

Top