Simple APIs for New Zealand Addresses
As-you-type autocomplete and full address look-ups, built on Toitū Te Whenua LINZ’s NZ Addresses — every address point in the country. Plus cleaning of whole spreadsheets of addresses.
Get started for freeShowing built-in sample results — the live API is not connected here.
Features
Up to date
Every address point in New Zealand, from LINZ NZ Addresses, kept up to date with LINZ’s releases.
99.9% Availability Guarantee
Independently monitored guaranteed uptime
Easy to use libraries
<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="town">Town or city</label>
<input id="town" type="text">
<label for="postcode">Postcode</label>
<input id="postcode" type="text"><script src="https://cdn.getaddress.io/scripts/getaddress-nz-autocomplete-2.0.0.js"></script>
<script>
getAddressNz.autocomplete('address_line_1', 'DOMAIN TOKEN',
{
output_fields: {
address_line_1: 'address_line_1',
address_line_2: 'address_line_2',
locality_name: 'suburb',
town_city: 'town',
postcode: 'postcode'
}
});
</script>Autocomplete
Autocomplete as they type
/autocomplete/{term} returns matching addresses with an id for each.
Suggestions are free and rate limited, so you can call it on every keystroke.
Resolve the one they picked
/get/{id} returns the full address with its geocode. This is the
only call that counts as a look-up against your plan.
- Every address in New Zealand, from LINZ
- Ranked near the visitor first
- An API key in the query string — no SDK required
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/maplibre-gl@5.24.0/dist/maplibre-gl.css">
<label for="location">Suburb or postcode</label>
<input id="location" type="text">
<div id="map" style="height: 380px"></div><script src="https://cdn.jsdelivr.net/npm/maplibre-gl@5.24.0/dist/maplibre-gl.js"></script>
<script src="https://cdn.getaddress.io/scripts/getaddress-nz-autocomplete-2.0.0.js"></script>
<script>
const map = new maplibregl.Map({
container: 'map',
style: 'https://tiles.openfreemap.org/styles/positron',
center: [134, -28],
zoom: 3
});
const marker = new maplibregl.Marker();
getAddressNz.location('location', 'DOMAIN TOKEN',
{
selected: place => {
const centre = [place.coordinates.longitude, place.coordinates.latitude];
marker.setLngLat(centre).addTo(map);
map.flyTo({ center: centre, zoom: 13 });
}
});
</script>Location
Suggest suburbs and postcodes
/location/{term} returns matching places — one per suburb, town and postcode.
Suggestions are free and rate limited.
Put the one they picked on a map
/get-location/{id} returns the place with its centre, ready for any map.
It counts as one look-up.
- Every suburb and town in New Zealand, with its postcode
- Nearest places to any point with
/nearest-location - Works with any map — no Google key needed
<button id="here" type="button">Use my location</button>
<label for="address">Address</label>
<input id="address" type="text"><script src="https://cdn.getaddress.io/scripts/getaddress-nz-autocomplete-2.0.0.js"></script>
<script>
document.getElementById('here').addEventListener('click', () => {
navigator.geolocation.getCurrentPosition(async position => {
const { latitude, longitude } = position.coords;
// The nearest address within 200 m: one look-up
const [nearest] = await getAddressNz.nearest(latitude, longitude, 'DOMAIN TOKEN');
document.getElementById('address').value = nearest
? nearest.address
: '';
});
});
</script>Reverse
Send a point
/nearest/{latitude}/{longitude} takes a latitude and longitude — a map pin or a GPS fix.
Get the nearest addresses
Nearest first, each with its distance in metres and an id for /get. One look-up;
nothing nearby costs nothing.
- “Use my location” on any address form
- Buildings, not every flat and level in them
- Works from the browser with a domain token
<label for="suburb">Suburb</label>
<input id="suburb" type="text">
<label for="town">Town or city</label>
<input id="town" type="text">
<label for="postcode">Postcode</label>
<input id="postcode" type="text"><script src="https://cdn.getaddress.io/scripts/getaddress-nz-autocomplete-2.0.0.js"></script>
<script>
const token = 'DOMAIN TOKEN';
getAddressNz.typeahead('suburb', token, { search: 'locality' });
getAddressNz.typeahead('town', token, { search: 'town_city' });
getAddressNz.typeahead('postcode', token, { search: 'postcode' });
</script>Typeahead
Complete any field as it is typed
/typeahead/{term} completes a suburb, town or postcode and returns plain
values, not addresses.
Narrow it only if you choose to
Each field stands alone, as the boxes here do. Pass a suburb, town or postcode
filter when you want the values held to one place.
- Free — rate limited, never counts as a look-up
- Every suburb, town and postcode in the LINZ data
- Works on forms you already have
<form id="check">
<label for="address">Address</label>
<input id="address" type="text">
<button>Validate</button>
</form>
<p id="result"></p><script src="https://cdn.getaddress.io/scripts/getaddress-nz-autocomplete-2.0.0.js"></script>
<script>
document.getElementById('check').addEventListener('submit', async e => {
e.preventDefault();
const line = document.getElementById('address').value;
const result = await getAddressNz.validate(line, 'DOMAIN TOKEN');
const out = document.getElementById('result');
if (result.status === 'found') {
out.textContent = result.address.address_label; // one look-up
} else if (result.status === 'ambiguous') {
out.textContent = result.candidates.length + ' possible addresses'; // free
} else {
out.textContent = 'No such address'; // free
}
});
</script>Validate
Send an address on one line
/validate/{address} reads the unit, number, road, suburb, town and postcode
however they are written.
Get the one address, or be told it isn't one
One match comes back as the full address. Several come back as ids, none as a 404 — never a best guess.
- Only a found address counts as a look-up
- Units, number suffixes and number ranges
- Clean up imported or pasted addresses
Clean a spreadsheet of addresses
Upload a CSV of customer, supplier or member addresses and get the same file back with every row matched to LINZ — the corrected address, its parts, its postcode, its LINZ address id and coordinates.
- Messy columns are fine — we work out which ones hold the address
- Free preview of the first 50 rows before you pay anything
- No guesses: a row is only matched when one address fits
- $2.00 per 1,000 matched addresses — rows that don't match are refunded
- Files up to 200 rows free every day, on every plan
- Up to 100,000 rows a file; deleted after 7 days
| Addr Ln 1 | City | ga_status | ga_address |
|---|---|---|---|
| 12 queen st, auckland central | auckland | matched | 12 Queen Street, Auckland Central, Auckland 1010 |
| 169 Lambton Qy | wellington | matched | 169 Lambton Quay, Wellington Central, Wellington 6011 |
| 12 Queen St | auckland | ambiguous | 2 candidates |
Add-ons
Optional extras, switched on per subscription from your console.
Google Places fallback
FreeWhen an address search finds nothing in the LINZ data, the autocomplete widget searches Google for businesses and places instead — using your own Google API key.
- No charge from us, and Google results never count as look-ups
- Addresses still come from LINZ; Google only fills the gaps
- No code changes — switch it on in your console
FAQ
- Autocomplete queries are rate limited but do not increase your usage.
- Resolving an autocomplete suggestion to a full address counts as 1 look-up.
Postcodes are not part of the LINZ data. Ours come from the open_nz_postcodes project (CC0): they are unofficial, not NZ Post’s, and are wrong for about 5% of addresses. Every address says how its postcode was assigned (
postcode_source), and you can tell us when one is wrong.
Contains data sourced from the LINZ Data Service licensed for reuse under CC BY 4.0.