Docs · Libraries

JavaScript autocomplete

One script tag adds as-you-type address completion to any form — Australia (G-NAF) and New Zealand (LINZ). No dependencies, no build step. Suggestions are free; resolving the address the user picks costs one credit.

Quick start

Mark up your form, then initialise the widget with a domain token (a browser-restricted API key).

<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://ipsofax.com/scripts/ipsofax-autocomplete-0.5.0.js"></script>

<script>
    ipsofaxAu.autocomplete('address_line_1', 'DOMAIN TOKEN',
    {
        output_fields: {
            address_line_1: 'address_line_1',
            address_line_2: 'address_line_2',
            locality_name: 'suburb',
            state: 'state',
            postcode: 'postcode'
        }
    });
</script>

Try it live on the libraries page.

New Zealand

Same fields, same code — swap the global. In New Zealand state does not exist, so that field is simply left untouched; postcodes are four digits.

ipsofaxNz.autocomplete('address_line_1', 'DOMAIN TOKEN',
{
    output_fields: {
        address_line_1: 'address_line_1',
        address_line_2: 'address_line_2',
        locality_name: 'suburb',
        postcode: 'postcode'
    }
});

Dedicated search box

Prefer a search box that completes the lines below it? Bind the widget to that input and choose what the box shows after selection:line1 (default), formatted, or clear.

// A dedicated search box above the address fields
ipsofaxAu.autocomplete('address_search', 'DOMAIN TOKEN', {
    search_display: 'formatted',   // show the full resolved label in the box
    output_fields: {
        address_line_1: 'address_line_1',
        address_line_2: 'address_line_2',
        locality_name: 'suburb',
        state: 'state',
        postcode: 'postcode'
    }
});

Postcode lookup

A structured alternative to type-ahead: one line of the 4-digit postcode + the first 3 letters of the street, with an optional premise or building — 2614BAN,2614BAN 2,2614BAN PRIMARY. Listing is free; resolving the chosen address costs 1 credit.

const { addresses } = await ipsofaxAu.postcodeLookup(
    '2614BAN 2', 'DOMAIN TOKEN', { limit: 25 });

for (const a of addresses) console.log(a.formatted);   // free

const picked = await ipsofaxAu.resolve(addresses[0].id, 'DOMAIN TOKEN');  // 1 credit

Reverse geocoding

nearest() returns the closest addresses to a point, nearest first with distance in metres. One credit when addresses come back; nothing nearby is free.

const { results } = await ipsofaxAu.nearest(
    -35.3081, 149.1244, 'DOMAIN TOKEN', { limit: 5 });

for (const a of results)
    console.log(a.distance_m + ' m', a.formatted);   // 1 credit

Options

Output fields

Keys on the left are what the widget writes; values are your form field ids or names. Fields a dataset does not have (e.g. state in NZ) are left untouched.

What is charged

• Typing (/v1/<dataset>/suggest) — free, rate limited.
• Selecting a concrete address (/v1/<dataset>/resolve) — 1 credit.
• Selecting a street/locality grouping — free; it just completes the label.

See what is a lookup? for the full model.

Accessibility & devices

The bound input is an ARIA combobox (listbox popup, active descendant). Keyboard: ↓/↑ to move, Enter to select, Esc to close. The dropdown is fixed-positioned so it survives scrollable layouts, and rows are full-width for touch.

Errors

Network or API errors are shown inside the dropdown; wire on_error to log or instrument them. Nothing throws into your page.

Versioning

The filename carries the version (ipsofax-autocomplete-0.5.0.js) so you can pin an exact build. New releases add new files; old URLs keep working.

Attribution

• AU results: “Incorporates or developed using G-NAF Core © Geoscape Australia”, licensed under the Open G-NAF Core EULA.
• NZ results: “NZ Addresses © Toitū Te Whenua LINZ” (CC BY 4.0).