JavaScript Autocomplete

Add as-you-type New Zealand 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-nz-autocomplete

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

Usage

<label for="address">Address</label>
<input id="address" type="text">

<label for="flat">Flat or unit</label>
<input id="flat" type="text">

<label for="number">Street number</label>
<input id="number" type="text">

<label for="road">Road</label>
<input id="road" type="text">

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

<label for="town_city">Town or city</label>
<input id="town_city" type="text">

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

<script>
    getAddressNz.autocomplete('address', '{your-domain-token}', {
        output_fields: {
            flat_number: 'flat',
            number_first: 'number',
            full_road_name: 'road',
            locality_name: 'suburb',
            town_city: 'town_city',
            postcode: 'postcode'
        }
    });
</script>

From npm:

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

autocomplete('address', '{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-nz-autocomplete-suggestions', e => console.log(e.suggestions));
input.addEventListener('getaddress-nz-autocomplete-suggestion-selected', e => console.log(e.suggestion));
input.addEventListener('getaddress-nz-autocomplete-address-selected', e => console.log(e.address));
input.addEventListener('getaddress-nz-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 picked address's one-line label 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.
postcode	–	Restrict to one postcode.
report_postcode_edits	false	Report a postcode the visitor changes — see below.
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: id, address_id, address_label, address_status, flat_number, number_first, number_last, number_suffix, full_road_name, locality_name, town_city, territorial_authority, postcode and postcode_source — plus latitude and longitude. Every field is present on every address, and empty when the address has no value for it.

For 2/12 East Street, Auckland Central, Auckland 1010, flat_number is "2", number_first is "12", full_road_name is "East Street", locality_name is "Auckland Central", town_city is "Auckland" and postcode is "1010". A range such as 48-56 Queen Street has "48" in number_first and "56" in number_last.

Postcodes are unofficial and wrong for roughly 5 addresses in 100; postcode_source says how each one was assigned. Some addresses have no postcode, and postcode is then empty.

Reporting postcode edits

Set report_postcode_edits: true and, when a visitor picks an address and then changes the postcode the widget filled into output_fields.postcode, the widget reports the new postcode. It is off by default. A report is sent when the form is submitted, or, for a field outside a form, when the field changes; only a different four-digit postcode is reported. Reports are free and never interrupt the page if they fail. See Postcode correction for how reports are applied.

getAddressNz.autocomplete('address', '{your-domain-token}', {
    output_fields: { postcode: 'postcode' /* , … */ },
    report_postcode_edits: true
});

Styling

.getaddress-nz-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 getAddressNz.validate('169 Lambton Quay, Wellington Central, Wellington 6011', '{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 getAddressNz.nearest(latitude, longitude, '{your-domain-token}');

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

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