getAddress.Au.Sdk 1.7.0

getAddress.Au.Sdk

.NET client for the getAddress() Australian address API — every address in Australia, from G-NAF. The same shape as the UK getAddress.Sdk.

dotnet add package getAddress.Au.Sdk

Targets .NET Standard 2.0 and .NET 8.

Register

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

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(GetAddressAu.Api api)
{
    var autocompleteResult = await api.Autocomplete("200 george 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;     // "200 George Street, Sydney NSW 2000"
                var suburb = address.LocalityName;
                var state = address.State;
                var postcode = address.Postcode;
            }
        }
    }
    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 G-NAF address_detail_pid — store it and pass it to Get(id) later.

Filter

var result = await api.Autocomplete("george st", new GetAddressAu.AutocompleteOptions
{
    Filter = new GetAddressAu.AutocompleteFilter { State = "NSW", Postcode = "2000" },
});

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(-33.8612, 151.2107, 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

Companies

Australian businesses from the Australian Business Register, by name, ABN or ACN. Suggestions are free and rate limited; the record counts one look-up. There is no street address in the register's free data.

var companies = await api.Companies("bbc hardw", top: 5, state: "VIC");   // free, rate limited
var suggestion = companies.Success.Suggestions[0];                       // "BBC HARDWARE LIMITED", ABN 11000003378

var company = await api.Company(suggestion);                             // one look-up
var record = company.Success;                                            // Name, Acn, EntityType, GstRegistered, OtherNames …

var byAcn = await api.Company("000 003 378");                            // an ABN or ACN, spaces allowed

A number that fails its check digit (400) or is not on the register (404) is a Failure and costs nothing.

Locations

Suburbs, states and postcodes — one place per suburb + state + postcode, each with its centre.

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

if (locations.IsSuccess)
{
    var suggestion = locations.Success.Suggestions[0];    // "NORTHBRIDGE NSW 2063"
    var place = await api.GetLocation(suggestion);        // one look-up

    var centre = place.Success.Coordinates;               // -33.8102, 151.2160
}

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

A location id such as northbridge-wa-6003 is the same in every G-NAF release, so it is safe to store.

Typeahead

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

var suburbs = await api.Typeahead("bon");           // ["BONDI JUNCTION", "BONDI BEACH", "BONDI", …]

var streets = await api.Typeahead("pi", new GetAddressAu.TypeaheadOptions
{
    Search = new() { GetAddressAu.TypeaheadOptions.Fields.Street },
    Filter = new GetAddressAu.TypeaheadFilter { Locality = "SYDNEY" },
});                                                 // ["PIER STREET", "PITT STREET"]

Validate

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

var result = await api.Validate("3/12 Chapel St, Melbourne VIC 3000");

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

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("GANSW721316793", "GAVIC419664638");   // 716312 m
var places = await api.Distance("sydney-nsw-2000", "melbourne-vic-3000");  // 713306 m
var points = await api.Distance(-33.8612, 151.2107, -33.8605, 151.2073);
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<GetAddressAu.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 G-NAF Core © Geoscape Australia, licensed under the Open G-NAF Core End User Licence Agreement, which forbids using it to generate or compile addresses for sending mail unless each is verified against another source. See the attribution page for the statement to show with it.