Getting started with the Australian address API

WattleAddr adds an address box to your website or app. As someone types, it suggests real Australian addresses. When they pick one, you get it back in separate fields: street, suburb, state, postcode and coordinates.

Step 1: Get an API key

1. Create an account. Go to the sign-up page. Enter your name, work email and a password, tick the box to accept the Terms, then press Create account. You start on the Free plan: 5,000 lookups a month, no card.

2. Create your first key. The console opens on your new workspace. Open API Keys in the left menu and press Create my first key.

3. Copy the key. You get a secret key in test mode, starting waddr_sk_test_. The console shows it once, under Copy your key now. Copy it somewhere safe. Test mode uses the real address data. It costs nothing and does not count against your 5,000 monthly lookups. It works for the first 15 days of your account.

The key then appears in your list. Only its first few characters are shown from now on.

Which key do I need?

To pick the key yourself, press Choose the options myself (or + New API key once you have one). Choose:

• Secret (server) for code that runs on your server. Never put a secret key in a web page or a public repository.
• Publishable (browser) for code that runs in a web page. A live publishable key must list the domains it may run on.
• Live or Test. Test keys stop after the 15-day test period. Live keys work on every plan, including Free. The one exception is the suburb and postcode API, which needs a paid plan on a live key.

Step 2: Try it without code

Open the interactive reference. It needs no key. Type an address and you see the request and the JSON that comes back. Click a suggestion to fetch its full record.

You can also take the OpenAPI 3.1 spec or the Postman collection into your own tools.

Step 3: Add it to your site

In the browser, use a publishable key (waddr_pk_…). In the console, press Choose the options myself or + New API key, pick Publishable (browser), and list your website’s domain. Test mode is fine while you build.

The widget and the React component handle the session for you. With the headless client, create one with createSession() and pass it to each call. All the keystrokes behind one address count as a single lookup.

Option A: the browser widget (one script tag)

No build step and no dependencies. Paste this into your page, with your publishable key in place of waddr_pk_live_….

As someone types, the widget shows suggestions under the box:

When they pick one, onSelect gets the full address. In this example page, onSelect copies a.components into separate fields:

Option B: the npm packages (React or Node)

Official, typed, MIT-licensed packages. Use @wattleaddr/react for React. Use @wattleaddr/js (no dependencies) for plain JavaScript or server-side Node.

The React component drops into any form:

Or use the client with no UI. It runs in the browser and in Node 18+. On a server, set keyTransport: 'header' so a secret key is sent as a Bearer token and not in the URL:

Worked examples: a React form, a Next.js App Router form and a checkout with the widget.

Step 4: Get the full address from your server (about 5 minutes)

This is what the widget does for you, as two plain HTTPS calls. Use it from a server, or try it in a terminal with curl. Replace YOUR_KEY with your secret key.

a. Ask for suggestions as someone types

Pick any unique string as the session. Reuse it for every request about this one address. Suggestions start from three characters. Autocomplete keystrokes are fair use and are not billed on their own.

The -H line sends your key in the Authorization header. A secret key is always sent that way. In the response, id is the address’s identifier in G-NAF, the national address dataset (see Words we use). formatted is the text to show in your list. score only ranks suggestions within this one response, and you can ignore it. Show the list and let the person pick one.

b. Retrieve the one they picked

Use the same session. This is the charged call. One session is one lookup, however many keystrokes it took.

Here is a live call in the interactive reference:

c. What you were charged

Nothing, on a test key. That is what "billed": false and "test": true mean. On a live key the same two calls use exactly one lookup, for the retrieve, and billed comes back true. The keystrokes are not billed because they shared the session. If you leave the session out, every retrieve is charged on its own.

On a plan with a quota, every successful response also carries X-WattleAddr-Quota-Limit and X-WattleAddr-Quota-Remaining headers. On a live key you can watch your monthly allowance drop by one.

d. Save the address

Store id, formatted and components together. Ids can change between G-NAF releases, so never keep the id on its own. There is a schema to copy in how to store an Australian address. The address format checker shows how a messy address splits into these fields.

Before you go live: create a Live key. Test keys stop working after the test period with 402 test_mode_expired. Live keys work on every plan, including Free. The one exception is the suburb and postcode API, which needs a paid plan on a live key.

Step 5: What you pay, limits and errors

You pay per lookup. Send the same session with each autocomplete keystroke and the final retrieve, and the whole session counts as one lookup. Autocomplete on its own is not billed. A retrieve or verify with no session is always charged, so always send one. A verify that finds no match is not charged. Suburb and postcode search is billed differently. See Suburb, state and postcode.

Plan allowances and prices are on the pricing page. When the monthly quota is used up, the Free plan, plans bought through the Shopify app, and a paid plan you have cancelled return 402 quota_exceeded on charged calls. Other paid plans keep working and bill overage at the rate on the pricing page, up to a ceiling where they also return 402.

Rate limits and speed

Each key has a requests-per-second limit set by its plan. A key can send that many requests at once, then continue at that rate. Over it, the API returns 429 rate_limited with a Retry-After header saying how many seconds to wait. Nothing is queued. A refused request is not counted or charged.

There is no separate concurrency limit. Parallel requests are fine within the per-second rate. Each key has its own limit, so use one key per system. If one system needs more than its plan’s rate, talk to us instead of spreading it across keys. Limits above the published ones are set by agreement. Test keys have a separate, smaller allowance. Monthly volume is set by the plan’s quota (above).

Speed. Measured inside the API in September 2026: autocomplete about 65 ms at the median and about 225 ms at the 95th percentile. Verify takes 35 to 100 ms once a query is warm, and up to about 600 ms on the first call for a large block of units. A fresh HTTPS connection from within Australia adds roughly 50 to 90 ms, and a reused one about 45 ms, so keep connections open. Repeated prefixes are served from an in-memory cache. Live availability and the G-NAF release being served are on the status page.

How it runs. The full G-NAF release is loaded into OpenSearch by the open-source Addressr loader, which we host. Our API queries it directly: the exact query first, and a spelling-tolerant one only when that finds nothing. The same API handles keys, metering, scoring and the corrections described below. Keys, usage and billing are in Postgres. Sydney is primary and Melbourne is a warm standby. Quarterly G-NAF releases are loaded in place with no downtime.

Common errors

Every error is JSON: { "error": { "code", "message", "docs" } }. Switch on code, which does not change. The message may change. The docs link points at the matching row of the full error reference, which lists every code. These are the ones you are most likely to see first:

Not an error: 200 with "suggestions": [] and a notice. See PO Boxes below.

Reference

Keys and authentication

There are two key types, both created in the console. Never expose a secret key in the browser.

Either type can be made in test mode (waddr_sk_test_…, waddr_pk_test_…). Test keys use real data, are never charged, and work for the first 15 days of an account. Responses from a test key carry "test": true.

Keys are how your application signs in. How your team signs in to the console is separate. On Enterprise plans you can connect the console to your own identity provider over OpenID Connect, and require it. See single sign-on setup.

Endpoints

Base URL https://api.wattleaddr.com.au/v1. JSON only. Australian addresses only.

Every parameter and response schema is in the interactive reference.

Verify an address you already hold

There is a plain-language overview of verification, and what it is not, on the verification page.

verify takes free text you already hold. It returns the best match in its official G-NAF form, plus an assessment of how well it answers what you sent. Branch on verdict.

elements gives every field its own status (verified, changed or missing). A checkout can then ask again for the one wrong field, not the whole address. match_level says how precisely we identified it: subpremise a unit, premise a building, thoroughfare the street only, locality the suburb only. It is independent of the verdict. When you supply no unit or level, verify prefers the building over its units. Supply the unit to get subpremise.

We publish no accept or reject score threshold. The right line depends on what a wrong address costs you. The older top-level confidence field on a verify response is deprecated. Branch on verdict. A verified address exists in G-NAF and we know where it is. That is not a promise that mail can be delivered to it. There is a worked example of verifying on the server, without paying twice, in the Next.js guide.

Typos, misspellings and units

Matching is fuzzy but not phonetic. A word of three to five letters may have one character wrong, missing, extra or swapped. A longer word may have two. A word of one or two letters must be exact. That applies to the street name and the suburb alike, with one exception: the last word typed is treated as a prefix and gets no tolerance. So 589 Beems Rd Carseldine and 589 Beams Rd Carsledine QLD both find 589 Beams Rd, but a suburb misspelt at the very end of the query matches nothing on its own.

When nothing matches, the search is retried with something dropped. Verify reports what it discarded in dropped_tokens and scores the match lower. The street number goes first if the street and suburb you named exist and only the number does not. You then get the numbers that street does hold, nearest yours, with a street_number_not_found notice. Verify refuses that match and does not answer with a different number. Otherwise the trailing words (suburb, state, postcode) are dropped one at a time. A retry is never answered in a state or postcode your query contradicts. Suggestions appear once the query names a street or suburb. A bare unit, level or small street number on its own returns an empty list.

Verify never corrects a street number. A number that disagrees with the record is marked changed, not swapped. If the number had to be discarded to find anything at all, verify refuses. It will not answer about the house next door.

Autocomplete is looser, in this order. A one- or two-digit number is matched exactly, so if no premise carries it the suggestions are sub-dwellings that do (8 Beams Rd returns Unit 8 of the blocks on Beams Rd). A number of three or more digits gets the same one-character tolerance as a word, which can bring up a neighbour. Only when neither finds anything does the number itself get dropped. That means the street and suburb exist but that number is not in G-NAF. You then get that street’s real numbers, nearest yours, with a street_number_not_found notice saying so. When you type a number and no unit, the premise with that number on that street comes before anybody’s units. A building normally comes before its own units, even when the block is large. Type the unit (3/589, unit 3 589) to get the unit.

Verify tells you what it changed. elements marks each part verified, changed or missing. changed_elements lists the corrected ones, and the corrected values are in match.components. A corrected street name lowers match_score and gives an unverified or ambiguous verdict, never verified. So a misspelt street reaches you as the right record flagged for review, not as an automatic accept. A building address on a block with units matches the building with an ambiguous verdict and some of its units in alternatives.

PO Boxes & postal addresses

PO Boxes are not supported, because G-NAF holds physical addresses only. It has no PO Boxes, GPO Boxes, Locked Bags or Private Bags. A query for one returns 200 with an empty suggestions array and a notice. Your form can then ask for a street address, or take the PO Box in a separate field. verify returns the same notice with matched: false and billed: false. A query the dataset cannot answer is never charged. To validate PO Boxes you need a product licensed for Australia Post’s PAF. AMAS and PAF vs G-NAF explains the difference.

Suburb, state and postcode

Three endpoints suggest suburbs and postcodes as someone types, and check that a suburb, state and postcode belong together. You can use them instead of building your own postcode list. They are included on Starter, Growth and Enterprise with a live key. On Free, test keys can use them during your account’s first 15 days. There is a shorter overview on the postcode API page.

This is an example. The id is made up, and real ids can change between G-NAF releases. A query of digits only searches postcodes. state and limit are optional. session is required, and without it you get 400 bad_request. Each suggestion already holds the suburb, state and postcode, so you do not need a second call to read them. Suburb search forgives a typo, but only when the first letter is right.

A suggestion carries the suburb, state and postcode, so filling a form needs no second call. There is no SDK helper for suburbs and postcodes, so call the endpoint with fetch. Use a publishable key in the browser, and one session for each search box.

How suburb and postcode lookups are billed

• One suburb search session is one lookup. It is billed the first time the session returns at least one suggestion, whether or not anything is selected.
• This is different from addresses, where an abandoned address search is not billed.
• A search that returns no suggestions is not billed. Keystrokes within a session are fair use.
• Retrieving or verifying in a session billed within the last hour is not billed again. Verify is billed only when match is not null.
• A billed suburb lookup costs the same as an address lookup and uses the same monthly quota.
• With a publishable key, each new session that returns a suggestion is billed, so use one session per search box and keep it for the whole search.

If you get a 402

A live key on the Free plan gets 402 feature_unavailable with the message “Nothing was charged. Suburb and postcode lookups need a paid plan on a live key. Test keys can use them during your account’s first 15 days.” A cancelled plan moves the workspace to Free when its paid period ends, and the same error appears from then. Treat a 402 as a signal to fall back to a free-text suburb field.

Verify a suburb, state and postcode

POST /v1/localities/verify takes at least two of suburb, state and postcode, and an optional session. It needs a secret key. A publishable key gets 403 forbidden_key_type. The response is { matched, billed, verdict, match, elements, alternatives }. match has the same shape as a retrieve response without billed, or is null. Each entry in elements is verified, changed or missing. “Canberra” on its own is ambiguous with match: null. With a postcode it is still ambiguous when more than one suburb at that postcode fits, and alternatives lists them. “Canberra City” with 2601 resolves to City.

What the data is

G-NAF has no postcode list. We build each suburb, state and postcode pair from the current G-NAF addresses that carry it. Suburb and postcode pairs are derived by WattleAddr from G-NAF address records.

• Postcodes are as recorded on G-NAF addresses and can differ from Australia Post’s.
• A postcode used only for PO Boxes, Locked Bags or large mail receivers is not included, because G-NAF holds physical addresses only.
• A suburb with no G-NAF addresses yet, such as a new estate, is not included.
• This is not Australia Post’s postcode list, and we never fill gaps from it.
• A verified suburb, state and postcode is not a check that mail can be delivered.

Show this attribution wherever you display the data: “Incorporates or developed using G-NAF © Geoscape Australia licensed by the Commonwealth of Australia under the Open Geo-coded National Address File (G-NAF) End User Licence Agreement.” If you change the pairs, say so, as set out under Attribution.

Building with a coding agent

If you use Claude Code, Cursor, Copilot or similar, give it our agent skill. It covers what an assistant otherwise gets wrong: session tokens and what they cost, which key belongs in the browser, PO Boxes not being in G-NAF, reading a verify verdict, and how to store the address components. It is one markdown file with no telemetry.

It also ships inside @wattleaddr/js, at node_modules/@wattleaddr/js/skills/wattleaddr/SKILL.md. An agent working in a project that already uses the SDK can find it without downloading anything.

Words we use

Data & privacy

Your end users’ input never goes to an offshore provider such as Google Places, and the request path stays onshore. The data-residency attestation has the detail.

Autocomplete queries, including suburb and postcode searches, and the addresses they match are recorded in a search log for each workspace, for usage, debugging and support. In the console you choose what it keeps:

You set how long logs are kept (7–365 days, by plan). Old query text is deleted automatically. You can also apply a privacy mode to logs already stored, in one click. Why hashing an address is pseudonymisation explains the difference. See the FAQ and Privacy Policy for detail.

Attribution

WattleAddr is built on the open Geocoded National Address File. The G-NAF licence requires attribution. Show this wherever you display address data:

Try every endpoint live in the interactive reference. Questions? hello@wattleaddr.com.au