getaddress-au-api

Node.js client for the getAddress() Australian address API — every address in Australia, from G-NAF. The same shape as the UK getaddress-api package. No dependencies; Node 18+.

npm install getaddress-au-api

Usage

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);
}

CommonJS works too: const { Client } = require('getaddress-au-api');

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 — store it and pass it to get later.

Keep your key on your server. Browser code uses a domain token with getaddress-au-autocomplete.

Filter

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

Nearest

The addresses nearest a point, nearest first, each with its distance in metres. Counts one look-up when it finds an address; nothing within the radius costs nothing.

const nearest = await api.nearest(-33.8612, 151.2107, 3, 0.5);     // radius in km, at most 1
const closest = nearest.toSuccess().suggestions[0];
const metres = closest.distance;
const address = await api.get(closest);                              // one more look-up

Locations

Suburbs, states and postcodes — one place per suburb + state + postcode, each with its centre.

const locations = await api.locations('northb');              // free, rate limited
const suggestion = locations.toSuccess().suggestions[0];      // "NORTHBRIDGE NSW 2063"

const place = await api.getLocation(suggestion);              // 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;

A location id such as northbridge-wa-6003 is the same in every G-NAF release, so it is safe to store.

Typeahead

Completes a partly typed suburb, postcode, street or state as plain strings. Free and rate limited.

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

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

Validate

Confirms a one-line address. One look-up only when it finds the address.

const result = await api.validate('3/12 Chapel St, Melbourne VIC 3000');
const { status, address, candidates } = result.toSuccess();   // 'found' | 'ambiguous' | 'not_found'

Distance

Straight-line metres between two addresses or locations (by id, in any mix) or two points. Free and rate limited.

const between = await api.distance('GANSW721316793', 'GAVIC419664638');        // { metres: 716312 }
const places = await api.distance('sydney-nsw-2000', 'melbourne-vic-3000');       // { metres: 713306 }
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 reports

Pass your admin key as the second argument:

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'));

Options

new Client('your-api-key', 'your-admin-key', {
    baseUrl: 'https://api.getaddress.io', // the API origin
    timeoutMs: 30000,                     // 0 for no timeout
    fetch: customFetch                    // defaults to the global fetch
});

Local development

Point baseUrl at a locally running API over plain HTTP:

const api = new Client('your-dev-api-key', 'your-dev-admin-key', { baseUrl: 'http://localhost:5255' });

Use HTTP, not https://localhost:7166: Node does not accept the ASP.NET development certificate (a self-signed end-entity certificate), even when your machine trusts it. The local API serves HTTP without redirecting in Development. Keys from a local run only work locally.

Development

npm install
npm test

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.