> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prontiq.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Autocomplete

> Build real-time Australian address typeahead.

Autocomplete returns address suggestions as a user types. Use it for search
boxes and address forms where the user should choose a known G-NAF address
before you enrich or submit the record.

<Info>
  Usage is metered in credits. See the [Credits guide](/guides/credits) for response headers and
  usage behaviour.
</Info>

## When to use it

* Build typeahead for address entry.
* Let users pick a canonical address before calling
  [Enrich](/guides/address/enrich).
* Narrow results with `state` when your flow already knows the state.

Use [Validate](/guides/address/validate) instead when a user has already
submitted a complete free-text address.

## Request

| Parameter | Type    | Required | Default | Description                                                                                 |
| --------- | ------- | -------- | ------- | ------------------------------------------------------------------------------------------- |
| `q`       | string  | Yes      | —       | Partial address query, 1-200 characters.                                                    |
| `state`   | string  | No       | —       | Australian state or territory code: `NSW`, `VIC`, `QLD`, `SA`, `WA`, `TAS`, `NT`, or `ACT`. |
| `limit`   | integer | No       | `5`     | Maximum suggestions to return, 1-20.                                                        |
| `debug`   | string  | No       | `false` | Optional diagnostics. Must be exactly `true` or `false`.                                    |

## Examples

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.prontiq.dev/v1/address/autocomplete?q=9+endeavour+cou&limit=3" \
    -H "X-Api-Key: YOUR_API_KEY"
  ```

  ```typescript TypeScript SDK theme={null}
  import { Prontiq } from "@prontiq/sdk";

  const prontiq = new Prontiq({
    serverURL: "https://api.prontiq.dev",
    apiKeyAuth: process.env.PRONTIQ_API_KEY!,
  });

  const response = await prontiq.address.autocompleteAddress("9 endeavour cou", undefined, 3);
  const { result } = response;

  for (const suggestion of result.suggestions) {
    console.log(suggestion.addressLabel);
  }
  ```

  ```python Python SDK theme={null}
  from prontiq import Prontiq

  client = Prontiq()

  response = client.address.autocomplete(
      q="9 endeavour cou",
      limit=3,
  )

  for suggestion in response.suggestions:
      print(suggestion.address_label)
  ```
</CodeGroup>

## Response

```json theme={null}
{
  "suggestions": [
    {
      "id": "GAQLD156786950",
      "addressLabel": "9 ENDEAVOUR COURT",
      "localityName": "LAMMERMOOR",
      "state": "QLD",
      "postcode": "4703",
      "prontiqMatchScore": 92,
      "prontiqMatchQuality": "high"
    }
  ],
  "total": 1
}
```

Autocomplete returns Prontiq match quality per suggestion. It does not return
G-NAF `confidence` or the internal search relevance score by default.
`total` equals `suggestions.length`: Autocomplete is optimized for fast,
ranked typeahead selection, not exhaustive corpus counts.

## Field notes

| Field                               | Meaning                                                                                    |
| ----------------------------------- | ------------------------------------------------------------------------------------------ |
| `suggestions[].id`                  | G-NAF persistent identifier. Pass it to Enrich for the full record.                        |
| `addressLabel`                      | Street address display text.                                                               |
| `localityName`, `state`, `postcode` | Locality fields for display and form population.                                           |
| `prontiqMatchScore`                 | Prontiq-computed match score from 0 to 100. Use it for thresholds, sorting, and analytics. |
| `prontiqMatchQuality`               | Human-readable bucket: `high`, `medium`, `low`, or `none`.                                 |
| `total`                             | Number of suggestions returned in this response.                                           |

With `debug=true`, suggestions may include `debug.searchScore`. This is an
unstable internal search relevance diagnostic. Do not store it, sort by it, or
use it for business decisions.

## Integration tips

* Start querying after the user has typed a few characters.
* Debounce browser calls so you do not send a request for every keystroke.
* Use the `state` filter when the user's state is known.
* Typos in completed words can still match. The word currently being typed is
  matched as a prefix, so typo tolerance is intentionally stronger for earlier
  tokens than the final token.

See the [Autocomplete API reference](/api-reference/autocomplete) for the
generated schema and live playground.