getAddress.Nz.Sdk 1.1.0

getAddress.Nz.Sdk

.NET client for the getAddress() New Zealand address API — every address in New Zealand, from LINZ NZ Addresses. The same shape as the UK getAddress.Sdk.

dotnet add package getAddress.Nz.Sdk

Targets .NET Standard 2.0 and .NET 8.

Register

services.AddSingleton(new GetAddressNz.ApiKeys("your-api-key", "your-admin-key"));
services.AddHttpClient<GetAddressNz.Api>();

Calls go to https://api.getaddress.nz/ unless the HttpClient has a BaseAddress of its own. The admin key is only needed for usage. Keep both keys on your server; browser code uses a domain token.

Autocomplete and get

public async Task Autocomplete(GetAddressNz.Api api)
{
    var autocompleteResult = await api.Autocomplete("12 queen st");

    if (autocompleteResult.IsSuccess)
    {
        foreach (var suggestion in autocompleteResult.Success.Suggestions)
        {
            var getResult = await api.Get(suggestion);

            if (getResult.IsSuccess)
            {
                var address = getResult.Success;
                var label = address.AddressLabel;     // "12 Queen Street, Auckland Central, Auckland 1010"
                var locality = address.LocalityName;  // "Auckland Central"
                var town = address.TownCity;          // "Auckland"
                var postcode = address.Postcode;      // "1010"
            }
        }
    }
    else
    {
        var errorMessage = autocompleteResult.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 — store it and pass it to Get(id) later. An address LINZ has since withdrawn still resolves, with IsRetired true.

Postcodes

New Zealand's free address data has no postcodes, so Postcode is unofficial: assigned from open_nz_postcodes, not NZ Post. PostcodeSource says how it was assigned — road, suburb (single), suburb (majority) or none — and the last two are lower confidence. none leaves Postcode empty, and an address whose postcode was fixed from a reported correction says corrected or corrected (road). They are wrong for roughly 5 addresses in 100.

Report a wrong postcode

When you or your user know an address's postcode first-hand, report it. Free, and limited to 100 a day per API key. Corrections are applied at the weekly run, not straight away, so the answer is the correction, pending. Never copy postcodes from NZ Post products or its finder.

// 169 Lambton Quay, Wellington: the resident changed the filled-in postcode
var report = await api.ReportPostcodeCorrection("363752", new GetAddressNz.PostcodeCorrectionRequest
{
    Postcode = postcodeTheyTyped,                                      // four digits
    Source = GetAddressNz.PostcodeCorrectionRequest.Sources.Customer,   // your staff; User (the default) is the address's own resident
    Note = "returned mail",                                            // optional, up to 200 characters
});

if (report.IsSuccess)
{
    var status = report.Success.Status;                 // "pending"
    var before = report.Success.PreviousPostcode;       // the postcode the address had
}
else
{
    var status = report.Failed.Status;   // 400 bad postcode or note, 404 unknown id, 409 already has that postcode
}

One report per account per address: a later one replaces it. List your account's reports, newest first, with where each stands — pending, applied, superseded or rejected:

var mine = await api.PostcodeCorrections(top: 50);   // 1–200, 50 when not given
foreach (var correction in mine.Success.Corrections)
{
    var line = $"{correction.AddressId}: {correction.PreviousPostcode} → {correction.Postcode} ({correction.Status})";
}

Filter

var result = await api.Autocomplete("queen st", new GetAddressNz.AutocompleteOptions
{
    Filter = new GetAddressNz.AutocompleteFilter { TownCity = "Auckland", Postcode = "1010" },
});

The filter also takes Locality and a Radius. Values match as LINZ writes them, macrons included.

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.

var nearest = await api.Nearest(-36.8441, 174.7672, top: 3, radius: 0.5);   // radius in km, at most 1
var closest = nearest.Success.Suggestions[0];
var metres = closest.Distance;
var address = await api.Get(closest);                                       // one more look-up

Locations

Places — one per locality + town or city + postcode, each with its centre and territorial authority.

var locations = await api.Locations("normanby");          // free, rate limited

if (locations.IsSuccess)
{
    var suggestion = locations.Success.Suggestions[0];    // "Normanby, Hāwera 4614"
    var place = await api.GetLocation(suggestion);        // one look-up

    var council = place.Success.TerritorialAuthority;     // "South Taranaki District"
    var centre = place.Success.Coordinates;               // -39.53909, 174.272071
}

var nearest = await api.NearestLocations(-39.5391, 174.2721, top: 3);   // one look-up
var metres = nearest.Success.Suggestions[0].Distance;

A location id is the three names joined by |, e.g. Normanby|Hāwera|4614. It is the same in every LINZ release, so it is safe to store.

Typeahead

Completes a partly typed locality, town or city, or postcode as plain strings. Free and rate limited. Macrons are optional when typing.

var towns = await api.Typeahead("hawera", new GetAddressNz.TypeaheadOptions
{
    Search = new() { GetAddressNz.TypeaheadOptions.Fields.TownCity },
});                                                 // ["Hāwera"]

var localities = await api.Typeahead("n", new GetAddressNz.TypeaheadOptions
{
    Search = new() { GetAddressNz.TypeaheadOptions.Fields.Locality },
    Filter = new GetAddressNz.TypeaheadFilter { TownCity = "Hāwera" },
});                                                 // ["Normanby", …]

Without Search, localities, towns and postcodes are completed alike.

Validate

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

var result = await api.Validate("2/12 East Street, Auckland Central, Auckland 1010");

switch (result.Success.Status)
{
    case GetAddressNz.ValidateStatus.Found:     var address = result.Success.Address; break;
    case GetAddressNz.ValidateStatus.Ambiguous: var ids = result.Success.Candidates; break;   // Get(id) each
    case GetAddressNz.ValidateStatus.NotFound:  break;
}

A line with no locality or postcode, such as 12 Queen Street, is Ambiguous.

Distance

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

var between = await api.Distance("1131927", "363752");   // 12 Queen St, Auckland to 169 Lambton Quay, Wellington: about 494 km
var mixed = await api.Distance("1131927", "Normanby|Hāwera|4614");   // a place is measured from its centre
var points = await api.Distance(-36.8441, 174.7672, -41.2828, 174.7760);
var metres = between.Success.Metres;

Failures

Errors the API reports are results, not exceptions. Failed.Status is the HTTP status (0 when no response arrived), Failed.Message says what went wrong, and a 429 carries Failed.RetryAfterSeconds.

if (!result.IsSuccess && result.Failed.IsRateLimited)
{
    await Task.Delay(TimeSpan.FromSeconds(result.Failed.RetryAfterSeconds ?? 60));
}

Usage

var today = await api.Usage();
var oneDay = await api.Usage(1, 9, 2026);
var range = await api.Usage(new DateTime(2026, 9, 1), new DateTime(2026, 9, 14));

Local development

Set the HttpClient's BaseAddress to a locally running API (end it with a slash):

services.AddHttpClient<GetAddressNz.Api>(client => client.BaseAddress = new Uri("https://localhost:7166/"));

.NET trusts the ASP.NET development certificate, so HTTPS works; http://localhost:5255/ works too. Keys from a local run only work locally.

Licence

MIT © getAddress()

The MIT licence covers the code only. Address data is NZ Addresses from LINZ, licensed under Creative Commons Attribution 4.0 (CC BY 4.0): credit LINZ when you display or redistribute it. Postcodes come from open_nz_postcodes (CC0 1.0), are unofficial and are not NZ Post's.