.NET SDK

.NET SDK for autocomplete, full address look-up and usage. Targets .NET Standard 2.0 and .NET 8.

Install

dotnet add package getAddress.Nz.Sdk

Dependency Injection

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

The admin key is only needed for usage. Keep both keys on your server — browser code uses a domain token.

Autocomplete

Autocomplete and get address.

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;
                var town = address.TownCity;
                var postcode = address.Postcode;      // unofficial; see PostcodeSource
                //....
            }
        }
    }
    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, so it is safe to store and pass to api.Get(id) later.

Filter

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

Nearest

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

var nearest = await api.Nearest(-36.8441, 174.7672, top: 3, radius: 0.5);   // one look-up
var closest = nearest.Success.Suggestions[0];
var metres = closest.Distance;

Locations

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

var locations = await api.Locations("normanby");        // free, rate limited
var place = await api.GetLocation(locations.Success.Suggestions[0]);   // one look-up
var centre = place.Success.Coordinates;                // Normanby, Hāwera 4614

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

Typeahead

Completes a locality, town or city, or postcode — see the Typeahead API. Free. 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 …

Validate

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

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

if (result.Success.Status == GetAddressNz.ValidateStatus.Found)
{
    var address = result.Success.Address;        // as Get returns it
}
else if (result.Success.Status == GetAddressNz.ValidateStatus.Ambiguous)
{
    var ids = result.Success.Candidates;         // Get(id) each
}

Distance

Straight-line metres between two addresses or two points — see the Distance API. Free.

var between = await api.Distance("1131927", "363752");   // 12 Queen Street, Auckland to 169 Lambton Quay, Wellington
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));

Without Dependency Injection

var api = new GetAddressNz.Api(new HttpClient(), new GetAddressNz.ApiKeys("{your-api-key}"));