getaddress-nz-api

Node.js client for the getaddress NZ address API — every address in New Zealand, from LINZ's NZ Addresses, with free, unofficial postcodes. No dependencies; Node 18+.

npm install getaddress-nz-api

Usage

import Client from 'getaddress-nz-api';

const api = new Client('your-api-key');

const autocompleteResult = await api.autocomplete('12 queen 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.town_city, address.postcode);
        }
    }
} else {
    const failed = autocompleteResult.toFailed();
    console.log(failed.status, failed.message);
}

CommonJS works too: const { Client } = require('getaddress-nz-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 LINZ address_id, e.g. 363752 — store it and pass it to get later.

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

The address

get returns every field as a string, empty when the address has no value for it:

const address = (await api.get('363752')).toSuccess();
// {
//   id: '363752', address_id: '363752',
//   address_label: '169 Lambton Quay, Wellington Central, Wellington 6011',
//   address_status: 'current',
//   flat_number: '', number_first: '169', number_last: '', number_suffix: '',
//   full_road_name: 'Lambton Quay',
//   locality_name: 'Wellington Central', town_city: 'Wellington', territorial_authority: 'Wellington City',
//   postcode: '6011', postcode_source: 'road',
//   coordinates: { latitude: -41.2828093667, longitude: 174.7759540167 }   // WGS84
// }

Postcodes are unofficial (from the open_nz_postcodes project, not NZ Post's) and wrong for roughly 5 addresses in 100. postcode_source says how each was assigned: road, suburb (single), suburb (majority) (lower confidence), none (postcode is empty), or, from customers' corrections, corrected and corrected (road).

Filter

const result = await api.autocomplete('12 queen st', { filter: { town_city: 'Auckland', postcode: '1010' } });

The filter also takes locality (a suburb, e.g. Ōtāhuhu) and a radius. Macrons are optional when typing: "otahuhu" finds Ōtāhuhu.

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(-41.2828, 174.776, 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, towns and postcodes — one place per suburb + town + postcode, each with its centre.

const locations = await api.locations('norman');              // free, rate limited
const suggestion = locations.toSuccess().suggestions[0];      // "Normanby, Hāwera 4614"

const place = await api.getLocation(suggestion);              // one look-up
const { town_city, territorial_authority, coordinates } = place.toSuccess();

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

const inTown = await api.locations('norman', { filter: { town_city: 'Hāwera' } });

A location id is suburb|town|postcode, e.g. Normanby|Hāwera|4614; a place with no postcode ends in |. It is safe to store.

Typeahead

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

const places = await api.typeahead('ota');     // ["Ōtāhuhu", "Ōtara", …]

const suburbs = await api.typeahead('nor', { search: ['locality'], filter: { town_city: 'Hāwera' } });   // ["Normanby"]

search takes locality, town_city and postcode; filter takes the same three.

Validate

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

const result = await api.validate('2/12 East Street, Auckland Central, Auckland 1010');
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('363752', '1131927');                                // two addresses
const places = await api.distance('Wellington Central|Wellington|6011', '363752');     // a place and an address
const points = await api.distanceBetweenPoints([-41.2828, 174.776], [-36.8466, 174.7666]);

Postcode corrections

Report an address whose postcode is wrong — only what you or your user know first-hand, never a postcode copied from NZ Post products or its finder. Free, and limited to 100 reports a day per API key.

// suggestion: from autocomplete (or a stored address id); correctPostcode: what your customer told you
const report = await api.reportPostcode(suggestion, { postcode: correctPostcode, source: 'customer', note: 'returned mail' });
const { status, previous_postcode } = report.toSuccess();      // status: 'pending'

source is user (a person correcting their own address, the default) or customer (your own staff, e.g. from returned mail); note is optional, up to 200 characters. A 400 is a postcode that is not four digits or that no NZ address has; a 404 an unknown address id; a 409 an address that already has that postcode. A later report from your account on the same address replaces the earlier one.

Corrections are applied at a weekly run, not straight away. List your account's reports, newest first, to see where each stands — pending, applied, superseded or rejected:

const list = await api.postcodeCorrections(50);       // top: 1–200, default 50
for (const c of list.toSuccess().corrections) {
    console.log(c.address_id, c.previous_postcode, '→', c.postcode, c.status);
}

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.nz', // the API origin
    timeoutMs: 30000,                     // 0 for no timeout
    fetch: customFetch                    // defaults to the global fetch
});

Upgrading from 1.x

2.0.0 describes the New Zealand API: the address is LINZ's (address_id, full_road_name, town_city, territorial_authority, postcode_source), places carry town_city and territorial_authority, and the autocomplete, location and typeahead filters take town_city where they took a state. Typeahead completes locality, town_city and postcode.

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 NZ Addresses, from Toitū Te Whenua Land Information New Zealand. Sourced from the LINZ Data Service and licensed for reuse under the CC BY 4.0 licence. Postcodes are unofficial, from the open_nz_postcodes project (CC0), and are not NZ Post's.