getaddress-au-autocomplete

Drop-in Australian address autocomplete for any text input. Attach it to a field you already have and it fills the rest of your address form — no framework, no build step, no markup changes.

Addresses come from the getAddress() Australian address API, backed by G-NAF (the Geocoded National Address File), so every address in Australia is covered and geocoded.

30-second start

<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 src="https://cdn.getaddress.io/scripts/getaddress-au-autocomplete-1.6.0.js"></script>
<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>

That is the whole integration. Type into the first field, pick a suggestion, and the rest fill in.

Install

npm install getaddress-au-autocomplete

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

autocomplete('address_line_1', 'YOUR-DOMAIN-TOKEN', { /* options */ });

Ships ESM, CommonJS, TypeScript types, and a <script src> build that puts getAddressAu on window.

Use a domain token, not an API key

Anything in browser JavaScript is readable by anyone who opens the page. A domain token is restricted to the origins you list, so publishing it costs you nothing. An API key is not — keep it on your server.

Free vs metered

Suggestions are free and rate limited, so calling on every keystroke is fine. Only resolving a picked suggestion to a full address counts as a look-up against your plan. If you only need the printed line and not the parts, set enable_get: false and the widget never spends one.

Options

| Option | Default | What it does | | --- | --- | --- | | output_fields | – | Address fields to write into your form. Key is a field name, value is an element id, a CSS selector, or the 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". Sends the suggestion request as a POST. | | postcode | – | Restrict to one postcode. Sends the suggestion request as a POST. | | 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. | | api_url | live API | Point at a different API origin. |

Address fields

output_fields keys are the API's own field names, which are G-NAF's own:

address_label (the printable one-line address), 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.

latitude and longitude are accepted too, and reach into the address's coordinates — which is null for an address G-NAF has not geocoded, in which case both fill with an empty string.

address_status is the one field that is not G-NAF's own: 'current' while G-NAF still publishes the address, 'retired' once it has been withdrawn. Nothing the widget suggests is ever retired, so it only matters if you resolve an id you stored earlier.

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. getAddressAu.addressLines(address) returns the same two lines, for a selected callback.

Every field is a string, and is empty when that address has no value for it. address_label is the whole address on one line.

Events

If callbacks do not suit, listen on the input instead:

const instance = getAddressAu.autocomplete('address_line_1', 'YOUR-DOMAIN-TOKEN');

instance.addEventListener('getaddress-au-autocomplete-address-selected', e => {
    console.log(e.address);
});

| Event | Fires | Carries | | --- | --- | --- | | getaddress-au-autocomplete-suggestions | each time a new list of suggestions arrives | e.suggestions | | getaddress-au-autocomplete-suggestion-selected | the moment a suggestion is picked | e.suggestion | | getaddress-au-autocomplete-address-selected | once the picked suggestion is resolved | e.address, e.suggestion | | getaddress-au-autocomplete-address-selected-failed | when resolving fails, e.g. a 429 | e.error, e.suggestion |

The same values are on e.detail too.

Show the address as JSON

The pattern the getaddress.io home page uses — a search box, and the chosen address printed below:

const input = document.getElementById('autocomplete-textbox');
const viewer = document.getElementById('json-viewer');

getAddressAu.autocomplete(input, 'YOUR-DOMAIN-TOKEN', { set_input_value: false });

input.addEventListener('getaddress-au-autocomplete-suggestions', () => viewer.textContent = '');
input.addEventListener('getaddress-au-autocomplete-address-selected', e => {
    viewer.textContent = JSON.stringify(e.address, null, 2);
    input.value = '';
});
input.addEventListener('getaddress-au-autocomplete-address-selected-failed', e => {
    viewer.textContent = e.error.message;
});

Suburbs and postcodes: location()

The same package suggests places — one per suburb, state and postcode — for a place picker rather than an address form. Picking one resolves its centre (one look-up; enable_get: false keeps it free).

<input id="suburb" type="text">
<input id="state" type="text">
<input id="postcode" type="text">

<script>
    getAddressAu.location('suburb', 'YOUR-DOMAIN-TOKEN', {
        output_fields: { locality_name: 'suburb', state: 'state', postcode: 'postcode' },
        selected: place => console.log(place.coordinates)   // { latitude, longitude }
    });
</script>

It takes the same options as autocomplete() bar the address-only ones (google_places_fallback), with output_fields keys id, location, locality_name, state, postcode, latitude and longitude. Its events are getaddressau-location-suggestions, getaddressau-location-suggestion-selected, getaddressau-location-selected (event.location is the place) and getaddressau-location-selected-failed.

Form fields that complete themselves: typeahead()

Any single field — a suburb, a postcode, a street or a state — completes as it is typed. It suggests plain values, not addresses, so it is free: it never spends a look-up.

<input id="suburb" type="text">
<input id="street" type="text">

<script>
    // Each field completes on its own.
    getAddressAu.typeahead('suburb', 'YOUR-DOMAIN-TOKEN', { search: 'locality' });
    getAddressAu.typeahead('street', 'YOUR-DOMAIN-TOKEN', { search: 'street' });
</script>

search is 'locality', 'postcode', 'street' or 'state', or an array of them. A street is its name and type — RAMSAY completes RAMSAY ROAD, RAMSAY STREET and the rest. Events: getaddressau-typeahead-suggestions and getaddressau-typeahead-selected (event.value).

Checking a whole address: validate()

For an address that arrives on one line — pasted, imported, or typed into a single box — validate() confirms it against G-NAF. It is a promise, not a widget.

const result = await getAddressAu.validate('3/12 Chapel St, Melbourne VIC 3000', 'YOUR-DOMAIN-TOKEN');

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

Reverse geocoding: nearest()

The addresses nearest a point, nearest first, each with its distance in metres — for a map pin or a "use my location" button. top defaults to 1 (max 20) and radius to 0.2 km (max 1). One look-up when it finds an address; nothing in reach is an empty list and costs nothing.

const [here] = await getAddressAu.nearest(-33.8732, 151.2061, 'YOUR-DOMAIN-TOKEN', { top: 1, radius: 0.2 });

if (here) {
    console.log(here.address, here.distance);   // "456 KENT ST, SYDNEY NSW 2000", 7 — pass here.id to /get for the rest
}

Distance: distance()

Straight-line metres between two addresses or locations (their ids, in any mix) or two points ([latitude, longitude]). Free; it answers metres and never coordinates.

const metres = await getAddressAu.distance('GANSW721316793', 'GAVIC419664638', 'YOUR-DOMAIN-TOKEN');   // 716312

Frameworks

It attaches to an element, so it works with React, Vue, Svelte or plain HTML. Every field it writes dispatches input and change, so framework-bound state updates rather than silently keeping the old value. Call destroy() when your component unmounts.

Styling

The default stylesheet is injected once and is deliberately minimal. Override the custom properties:

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

Or pass inject_styles: false and write your own against .getaddress-au-autocomplete, .getaddress-au-autocomplete__item, .getaddress-au-autocomplete__item--selected and .getaddress-au-autocomplete__match.

Dark mode follows prefers-color-scheme unless you set data-gaau-theme="light" on the list.

Accessibility

The input is marked up as a combobox with an owned listbox, options are exposed with aria-selected, and the highlighted option is tracked with aria-activedescendant. Arrow keys move, Enter selects, Escape closes. Enter is only intercepted while an option is highlighted, so it still submits your form otherwise.

Development

npm install
npm run build

Then open test/index.html, paste a key, and try it.

Licence

MIT © getAddress()

The MIT licence covers the code only. Address data is G-NAF Core © Geoscape Australia, licensed under the Open G-NAF Core End User Licence Agreement, which forbids using it to generate or compile addresses for sending mail unless each is verified against another source. See the attribution page for the statement to show with it.