Try the Australian address API, right here
Every call below hits the live WattleAddr API. You need no key and no signup. Edit the query to see the request and the JSON response. You can also load the OpenAPI spec into your own tools. Your own calls need a key: add Authorization: Bearer YOUR_KEY to each request shown here. The quickstart shows where a key comes from.
/v1/addresses/autocompletenever billed · call it on every keystrokeAll endpoints
7 endpoints, fully described in the OpenAPI 3.1 spec. Paste that URL into Swagger UI, Scalar, Stoplight or Postman, or run it through an OpenAPI client generator to scaffold an SDK in your language.
| Method | Path | Billed? | Purpose |
|---|---|---|---|
GET | /v1/addresses/autocomplete | No | Type-ahead suggestions for a partial query |
GET | /v1/addresses/{id} | Once per session | Full structured record for a chosen suggestion |
POST | /v1/addresses/verify | On a match | Match free-text to the best canonical address, with a per-field verdict |
GET | /v1/localities/autocomplete | Once per session, on the first suggestion | Suburb or postcode suggestions. Starter and above on live keys; Free has test keys only, during test mode |
GET | /v1/localities/{id} | Once per session, unless the session was billed within the last hour | One suburb, state and postcode pair |
POST | /v1/localities/verify | On a match, unless the session was billed within the last hour | Check that a suburb, state and postcode belong together (secret keys only) |
GET | /v1/status | No | Service health & current G-NAF release (no auth) |
Notices & errors
A notice explains a successful but empty or substituted result and is not an error. Error codes are stable and safe to switch on.
Notices
| Code | HTTP | Endpoints | What it means |
|---|---|---|---|
postal_address_unsupported | 200 | Autocomplete and verify | The query is for a PO Box, GPO Box, Post Office Box, Locked Bag or Private Bag. The result is empty (an empty suggestions array, or no match from verify) because G-NAF holds physical addresses only. Try one in the field above. |
street_number_not_found | 200 | Autocomplete only | The street and suburb matched, but there is no exact match for that number in the area searched. The suggestions are the nearest street numbers, nearest first. Show the person the list rather than taking the first one. Verify never substitutes: it declines the match. |
unit_not_found | 200 | Autocomplete only | The building matched in the place you typed, but there is no exact match for the unit, shop, suite or level number. The building’s own address leads the list, followed by other matches. Show the person the list rather than taking the first one. |
Errors
| Code | HTTP | What it means |
|---|---|---|
bad_request | 400 | The query (q) or address is under 3 characters, or over the length limit. For suburb and postcode search the minimum is 2 characters, and session is required. Suburb verify needs at least two of suburb, state and postcode. |
invalid_key | 401 | The key is wrong, has been revoked, or has a typo. |
unauthorized | 401 | No API key was sent. |
feature_unavailable | 402 | The endpoint is not included in the workspace’s plan. Today that means a live key on the Free plan calling the suburb and postcode API. Nothing was charged. |
quota_exceeded | 402 | This month’s lookups are used up and your plan does not run over (Free, Shopify, a cancelled plan, or a paid plan with a spending cap set at your request), or a paid plan has reached the overage ceiling of five times its included lookups. The message says which. |
test_mode_expired | 402 | A test key was used after the free test period (15 days from account creation). |
forbidden_ip | 403 | A secret key was used from an IP address that is not on its allowed list. |
forbidden_key_type | 403 | A publishable (browser) key was used to call verify (address or suburb). Publishable keys can only call autocomplete and retrieve. |
forbidden_referrer | 403 | A publishable key was used from a domain that is not on its allowed list. |
not_found | 404 | No address, suburb or postcode pair has that id. |
rate_limited | 429 | Too many requests per second on one key. |
engine_unavailable | 503 | The suburb and postcode data is not loaded on this server. Nothing was charged. |
For 429, wait for the Retry-After header before retrying. Full causes and fixes are on the error codes page. The response schemas are in the spec.
Prefer a written walkthrough? See the quickstart. Questions? hello@wattleaddr.com.au