> ## 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.

# Address API

> Australian address validation, enrichment, geocoding, and lookup endpoints powered by G-NAF.

The Address API exposes the public Prontiq address endpoints generated from the
committed OpenAPI spec. Use this page to choose the right endpoint and interpret
the response fields that appear across multiple operations.

<Info>
  Usage is metered in credits. See the [Credits guide](/guides/credits) for response headers and
  usage behaviour. Account-specific billing details live in the Prontiq console; support questions
  go through [Featurebase](https://prontiq.featurebase.app).
</Info>

## Which endpoint should I use?

| Need                                          | Endpoint                          | Guide                                              |
| --------------------------------------------- | --------------------------------- | -------------------------------------------------- |
| Suggest addresses while a user types          | `GET /v1/address/autocomplete`    | [Autocomplete](/guides/address/autocomplete)       |
| Check a submitted address string              | `GET /v1/address/validate`        | [Validate](/guides/address/validate)               |
| Get the richest document for a known G-NAF ID | `GET /v1/address/enrich`          | [Enrich](/guides/address/enrich)                   |
| Find addresses near coordinates               | `GET /v1/address/reverse`         | [Reverse geocode](/guides/address/reverse)         |
| List localities inside a postcode             | `GET /v1/address/lookup/postcode` | [Postcode lookup](/guides/address/postcode-lookup) |
| Find postcodes for a suburb/locality          | `GET /v1/address/lookup/suburb`   | [Suburb lookup](/guides/address/suburb-lookup)     |

## Common response fields

### Address identity

`id` is the G-NAF persistent identifier. Store it when a user selects a
suggestion or validates an address, then pass it to
[Enrich](/guides/address/enrich) when you need the complete address document.

`addressLabel`, `localityName`, `state`, and `postcode` are the display fields
most integrations use to populate forms.

[Enrich](/guides/address/enrich) adds structured address components when
available, including unit, level, lot, street number, street name, street type,
site name, and building name. Prefer those fields over parsing `addressLabel`
when your integration needs structured storage.

### Prontiq match quality

[Autocomplete](/guides/address/autocomplete) and
[Validate](/guides/address/validate) return Prontiq-owned match-quality fields:
`prontiqMatchScore` and `prontiqMatchQuality`.

`prontiqMatchScore` estimates how well the returned address matched the
submitted request. It is not a measure of G-NAF record quality, deliverability,
or geocode precision.

| Value    | Meaning                                 | Typical handling                                  |
| -------- | --------------------------------------- | ------------------------------------------------- |
| `high`   | Strong match for the submitted address  | Accept or pre-fill with the matched address       |
| `medium` | Partial match                           | Show the match and ask the user to confirm        |
| `low`    | Weak match or likely component mismatch | Route to manual review or ask for another address |
| `none`   | No usable match                         | Do not treat `match` as a verified address        |

Score boundaries are stable for the `address-match-v1` scorer:

| Score range | Quality  |
| ----------- | -------- |
| `67-100`    | `high`   |
| `34-66`     | `medium` |
| `1-33`      | `low`    |
| `0`         | `none`   |

### G-NAF numeric confidence

Full address documents may include numeric `confidence` from G-NAF. It is
source-record metadata about the address record, not a judgement about the
user's submitted query.

G-NAF confidence values are:

| Value | Meaning                                         |
| ----- | ----------------------------------------------- |
| `2`   | Three contributor datasets support the address. |
| `1`   | Two contributor datasets support the address.   |
| `0`   | One contributor dataset supports the address.   |
| `-1`  | Retired address record.                         |

Autocomplete no longer returns G-NAF `confidence`. Use `prontiqMatchScore` and
`prontiqMatchQuality` for request match quality. On Validate, `match.confidence`
remains G-NAF source metadata.

See Geoscape's G-NAF documentation for the upstream data model:
[Data maintenance](https://docs.geoscape.com.au/projects/gnaf_desc/en/stable/data_maintenance.html)
and [Appendix C](https://docs.geoscape.com.au/projects/gnaf_desc/en/stable/appendix_c.html).

### Debug diagnostics

All public Address endpoints accept `debug=true`. Debug responses are for
support diagnostics only. `debug.searchScore`, when present, is an unstable
internal search relevance score. Do not store it, sort by it, or use it for
business decisions.

### Geocode and location

`geocode.latitude` and `geocode.longitude` are decimal degrees. `geocode.type`
describes the geocoding method when present. `geocode.reliability` is a G-NAF
reliability value where lower is better.

`location` is a compact latitude/longitude point with `lat` and `lon`.

### Boundaries

`boundaries` contains administrative, electoral, and statistical geography when
available:

| Field                    | Meaning                                                    |
| ------------------------ | ---------------------------------------------------------- |
| `lga`                    | Local Government Area                                      |
| `stateElectorate`        | State electoral district                                   |
| `commonwealthElectorate` | Federal electoral district                                 |
| `meshBlock`              | ABS mesh block, including land-use category when available |
| `sa2`, `sa3`, `sa4`      | ABS Statistical Areas                                      |
| `gccsa`                  | Greater Capital City Statistical Area                      |

Boundary fields are optional because coverage varies by source record and data
release.

Enrich returns the richest boundary shape. In addition to the common boundary
fields above, Enrich can include `boundaries.sa1` for Statistical Area Level 1
joins and `boundaries.ward` for council ward context when available.

### Lookup counts and bounds

Postcode lookup returns `address_count` for each locality in the postcode.
Suburb lookup returns total `address_count`, postcodes, and optional `bounds`.
When suburb lookup is called without `state`, matching localities across states
may be aggregated.

## API reference

The [API Reference](/api-reference/autocomplete) pages render request
parameters, response schemas, errors, and the Mintlify playground from
`packages/docs/openapi.json`.