Do Australian address APIs support PO Boxes?

21 July 2026 · 4 min read

It’s one of the first things you hit when you wire up address autocomplete on an Australian signup or checkout form: someone types “PO Box 123” and nothing comes back. That isn’t a bug in your integration — it’s a property of the underlying dataset, and it’s worth understanding so you can handle it deliberately.

G-NAF is a register of physical addresses

Almost every Australian address API — WattleAddr included — is built on the Geocoded National Address File (G-NAF), the authoritative national index maintained by Geoscape Australia. G-NAF records physical addresses: places with a street number, a street and a locality. It contains no PO Boxes, GPO Boxes, Locked Bags or Private Bags, because those are postal-delivery constructs owned by Australia Post, not physical locations.

So no G-NAF-based autocomplete can return a PO Box. The question isn’t which provider “supports” them — none do — it’s what the API does when someone asks for one.

An empty dropdown is the wrong answer

The lazy behaviour is to return nothing and let the user stare at a blank list, unsure whether they mistyped. Worse, some engines strip the “PO Box” tokens and surface an unrelated street address as if it were a match, which a rushed user may well accept.

WattleAddr detects these queries and returns a clear signal instead. The call still succeeds with a 200, an empty suggestions array, and a notice:

GET /v1/addresses/autocomplete?q=PO+Box+123+Parkes+NSW

{
  "suggestions": [],
  "notice": {
    "code": "postal_address_unsupported",
    "kind": "PO Box",
    "message": "PO Box addresses aren’t in the G-NAF dataset…"
  }
}

What to do in your form

• Watch for notice.code === "postal_address_unsupported" and show the message, so the field explains itself.
• Offer a separate “PO Box / postal address” field for people who genuinely post to one.
• Keep the physical-address autocomplete for the delivery or residential address.

verify behaves the same way: a PO Box returns matched: false, billed: false and the same notice — you’re never charged for a query the dataset structurally can’t answer. You can try it yourself in the interactive reference: type a PO Box into the live field and watch the notice come back.