# 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=true` to exclude address aliases. The default is `false`
- Set `excludePrimaryWithSec=true` to exclude primary addresses with related secondary addresses. The default is `false`
- 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 `ALL` for no state restriction
- For locality suggestions, omit the state filter for no restriction
- Locality suggestions accept `postcode` as one comma-separated value, for example `postcode=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 `ST` instead of `AV`, 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

1. Wait until input meets the endpoint's minimum length
2. Debounce changes so each keystroke does not issue a request
3. Ignore responses for queries that are no longer current
4. Display suggestions in returned rank order
5. 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](/guides/gda-2020) for request syntax.

For datum background, see:

- [GDA2020 overview](https://www.icsm.gov.au/gda2020)
- [Mapping datums](https://www.icsm.gov.au/education/fundamentals-mapping/datums)
- [GDA2020 video](https://player.vimeo.com/video/191566518)
- [Coordinate precision illustration](https://xkcd.com/2170/)

## Next steps

- [Try the suggestion and details workflow](/guides/predictive/quickstart)
- [Configure an ArcGIS locator](/guides/predictive/esri-compatible-locator)