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-nz-api

Usage

Autocomplete

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

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. 1131927, 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('queen st', { filter: { town_city: 'Auckland', postcode: '1010' } });

Nearest

The addresses nearest a point, with their distance in metres — see the Nearest API.

const nearest = await api.nearest(-36.8441, 174.7672, 3, 0.5);   // one look-up
const closest = nearest.toSuccess().suggestions[0];
const metres = closest.distance;

Locations

Localities, towns and cities, and postcodes — see the Location API.

const locations = await api.locations('normanby');                     // 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(-39.5391, 174.2721, 3);          // one look-up
const metres = nearest.toSuccess().suggestions[0].distance;

Typeahead

Completes a locality, town or city, or postcode — see the Typeahead API. Free. Macrons are optional when typing.

const towns = await api.typeahead('hawera', { search: ['town_city'] });   // Hāwera

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

Validate

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

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 two points — see the Distance API. Free.

const between = await api.distance('1131927', '363752');   // 12 Queen Street, Auckland to 169 Lambton Quay, Wellington
const points = await api.distanceBetweenPoints([-36.8441, 174.7672], [-41.2828, 174.7760]);

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