> ## 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.
# Data Dictionary
> Definitive field reference for every public Address API attribute: types, meanings, edge cases, and source context.
## Overview
This page explains every public field returned by the Prontiq Address API. It is
written for developers implementing the API, analysts interpreting address and
boundary data, and stakeholders who need to understand what each field means in
plain English.
This page documents the current public contract generated from
`packages/docs/openapi.json`. It does not document private account APIs or
internal search, billing, or storage fields.
## How to read this page
Each field entry starts with a plain-English description, then moves into type,
nullability, source classification, and gotchas. Source classification uses four
labels:
| Source classification | Meaning |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| API contract field | Field defined by the public API contract rather than a direct upstream data attribute. |
| Prontiq-derived | Field computed by Prontiq from the request and returned records. |
| G-NAF / Geoscape source metadata | Field sourced from or describing Geoscape's Geocoded National Address File. |
| ABS / ASGS source metadata | Field sourced from Australian Bureau of Statistics geography or the Australian Statistical Geography Standard. |
## Quick reference
| Field | Type | Appears in | Meaning |
| ------------------------- | ------------------------- | --------------------------------------- | ---------------------------------------------------------------------------------- |
| `id` | `string` | Suggestions, address documents | Stable G-NAF address identifier used for enrichment and storage. |
| `addressLabel` | `string \| null` | Suggestions, address documents | Display-ready street address line. |
| `localityName` | `string \| null` | Suggestions, address documents | Official suburb or locality name. |
| `state` | `string \| null` | Suggestions, address documents, lookups | Australian state or territory code. |
| `postcode` | `string \| null` | Suggestions, address documents, lookups | Four-digit Australian postcode stored as a string. |
| `prontiqMatchScore` | `integer` | Autocomplete suggestions, Validate | Prontiq match score from 0 to 100 for the submitted request. |
| `prontiqMatchQuality` | `enum` | Autocomplete suggestions, Validate | Human-readable bucket derived from `prontiqMatchScore`. |
| `suggestions` | `array` | Autocomplete response | Ordered compact address candidates for typeahead interfaces. |
| `match` | `AddressDocument \| null` | Validate response | Best full address document for the submitted address, or `null`. |
| `results` | `array` | Reverse response | Nearby full address documents, each with `distance_m`. |
| `confidence` | `integer \| null` | Full address documents | G-NAF source-record confidence metadata, not match quality. |
| `geocode` | `object \| null` | Full address documents | Coordinates plus G-NAF geocode metadata. |
| `location` | `object \| null` | Full address documents | Compact `{ lat, lon }` point for maps and proximity workflows. |
| `boundaries` | `object \| null` | Full address documents | Administrative, electoral, and ABS geography. |
| `sourceDataRelease` | `string \| null` | Enrich response | Source data release or version used to produce the enriched address record. |
| `addressRole` | `enum \| null` | Enrich response | Primary or secondary address role when available. |
| `components` | `object` | Enrich response | Structured address components such as unit, level, street number, and street name. |
| `legalParcelId` | `string \| null` | Enrich response | Parcel or legal-property reference when available. |
| `allGeocodes` | `array` | Enrich response | Additional geocodes associated with the address. |
| `locality` | `object` | Enrich response | Locality context including classification, neighbours, and aliases. |
| `street` | `object` | Enrich response | Street context including classification and aliases. |
| `aliases` | `array` | Enrich response | Alternative address labels associated with the address. |
| `secondaries` | `array` | Enrich response | Secondary or child address records associated with the address. |
| `distance_m` | `number` | Reverse geocode results | Distance from the submitted coordinate in metres. |
| `address_count` | `integer` | Lookup responses | Number of address records in a locality or suburb. |
| `localities` | `array` | Postcode lookup response | Locality summaries for a postcode. |
| `postcodes` | `array` | Suburb lookup response | Postcodes associated with a suburb/locality. |
| `suburb` | `string` | Suburb lookup response | Canonical suburb/locality name for the lookup result. |
| `bounds` | `object` | Suburb lookup response | Optional geographic bounding box for the locality. |
| `debug` | `object` | Debug responses only | Optional diagnostics when `debug=true`. |
| `debug.scoringVersion` | `string` | Debug responses only | Version identifier for the diagnostic scoring model. |
| `debug.queryMode` | `enum` | Debug responses only | Address operation mode that produced the debug payload. |
| `debug.matchedComponents` | `object` | Debug responses only | Optional component-level match diagnostics. |
| `debug.scoreCaps` | `array` | Debug responses only | Optional list of match-score caps applied by the scorer. |
| `debug.searchScore` | `number` | Debug responses only | Optional diagnostic search relevance score; not for business logic. |
| `error` | `object` | Error responses | Standard API error envelope. |
| `error.code` | `enum` | Error responses | Stable machine-readable error code. |
| `error.message` | `string` | Error responses | Human-readable error message. |
| `error.status` | `integer` | Error responses | HTTP status code mirrored in the error body. |
| `error.details` | `object` | Error responses | Optional structured error details. |
| `error.request_id` | `string` | Error responses | Request identifier for support and debugging. |
## How G-NAF powers the API
G-NAF means Geocoded National Address File. It is Australia's national address
dataset, maintained by Geoscape and built from address information supplied by
state, territory, and Commonwealth contributors. Prontiq uses G-NAF as the
address corpus behind autocomplete, validation, enrichment, reverse geocoding,
and locality lookup.
Prontiq adds a public API layer on top of that source data: authenticated
endpoints, match-quality scoring, simplified response shapes, debug diagnostics,
and generated SDKs. Prontiq match fields describe how well a returned address
matched the submitted request. G-NAF fields describe the address record itself.
Geoscape publishes G-NAF updates on a regular release cycle. Address metadata,
geocodes, and boundary values can change across source data releases without
the public `id` changing.
`prontiqMatchScore` and `prontiqMatchQuality` are Prontiq match-quality
fields. `confidence` is G-NAF source-record metadata on full address
documents. Autocomplete suggestions do not expose `confidence` or `score`, and
Validate does not expose top-level `confidence`.
Returns compact suggestions with display fields and Prontiq match quality.
Returns the best matching full address document plus Prontiq match quality.
Resolves a known `id` into the full public address document.
Finds nearby address documents and returns `distance_m`.
Returns localities and address counts for a four-digit postcode.
Returns postcodes, bounds, and address counts for a locality.
## Field reference
Unique G-NAF persistent identifier for an address record.
| Property | Value |
| --------------------- | ------------------------------------------------------ |
| Appears in | `suggestions[]`, `match`, Enrich response, `results[]` |
| Nullable | No |
| Example | `GAQLD156786950` |
| Source classification | G-NAF / Geoscape source metadata |
Store `id` as an opaque string. Do not parse state, locality, or record
meaning out of it. Pass it to [Enrich](/guides/address/enrich) when you
need the full address document after a user selects a suggestion.
Display-ready street address line.
| Property | Value |
| --------------------- | ------------------------------------------------------ |
| Appears in | `suggestions[]`, `match`, Enrich response, `results[]` |
| Nullable | Yes |
| Example | `9 ENDEAVOUR COURT` |
| Source classification | API contract field |
Use this as the street-address line in forms and confirmation screens.
It usually contains the street number, street name, and unit or building
text when the source record provides those details.
Source data release or version used to produce the enriched address record.
| Property | Value |
| --------------------- | ------------------ |
| Appears in | Enrich response |
| Nullable | Yes |
| Example | `2026.04` |
| Source classification | API contract field |
This identifies the source data release behind the enriched record when
available. It is not the Prontiq API version.
Parent or child address role for an enriched address record.
| Property | Value |
| --------------------- | -------------------------------- |
| Appears in | Enrich response |
| Nullable | Yes |
| Example | `SECONDARY` |
| Source classification | G-NAF / Geoscape source metadata |
`PRIMARY` generally means a parent or building-level address.
`SECONDARY` generally means a child, unit, or subaddress record.
Official suburb or locality name for the address.
| Property | Value |
| --------------------- | ------------------------------------------------------ |
| Appears in | `suggestions[]`, `match`, Enrich response, `results[]` |
| Nullable | Yes |
| Example | `LAMMERMOOR` |
| Source classification | G-NAF / Geoscape source metadata |
Locality names should be displayed as returned. Do not assume user input
casing or aliases are the canonical form.
Australian state or territory code.
| Property | Value |
| --------------------- | ------------------------------------------------------- |
| Appears in | Address documents, suggestions, lookup summaries |
| Nullable | Yes on returned records where source data is incomplete |
| Example | `QLD` |
| Source classification | API contract field |
Allowed response values are `NSW`, `VIC`, `QLD`, `SA`, `WA`, `TAS`,
`NT`, and `ACT`. Query filters are case-insensitive, but responses
normalize state codes to uppercase.
Four-digit Australian postcode.
| Property | Value |
| --------------------- | --------------------------------------------------------------- |
| Appears in | Address documents, suggestions, lookup responses |
| Nullable | Yes on returned address records where source data is incomplete |
| Example | `4703` |
| Source classification | API contract field |
Store postcodes as strings. Some Australian postcodes can begin with `0`,
and integer coercion loses leading zeroes.
Numeric score that estimates how well the returned address matched the submitted request.
| Property | Value |
| --------------------- | ---------------------------------- |
| Appears in | `suggestions[]`, Validate response |
| Nullable | No |
| Example | `92` |
| Source classification | Prontiq-derived |
The score is an integer from `0` to `100`. Use it for thresholds,
ranking, and analytics. It is not G-NAF record quality, deliverability, or
geocode precision.
Human-readable match-quality bucket derived from `prontiqMatchScore`.
| Property | Value |
| --------------------- | ---------------------------------- |
| Appears in | `suggestions[]`, Validate response |
| Nullable | No |
| Example | `high` |
| Source classification | Prontiq-derived |
| Value | Score range | Typical handling |
| -------- | ----------- | ---------------------------------------------- |
| `high` | `67-100` | Accept or pre-fill with the matched address. |
| `medium` | `34-66` | Show the match and ask the user to confirm. |
| `low` | `1-33` | Ask for correction or route to review. |
| `none` | `0` | Do not treat the result as a verified address. |
Use this when a simple branch is clearer than tuning numeric thresholds.
The API has two separate quality concepts. Prontiq match quality describes
the submitted request. G-NAF confidence describes the source address
record.
| Concept | Field | Appears in | Use for | Do not use for |
| ------------------------ | ------------------------------------------ | ------------------------------------------- | ---------------------------------- | -------------------------------------------- |
| Request match quality | `prontiqMatchScore`, `prontiqMatchQuality` | Autocomplete suggestions, Validate response | Accept, confirm, reject, analytics | Source provenance or geocode precision |
| Source-record confidence | `confidence` | Full address documents only | Understanding source-data support | Ranking suggestions or validating user input |
G-NAF source-record confidence metadata for a full address document.
| Property | Value |
| --------------------- | ------------------------------------------------------------------- |
| Appears in | `match.confidence`, Enrich response, Reverse `results[].confidence` |
| Nullable | Yes |
| Example | `2` |
| Source classification | G-NAF / Geoscape source metadata |
`confidence` describes how many upstream contributor datasets support the
address record. It does not describe how well the user's submitted text
matched the record.
| 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 suggestions do not include G-NAF `confidence`. Validate uses
top-level `prontiqMatchScore` and `prontiqMatchQuality` for request match
quality, while `match.confidence` remains source-record metadata.
Latitude of the address geocode in WGS84 decimal degrees.
| Property | Value |
| --------------------- | ------------------------------------------------------------- |
| Appears in | `match.geocode`, Enrich response, Reverse `results[].geocode` |
| Nullable | No when `geocode` is present |
| Example | `-23.1601` |
| Source classification | G-NAF / Geoscape source metadata |
Longitude of the address geocode in WGS84 decimal degrees.
| Property | Value |
| --------------------- | ------------------------------------------------------------- |
| Appears in | `match.geocode`, Enrich response, Reverse `results[].geocode` |
| Nullable | No when `geocode` is present |
| Example | `150.7596` |
| Source classification | G-NAF / Geoscape source metadata |
Source geocoding method or level, when available.
| Property | Value |
| --------------------- | -------------------------------- |
| Appears in | Full address documents |
| Nullable | Yes |
| Example | `PROPERTY CENTROID` |
| Source classification | G-NAF / Geoscape source metadata |
G-NAF geocode precision code, where lower numbers are more precise.
| Property | Value |
| --------------------- | -------------------------------- |
| Appears in | Full address documents |
| Nullable | Yes |
| Example | `2` |
| Source classification | G-NAF / Geoscape source metadata |
Lower is better. A smaller `geocode.reliability` number indicates a
more precise coordinate. This is separate from address match quality and
separate from G-NAF `confidence`.
The public contract allows integer values from `0` to `6`. Treat the
value as source precision metadata and link to Geoscape's official
documentation when your workflow needs the full reliability-code model.
Compact map point for the same address location.
| Property | Value |
| --------------------- | -------------------------------------- |
| Appears in | Full address documents |
| Nullable | `location` can be null |
| Example | `{ "lat": -23.1601, "lon": 150.7596 }` |
| Source classification | API contract field |
Use `location` when your integration wants a simple `{ lat, lon }` shape.
Use `geocode` when you also need source precision and geocoding method
metadata.
Local Government Area for council-level reporting and segmentation.
| Property | Value |
| --------------------- | ------------------------------------------ |
| Appears in | `boundaries.lga` on full address documents |
| Nullable | Yes |
| Example | `{ "name": "Livingstone Shire" }` |
| Source classification | ABS / ASGS source metadata |
State electoral district associated with the address location.
| Property | Value |
| --------------------- | ------------------------------------------------------ |
| Appears in | `boundaries.stateElectorate` on full address documents |
| Nullable | Yes |
| Example | `{ "name": "Keppel" }` |
| Source classification | ABS / ASGS source metadata |
Federal electoral division associated with the address location.
| Property | Value |
| --------------------- | ------------------------------------------------------------- |
| Appears in | `boundaries.commonwealthElectorate` on full address documents |
| Nullable | Yes |
| Example | `{ "name": "Capricornia" }` |
| Source classification | ABS / ASGS source metadata |
Australian Bureau of Statistics Mesh Block and optional land-use category.
| Property | Value |
| --------------------- | ------------------------------------------------------ |
| Appears in | `boundaries.meshBlock` on full address documents |
| Nullable | Yes |
| Example | `{ "code": "30000000000", "category": "Residential" }` |
| Source classification | ABS / ASGS source metadata |
ABS statistical geography used for reporting from local areas up to capital-city regions.
| Property | Value |
| --------------------- | ------------------------------------------------------------------------ |
| Appears in | `boundaries.sa2`, `boundaries.sa3`, `boundaries.sa4`, `boundaries.gccsa` |
| Nullable | Yes |
| Example | `{ "name": "Yeppoon", "code": "308011188" }` |
| Source classification | ABS / ASGS source metadata |
| Field | Meaning |
| ------- | ------------------------------------------------------------------------ |
| `sa2` | Statistical Area Level 2, commonly used for suburb-scale analysis. |
| `sa3` | Statistical Area Level 3, a larger regional grouping. |
| `sa4` | Statistical Area Level 4, a broader labour-market and regional grouping. |
| `gccsa` | Greater Capital City Statistical Area. |
ASGS source hierarchy: Mesh Block -> SA1 -> SA2 -> SA3 -> SA4 -> GCCSA.
Boundary fields are optional because coverage varies by source record and
release.
ABS Statistical Area Level 1 code associated with an enriched address when available.
| Property | Value |
| --------------------- | -------------------------- |
| Appears in | Enrich response |
| Nullable | Yes |
| Example | `20802117831` |
| Source classification | ABS / ASGS source metadata |
SA1 is useful for downstream statistical joins, including socio-economic
and small-area analytics.
Council ward associated with an enriched address when available.
| Property | Value |
| --------------------- | -------------------------------- |
| Appears in | Enrich response |
| Nullable | Yes |
| Example | `{ "name": "Bambra Ward" }` |
| Source classification | G-NAF / Geoscape source metadata |
Enrich returns additional fields when they are present in the source
address record. Coverage varies by address and geography.
Structured address parts for integrations that need more than `addressLabel`.
| Property | Value |
| --------------------- | -------------------------------------------------------------------------------------------------------------------- |
| Appears in | Enrich response |
| Nullable | Optional |
| Example | `{ "flatType": "FLAT", "flatNumber": "14", "streetNumberFirst": "5", "streetName": "DUKE", "streetType": "STREET" }` |
| Source classification | G-NAF / Geoscape source metadata |
Common child fields include `components.addressSiteName`,
`components.buildingName`, `components.flatType`,
`components.flatNumber`, `components.levelType`,
`components.levelNumber`, `components.lotNumber`,
`components.streetNumberFirst`, `components.streetNumberLast`,
`components.streetName`, `components.streetType`, and
`components.streetSuffix`.
Parcel or legal-property reference when available for the address.
| Property | Value |
| --------------------- | -------------------------------- |
| Appears in | Enrich response |
| Nullable | Yes |
| Example | `14\\PS349838` |
| Source classification | G-NAF / Geoscape source metadata |
Coverage varies. Store it as a string and do not parse state or property
meaning out of the value.
Additional geocodes associated with the address.
| Property | Value |
| --------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Appears in | Enrich response |
| Nullable | Optional |
| Example | `[{ "latitude": -37.89180933, "longitude": 145.01510717, "type": "FRONTAGE CENTRE SETBACK", "reliability": 2 }]` |
| Source classification | G-NAF / Geoscape source metadata |
Each item has `allGeocodes[].latitude`,
`allGeocodes[].longitude`, optional `allGeocodes[].type`, and optional
`allGeocodes[].reliability`.
Locality context for the enriched address.
| Property | Value |
| --------------------- | ----------------------------------------------------------------------------------------- |
| Appears in | Enrich response |
| Nullable | Optional |
| Example | `{ "classification": "GAZETTED LOCALITY", "neighbours": ["ELSTERNWICK"], "aliases": [] }` |
| Source classification | G-NAF / Geoscape source metadata |
Public child fields are `locality.id`, `locality.classification`,
`locality.neighbours`, and `locality.aliases`.
Street-level context for the enriched address.
| Property | Value |
| --------------------- | -------------------------------------------------- |
| Appears in | Enrich response |
| Nullable | Optional |
| Example | `{ "classification": "CONFIRMED", "aliases": [] }` |
| Source classification | G-NAF / Geoscape source metadata |
Public child fields are `street.id`, `street.classification`, and
`street.aliases`.
Alternative address labels associated with the enriched address.
| Property | Value |
| --------------------- | --------------------------------------------------------------------------------------------- |
| Appears in | Enrich response |
| Nullable | Optional |
| Example | `[{ "id": "MA13517230", "addressLabel": "SHOP 1 GROUND 1 MCNAB AVENUE", "type": "SYNONYM" }]` |
| Source classification | G-NAF / Geoscape source metadata |
Each item may include `aliases[].id`, `aliases[].addressLabel`, and
`aliases[].type`.
Secondary or child address records associated with the enriched address.
| Property | Value |
| --------------------- | ----------------------------------------------------------------------- |
| Appears in | Enrich response |
| Nullable | Optional |
| Example | `[{ "id": "GAVIC425495838", "addressLabel": "SHOP 1 1 MCNAB AVENUE" }]` |
| Source classification | G-NAF / Geoscape source metadata |
Each item may include `secondaries[].id` and
`secondaries[].addressLabel`.
Ordered compact address candidates returned by Autocomplete.
| Property | Value |
| --------------------- | ------------------------------------------------------------------- |
| Appears in | Autocomplete response |
| Nullable | No |
| Example | `[{ "id": "GAQLD156786950", "addressLabel": "9 ENDEAVOUR COURT" }]` |
| Source classification | API contract field |
Each item is an address suggestion with display fields and Prontiq match
quality. Suggestions are intentionally compact; call Enrich after a user
selects a suggestion when you need full address metadata. Autocomplete
`total` equals the number of suggestions returned, not an exhaustive
count of every possible match.
Best matching full address document returned by Validate.
| Property | Value |
| --------------------- | ----------------------------------------------------------------- |
| Appears in | Validate response |
| Nullable | Yes |
| Example | `{ "id": "GAQLD156786950", "addressLabel": "9 ENDEAVOUR COURT" }` |
| Source classification | API contract field |
`match` is `null` when the submitted address cannot be resolved to a
usable record. Even when `match` is present, use `prontiqMatchScore` and
`prontiqMatchQuality` to decide whether the match is strong enough for
your workflow.
Address result list returned by Reverse geocode.
| Property | Value |
| --------------------- | -------------------------------------------------- |
| Appears in | Reverse geocode response |
| Nullable | No |
| Example | `[{ "id": "GAQLD156786950", "distance_m": 27.4 }]` |
| Source classification | API contract field |
Each item is a full address document plus `distance_m`. Reverse geocode
also includes `total`, which reports how many records were found inside
the requested radius.
Distance from the reverse-geocode coordinate to an address result, in metres.
| Property | Value |
| --------------------- | --------------------------- |
| Appears in | Reverse geocode `results[]` |
| Nullable | No when present |
| Example | `27.4` |
| Source classification | Prontiq-derived |
`distance_m` appears only on Reverse geocode results. It is a proximity
measure, not match quality.
Number of address records in a lookup grouping.
| Property | Value |
| --------------------- | ------------------------------------ |
| Appears in | Postcode and suburb lookup responses |
| Nullable | No |
| Example | `12345` |
| Source classification | API contract field |
`address_count` appears in postcode and suburb lookup responses. It is
dataset cardinality, not credits, quota, billing usage, or rate limiting.
Locality summaries returned by postcode lookup.
| Property | Value |
| --------------------- | ---------------------------------------------------------------- |
| Appears in | Postcode lookup response |
| Nullable | No |
| Example | `[{ "name": "SYDNEY", "state": "NSW", "address_count": 12345 }]` |
| Source classification | API contract field |
Each item includes `name`, optional `state`, and `address_count`.
Postcodes associated with a suburb or locality lookup result.
| Property | Value |
| --------------------- | ---------------------- |
| Appears in | Suburb lookup response |
| Nullable | No |
| Example | `["2000"]` |
| Source classification | API contract field |
Postcodes remain strings for the same reason as `postcode`: preserving
leading zeroes is part of the public contract.
Canonical suburb or locality name returned by suburb lookup.
| Property | Value |
| --------------------- | ---------------------- |
| Appears in | Suburb lookup response |
| Nullable | No |
| Example | `SYDNEY` |
| Source classification | API contract field |
This is the matched locality name for the lookup response. Display it as
returned rather than preserving the caller's input casing.
Approximate bounding box for a suburb or locality when available.
| Property | Value |
| --------------------- | ------------------------------------------------------------------------------------------------------------ |
| Appears in | Suburb lookup response |
| Nullable | Optional |
| Example | `{ "top_left": { "lat": -33.8568, "lon": 151.2001 }, "bottom_right": { "lat": -33.8812, "lon": 151.2204 } }` |
| Source classification | API contract field |
`bounds.top_left` and `bounds.bottom_right` use snake\_case field names for
v1 wire compatibility.
Response count summary. In Autocomplete, `total` is the number of
suggestions returned in that response. In Reverse geocode, `total` is the
number of address records found inside the requested radius.
| Property | Value |
| --------------------- | ----------------------------------------------- |
| Appears in | Autocomplete response, Reverse geocode response |
| Nullable | No |
| Example | `3` |
| Source classification | API contract field |
Optional diagnostics returned only when `debug=true` is supplied.
| Property | Value |
| --------------------- | ----------------------------------------------------------------------- |
| Appears in | Successful Address responses when `debug=true` |
| Nullable | Optional |
| Example | `{ "scoringVersion": "address-match-v1", "queryMode": "autocomplete" }` |
| Source classification | Prontiq-derived |
Debug output is for support and troubleshooting. Default responses do not
include a `debug` object.
Version identifier for the diagnostic scoring model.
| Property | Value |
| --------------------- | ------------------ |
| Appears in | Debug responses |
| Nullable | No |
| Example | `address-match-v1` |
| Source classification | Prontiq-derived |
Use this only to interpret debug diagnostics. It is not a release version
for the public API.
Address operation mode that produced the debug payload.
| Property | Value |
| --------------------- | --------------- |
| Appears in | Debug responses |
| Nullable | No |
| Example | `autocomplete` |
| Source classification | Prontiq-derived |
This helps support distinguish diagnostics from suggestion, validation,
enrichment, reverse-geocode, and lookup flows.
Optional component-level match diagnostics.
| Property | Value |
| --------------------- | -------------------------------------------------------- |
| Appears in | Debug responses when component diagnostics are available |
| Nullable | Optional |
| Example | `{ "streetNumber": "exact", "streetName": "prefix" }` |
| Source classification | Prontiq-derived |
Values classify how submitted address components matched the returned
record. Possible values are `exact`, `prefix`, `fuzzy`, and `none`.
Optional list of match-score caps applied by the scorer.
| Property | Value |
| --------------------- | ------------------------------------- |
| Appears in | Debug responses when caps are applied |
| Nullable | Optional |
| Example | `["explicitPostcodeMismatch"]` |
| Source classification | Prontiq-derived |
Score caps explain why a result was limited to a lower public
`prontiqMatchScore`, such as an explicit postcode or state mismatch.
Optional internal search relevance diagnostic.
| Property | Value |
| --------------------- | ------------------------------------ |
| Appears in | Debug responses only, when available |
| Nullable | Optional |
| Example | `42.1` |
| Source classification | Prontiq-derived |
This field may be absent even when `debug=true`. Do not store it, sort by
it, or use it for business decisions.
Standard API error envelope returned when a request cannot be completed.
| Property | Value |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Appears in | Error responses |
| Nullable | No |
| Example | `{ "error": { "code": "INVALID_PARAMETERS", "message": "Invalid query parameters", "status": 400, "request_id": "req_01HZX7A8J5K9P4R2QW3E6T7Y8Z" } }` |
| Source classification | API contract field |
Branch on `error.code`, display or log `error.message`, and include
`error.request_id` when contacting support.
Stable machine-readable error code.
| Property | Value |
| --------------------- | -------------------- |
| Appears in | Error responses |
| Nullable | No |
| Example | `INVALID_PARAMETERS` |
| Source classification | API contract field |
Use `error.code` for branching. Do not parse `error.message`.
Human-readable error message.
| Property | Value |
| --------------------- | -------------------------- |
| Appears in | Error responses |
| Nullable | No |
| Example | `Invalid query parameters` |
| Source classification | API contract field |
Messages are for display and support context. They are not a stable enum.
HTTP status code mirrored inside the error envelope.
| Property | Value |
| --------------------- | ------------------ |
| Appears in | Error responses |
| Nullable | No |
| Example | `400` |
| Source classification | API contract field |
This should match the HTTP response status.
Optional structured error details.
| Property | Value |
| --------------------- | ---------------------------------------------------- |
| Appears in | Error responses when structured context is available |
| Nullable | Optional |
| Example | `{ "q": ["Required"] }` |
| Source classification | API contract field |
The shape depends on `error.code`. Treat it as optional context rather
than a required schema for every error.
Request identifier for support and debugging.
| Property | Value |
| --------------------- | -------------------------------- |
| Appears in | Error responses |
| Nullable | No |
| Example | `req_01HZX7A8J5K9P4R2QW3E6T7Y8Z` |
| Source classification | API contract field |
This field is intentionally snake\_case in the v1 error envelope. Include
it when contacting support about a failed request.
## Fields not present in default responses
| Field | Status | Use instead |
| ------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------- |
| `suggestions[].confidence` | Not in the current public autocomplete contract. | `suggestions[].prontiqMatchScore` and `suggestions[].prontiqMatchQuality`. |
| `suggestions[].score` | Not in default responses. | `suggestions[].debug.searchScore` only when `debug=true`, for diagnostics only. |
| Validate top-level `confidence` | Not in the current public validate contract. | `prontiqMatchScore` and `prontiqMatchQuality`. |
## Alias, canonical values, and storage
Prontiq returns canonical address values from the public contract. Users may type
aliases, partial street names, or mixed-case locality names, but integrations
should store the returned `id` and display the returned address fields rather
than attempting to preserve the submitted text as the canonical record.
Store `id`, `postcode`, and boundary codes as strings. Treat optional nested
objects defensively: `geocode`, `location`, `boundaries`, and individual
boundary fields can be absent or null depending on source coverage.
## Freshness and lifecycle
Address source data and boundary data change across official releases. A stored
`id` is the right key to keep, but the document behind that key can gain, lose,
or update metadata over time. If your product relies on current boundaries,
geocodes, or source metadata, re-enrich stored IDs on a regular release cadence.
An ID that no longer resolves returns a `NOT_FOUND` error from
[Enrich](/guides/address/enrich). Handle that as stale source data rather than
as a user input error.
## Semantic origin table
The repo verifies the public field names, types, examples, and source
classifications below. It does not encode exact upstream G-NAF table and column
lineage for every field, so this page does not invent table-column precision
that cannot be checked from source.
| Prontiq field | Source classification | Verified public shape | Notes |
| ------------------------- | -------------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------- |
| `id` | G-NAF / Geoscape source metadata | `string`, required where an address record appears | Opaque persistent address identifier. |
| `addressLabel` | API contract field | `string \| null` | Display street-address line. |
| `localityName` | G-NAF / Geoscape source metadata | `string \| null` | Canonical locality/suburb name returned by the API. |
| `state` | API contract field | `NSW`, `VIC`, `QLD`, `SA`, `WA`, `TAS`, `NT`, `ACT`, or null | Query input is case-insensitive; responses are uppercase. |
| `postcode` | API contract field | Four-digit string or null | Store as a string to preserve leading zeroes. |
| `prontiqMatchScore` | Prontiq-derived | Integer `0-100` | Request match quality, not source metadata. |
| `prontiqMatchQuality` | Prontiq-derived | `high`, `medium`, `low`, `none` | Derived from `prontiqMatchScore`. |
| `suggestions` | API contract field | Array of `AddressSuggestion` | Compact autocomplete candidates. |
| `match` | API contract field | `AddressDocument` or null | Validate's best address match. |
| `results` | API contract field | Array of reverse-geocode result documents | Reverse geocode candidates with `distance_m`. |
| `confidence` | G-NAF / Geoscape source metadata | Integer `-1` through `2`, or null | Full address documents only. |
| `geocode` | G-NAF / Geoscape source metadata | Object or null | Contains coordinates, geocode type, and reliability metadata. |
| `location` | API contract field | `{ lat, lon }` object or null | Convenience point shape for mapping workflows. |
| `boundaries.*` | ABS / ASGS source metadata | Objects or null | Administrative, electoral, and statistical geography can change by release. |
| `boundaries.sa1` | ABS / ASGS source metadata | String or null on Enrich | Statistical Area Level 1 code when available. |
| `boundaries.ward` | G-NAF / Geoscape source metadata | Object or null on Enrich | Council ward when available. |
| `sourceDataRelease` | API contract field | String or null on Enrich | Source data release/version for the enriched record, not the Prontiq API version. |
| `addressRole` | G-NAF / Geoscape source metadata | `PRIMARY`, `SECONDARY`, or null on Enrich | Parent/child address role when available. |
| `components` | G-NAF / Geoscape source metadata | Object on Enrich | Structured address components. |
| `legalParcelId` | G-NAF / Geoscape source metadata | String or null on Enrich | Parcel/legal-property reference when available. |
| `allGeocodes` | G-NAF / Geoscape source metadata | Array on Enrich | Additional geocodes associated with the address. |
| `locality` | G-NAF / Geoscape source metadata | Object on Enrich | Locality classification, neighbours, and aliases. |
| `street` | G-NAF / Geoscape source metadata | Object on Enrich | Street classification and aliases. |
| `aliases` | G-NAF / Geoscape source metadata | Array on Enrich | Alternative address labels. |
| `secondaries` | G-NAF / Geoscape source metadata | Array on Enrich | Secondary or child address labels. |
| `distance_m` | Prontiq-derived | Number on Reverse results | Distance from submitted coordinate, in metres. |
| `address_count` | API contract field | Non-negative integer | Dataset cardinality, not billing usage. |
| `localities` | API contract field | Array of locality summaries | Postcode lookup envelope. |
| `postcodes` | API contract field | Array of strings | Suburb lookup envelope. |
| `suburb` | API contract field | String | Canonical suburb/locality for suburb lookup. |
| `bounds` | API contract field | Optional `GeoBounds` object | Suburb lookup bounding box. |
| `debug` | Prontiq-derived | Optional object when `debug=true` | Diagnostic envelope only. |
| `debug.scoringVersion` | Prontiq-derived | String | Diagnostic scoring-model identifier. |
| `debug.queryMode` | Prontiq-derived | Address operation enum | Debug context for the operation that produced the response. |
| `debug.matchedComponents` | Prontiq-derived | Optional object | Component-level match diagnostics. |
| `debug.scoreCaps` | Prontiq-derived | Optional array of strings | Explains public score caps applied during scoring. |
| `debug.*` | Prontiq-derived | Optional object when `debug=true` | Diagnostic only; do not use for product decisions. |
| `error` | API contract field | Standard error envelope | Contains stable error fields under `error.*`. |
| `error.code` | API contract field | Address error-code enum | Stable field for error branching. |
| `error.message` | API contract field | String | Human-readable error text. |
| `error.status` | API contract field | Integer | HTTP status mirrored in the body. |
| `error.details` | API contract field | Optional object | Extra structured context when available. |
| `error.request_id` | API contract field | String in error envelope | Include this value when contacting support. |
## Implementation checklist
Store `id`, `postcode`, Mesh Block codes, ABS area codes, and electorate
codes as strings. Enrich-only values such as `legalParcelId`,
`sourceDataRelease`, `boundaries.sa1`, aliases, and secondary IDs should
also be stored as strings when your workflow needs them.
Use `prontiqMatchScore` and `prontiqMatchQuality` for accept, confirm, or
reject workflows.
`confidence` tells you about source-record support. It is not request match
quality.
Lower `geocode.reliability` values indicate more precise geocodes.
`debug.searchScore` is optional, unstable, and diagnostic only.
Keep `distance_m`, `address_count`, `top_left`, `bottom_right`, and
`error.request_id` exactly as documented.
`geocode`, `location`, `boundaries`, and individual boundary fields can be
absent or null.
Autocomplete is a compact suggestion flow. Call Enrich with the selected
`id` when your application needs coordinates and boundary data.
Boundary and geocode metadata can change across source data releases even
when the address `id` remains stable.
A `NOT_FOUND` response from Enrich means the stored `id` no longer resolves
in the current public corpus.
## External references
* [Geoscape G-NAF documentation](https://docs.geoscape.com.au/projects/gnaf_desc/en/stable/)
* [G-NAF on data.gov.au](https://data.gov.au/data/dataset/geocoded-national-address-file-g-naf)
* [ABS Australian Statistical Geography Standard Edition 3](https://www.abs.gov.au/statistics/standards/australian-statistical-geography-standard-asgs-edition-3)
* [ICSM overview of AS/NZS 4819 rural and urban addressing](https://www.icsm.gov.au/what-we-do/addressing/standards-rural-and-urban-addressing-as4819)
* [Prontiq API reference](/api-reference/)