Autocomplete
Use this guide to choose suggestion filters, handle typed input and ranked results, and build an address selection flow.
Choose filters
Address suggestions accept partial input from 3 to 50 characters. Locality suggestions accept 1 to 50 characters. Both return up to 5 suggestions by default, with maxNumberOfResults accepting 1 to 20.
Address datasets
Send dataset names in one comma-separated value, for example dataset=gnaf,gnaflive:
| Value | Data searched |
|---|---|
gnaf | G-NAF addresses |
gnaflive | G-NAF Live addresses |
mailAddress | Mailing addresses, including PO Boxes and RMB addresses |
all | All three datasets. This also applies when the parameter is omitted |
Dataset values are case-sensitive. addressType accepts physical, mailing, or all, with all as the default. An address can be both physical and mailing.
- Set
excludeAliases=trueto exclude address aliases. The default isfalse - Set
excludePrimaryWithSec=trueto exclude primary addresses with related secondary addresses. The default isfalse - Use the Addresses API when you need to assess a complete address match rather than offer autocomplete suggestions
State and postcode filters
Both suggestion endpoints accept stateTerritory as one comma-separated value, for example stateTerritory=NSW,QLD. Allowed abbreviations are ACT, NSW, NT, OT, QLD, SA, TAS, VIC, and WA.
- Address suggestions also accept
ALLfor no state restriction - For locality suggestions, omit the state filter for no restriction
- Locality suggestions accept
postcodeas one comma-separated value, for examplepostcode=2603,2604. Preserve leading zeros
Understand suggestion matching
Suggestions can account for incomplete or imperfect input:
- Street and locality spelling differences can still produce suggestions
- A locality alias or neighbouring locality can contribute to the search
- A street-type difference, such as
STinstead ofAV, does not always prevent a suggestion
These behaviours help users find an address but do not establish match confidence. Display the returned address and let the user confirm their selection.
For example, excludePrimaryWithSec=true can suppress the primary address 1 SMITH ST SMITHTOWN when secondary addresses such as UNIT 1 1 SMITH ST SMITHTOWN exist. These labels illustrate the filter rather than actual API results.
Build the selection flow
- Wait until input meets the endpoint's minimum length
- Debounce changes so each keystroke does not issue a request
- Ignore responses for queries that are no longer current
- Display suggestions in returned rank order
- Retrieve address details only after the user selects an address suggestion
Suggestions can match incomplete or imperfect input. The rank is a zero-based ordering value, not a quality rating or probability. An empty suggest array is a valid no-result response. Address suggestions may also report no results in messages.
Address suggestion IDs support an address-details lookup. Locality suggestion IDs do not. Handle 404 if a selected address can no longer be retrieved.
Read address details
The structured address uses snake_case property names. Optional components are returned as null, so check for a value before displaying or combining them. Alias and neighbour fields can contain comma-separated text when supplied.
Coordinates default to GDA94 (EPSG:4283). Use Accept-Crs to request a different supported response CRS. See CRS & GDA2020 for request syntax.
For datum background, see: