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

Node.js

Node.js library for autocomplete, full address look-up and usage. No dependencies; Node 18 or later.

Installation

npm install getaddress-au-api

Usage

Autocomplete

import Client from 'getaddress-au-api'

const api = new Client("{your-api-key}");

const autocompleteResult = await api.autocomplete('200 george st');

if (autocompleteResult.isSuccess)
{
    const success = autocompleteResult.toSuccess();

    for (const suggestion of success.suggestions)
    {
        const getResult = await api.get(suggestion.id);

        if (getResult.isSuccess)
        {
            const address = getResult.toSuccess();
            console.log(address.address_label, address.locality_name, address.state, address.postcode);
        }
    }
}
else
{
    const failed = autocompleteResult.toFailed();
    console.log(failed.status, failed.message);
}

Autocomplete is free and rate limited. Each successful get counts one look-up against your plan; a 404 costs nothing. A suggestion's id is the address's G-NAF address_detail_pid, so it is safe to store and resolve later. Keep your key on your server — browser code uses a domain token with JavaScript Autocomplete.

Filter

const result = await api.autocomplete('george st', { filter: { state: 'NSW', postcode: '2000' } });

Locations

Suburbs, states and postcodes — see the Location API.

const locations = await api.locations('northb');                       // free, rate limited
const place = await api.getLocation(locations.toSuccess().suggestions[0]);   // one look-up
const { latitude, longitude } = place.toSuccess().coordinates;

const nearest = await api.nearestLocations(-33.8612, 151.2107, 3);          // one look-up
const metres = nearest.toSuccess().suggestions[0].distance;

Typeahead

Completes a suburb, postcode, street or state — see the Typeahead API. Free.

const suburbs = await api.typeahead('bon');     // BONDI JUNCTION, BONDI BEACH, BONDI …

const streets = await api.typeahead('pi', { search: ['street'], filter: { locality: 'SYDNEY' } });   // PIER, PITT

Validate

Confirms a one-line address — see the Validate API. One look-up only when found.

const result = await api.validate('12 Acland St, St Kilda VIC 3182');
const { status, address, candidates } = result.toSuccess();   // 'found' | 'ambiguous' | 'not_found'

Distance

Straight-line metres between two addresses or two points — see the Distance API. Free.

const between = await api.distance('GANSW721316793', 'GAVIC419664638');   // { metres: 716312 }
const points = await api.distanceBetweenPoints([-33.8612, 151.2107], [-33.8605, 151.2073]);

Failures

Errors the API reports and network failures are results, never thrown. status is the HTTP status (0 when no response arrived), message says what went wrong, and a 429 carries retryAfterSeconds. 

if (!result.isSuccess && result.toFailed().isRateLimited)
{
    const wait = result.toFailed().retryAfterSeconds ?? 60;
}

Usage

const api = new Client("{your-api-key}", "{your-admin-key}");

const today = await api.usage();
const oneDay = await api.usage(1, 9, 2026);
const range = await api.usageRange(new Date('2026-09-01'), new Date('2026-09-14'));
Top