Data Dictionary

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<string>`	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<string>`	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.

Autocomplete

Returns compact suggestions with display fields and Prontiq match quality.

Validate

Returns the best matching full address document plus Prontiq match quality.

Enrich

Resolves a known id into the full public address document.

Reverse geocode

Finds nearby address documents and returns distance_m.

Postcode lookup

Returns localities and address counts for a four-digit postcode.

Suburb lookup

Returns postcodes, bounds, and address counts for a locality.

Field reference

Address identity

string

required

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 when you need the full address document after a user selects a suggestion.

addressLabel

string | null

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.

sourceDataRelease

string | null

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.

addressRole

"PRIMARY" | "SECONDARY" | null

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.

Locality and postal fields

localityName

string | null

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.

state

string | null

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.

postcode

string | null

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.

Prontiq match quality

prontiqMatchScore

integer

required

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.

prontiqMatchQuality

"high" | "medium" | "low" | "none"

required

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.

G-NAF record quality

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

confidence

integer | null

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.

Geocode and location

geocode.latitude

number<double>

required

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

geocode.longitude

number<double>

required

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

geocode.type

string | null

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

geocode.reliability

integer | null

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.

location.lat / location.lon

number<double>

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.

Administrative and statistical boundaries

boundaries.lga

NamedArea | null

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

boundaries.stateElectorate

NamedArea | null

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

boundaries.commonwealthElectorate

NamedArea | null

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

boundaries.meshBlock

MeshBlock | null

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

boundaries.sa2 / sa3 / sa4 / gccsa

NamedArea | null

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.

boundaries.sa1

string | null

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.

boundaries.ward

object | null

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-only fields

Enrich returns additional fields when they are present in the source address record. Coverage varies by address and geography.

components

AddressComponents

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.

legalParcelId

string | null

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.

allGeocodes

array<AllGeocode>

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

LocalityContext

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

StreetContext

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.

aliases

array<AddressAlias>

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.

secondaries

array<SecondaryAddress>

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.

Endpoint envelopes and aggregates

suggestions

array

required

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.

match

AddressDocument | null

required

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.

results

array

required

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_m

number<double>

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.

address_count

integer

required

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.

localities

array

required

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

array<string>

required

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.

suburb

string

required

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.

bounds

GeoBounds

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.

total

integer

required

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

Debug and errors

debug

DebugInfo

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.

debug.scoringVersion

string

required

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.

debug.queryMode

"autocomplete" | "validate" | "enrich" | "reverse" | "lookup"

required

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.

debug.matchedComponents

object

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.

debug.scoreCaps

array<string>

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.

debug.searchScore

number<double>

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.

error

AddressErrorResponse

required

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.

error.code

AddressErrorCode

required

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.

error.message

string

required

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.

error.status

integer

required

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.

error.details

object

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.

error.request_id

string

required

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. 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 stable identifiers as strings

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 Prontiq fields for match decisions

Use prontiqMatchScore and prontiqMatchQuality for accept, confirm, or reject workflows.

Treat G-NAF confidence as provenance

confidence tells you about source-record support. It is not request match quality.

Remember reliability is inverted

Lower geocode.reliability values indicate more precise geocodes.

Keep debug out of product logic

debug.searchScore is optional, unstable, and diagnostic only.

Preserve v1 snake_case fields

Keep distance_m, address_count, top_left, bottom_right, and error.request_id exactly as documented.

Treat optional nested objects defensively

geocode, location, boundaries, and individual boundary fields can be absent or null.

Use Enrich after selection

Autocomplete is a compact suggestion flow. Call Enrich with the selected id when your application needs coordinates and boundary data.

Re-enrich stored IDs periodically

Boundary and geocode metadata can change across source data releases even when the address id remains stable.

Handle stale IDs explicitly

A NOT_FOUND response from Enrich means the stored id no longer resolves in the current public corpus.

Getting Started

Address API

SDKs

Data Dictionary

Overview

How to read this page

Quick reference

How G-NAF powers the API

Autocomplete

Validate

Enrich

Reverse geocode

Postcode lookup

Suburb lookup

Field reference

Fields not present in default responses

Alias, canonical values, and storage

Freshness and lifecycle

Semantic origin table

Implementation checklist

External references

​Overview

​How to read this page

​Quick reference

​How G-NAF powers the API

Autocomplete

Validate

Enrich

Reverse geocode

Postcode lookup

Suburb lookup

​Field reference

​Fields not present in default responses

​Alias, canonical values, and storage

​Freshness and lifecycle

​Semantic origin table

​Implementation checklist

​External references

Overview

How to read this page

Quick reference

How G-NAF powers the API

Field reference

Fields not present in default responses

Alias, canonical values, and storage

Freshness and lifecycle

Semantic origin table

Implementation checklist

External references