Australian postcode and suburb lookup API
A suburb and postcode API answers two questions: which suburb or postcode did someone mean, and do this suburb, state and postcode belong together. WattleAddr builds its pairs from G-NAF. You get a suggestion list for a search box, and a check that marks each part that disagrees.
Search a suburb, or check a combination
Suburb and postcode search
Type part of a suburb name, or the start of a postcode. Each suggestion holds the suburb, state and postcode, so filling a form needs no second call.
Check a combination
Send at least two of suburb, state and postcode. The answer is verified, corrected, ambiguous or unverified, and each part is marked verified, changed or missing.
Mismatches are marked
When the parts do not belong together, each part that disagrees is marked changed. A single nearest match comes back in match, and several come back in alternatives.
Several fits are not guessed
When several suburbs fit, nothing is picked for you. The candidates are listed in alternatives, and the call is not billed.
Search for a suburb
-H "Authorization: Bearer YOUR_KEY"
"session": "demo-3",
"query": "north parra",
"suggestions": [{
"id": "NSW1234-2151",
"formatted": "North Parramatta NSW 2151",
"suburb": "North Parramatta",
"state": "NSW",
"postcode": "2151"
}]
}
This is an example, and the id is made up. session is required. A query of digits only searches postcodes. To check a combination, send POST /v1/localities/verify with two or more of suburb, state and postcode. The suburb, state and postcode section of the docs has the full response, the verdict table and a code example that fills a form.
Teams that keep their own postcode list
- Developers with a suburb picker or a postcode regex that has grown into a scraped list.
- Teams that want to catch a mismatched suburb and postcode in a form, a CRM import or a back-office check.
- Operations staff who need a state and postcode confirmed before a record is saved.
A regular expression can check that a postcode is four digits. It cannot check that it belongs to the suburb. The postcode validation post shows where the pattern stops and data starts.
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.
- A lookup costs the same as an address lookup and uses the same monthly quota. Suburb search requires a
session. - A verify call is billed only when it finds a match.
- Live keys need Starter, Growth or Enterprise. On Free, test keys work during your account’s first 15 days.
Prices are on the pricing page.
What the data is, and is not
G-NAF has no postcode list. WattleAddr builds each pair from the current G-NAF addresses that carry it.
- 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.
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.
Short answers
Is there an API for Australian postcodes?
Yes. WattleAddr has endpoints that suggest suburbs and postcodes as someone types, and one that checks a suburb, state and postcode together. The pairs are built from G-NAF, where postcodes are recorded on address records. There is no separate official postcode list in G-NAF, so WattleAddr derives each pair from the current addresses that carry it.
Can I check that a suburb matches its postcode?
Yes. Send at least two of suburb, state and postcode to the verify endpoint. It says whether they belong together. When the parts do not belong together, each part that disagrees is marked changed. A single nearest match comes back in match, and several come back in alternatives. If several suburbs share a postcode and your input does not pick one, the answer is ambiguous and it lists the candidates. Verify needs a secret key, so call it from your server.
Does it include PO Box postcodes?
No. 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 either.
Is it Australia Post’s postcode data?
No. It is not Australia Post’s postcode list, and gaps are never filled from it. Postcodes are as recorded on G-NAF addresses and can differ from Australia Post’s. A verified suburb, state and postcode is also not a check that mail can be delivered.
How is it billed?
One suburb search session is one lookup, billed the first time the session returns at least one suggestion, whether or not anything is selected. A lookup costs the same as an address lookup and uses the same monthly quota. A verify call is billed only when it finds a match. Live keys need Starter or above. Free accounts can use test keys during the first 15 days. The prices are on the pricing page.
What happens if my plan does not include it?
A live key on the Free plan gets a 402 error and nothing is charged. Treat that as a signal to fall back to a free-text suburb field. The same error appears once a cancelled plan ends and the workspace moves to Free.
Try a suburb search
Test keys work for your first 15 days. The docs show the whole flow.