Suburb Lookup

Suburb lookup returns postcodes and aggregate address information for a suburb or locality name. It can optionally filter by state.

Usage is metered in credits. See the Credits guide for response headers and usage behaviour.

When to use it

Validate a suburb/locality name before accepting a form.
Find postcodes for a selected suburb.
Aggregate across states when the suburb name is ambiguous and the user has not chosen a state yet.

Use Postcode lookup when your starting point is a 4-digit postcode.

Request

Parameter	Type	Required	Default	Description
`suburb`	string	Yes	—	Suburb/locality name, 1-100 characters.
`state`	string	No	—	Australian state or territory code: `NSW`, `VIC`, `QLD`, `SA`, `WA`, `TAS`, `NT`, or `ACT`.
`limit`	integer	No	`10`	Maximum postcodes to return, 1-20.

Examples

curl "https://api.prontiq.dev/v1/address/lookup/suburb?suburb=bondi+beach&state=NSW" \
  -H "X-Api-Key: YOUR_API_KEY"

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.lookupSuburb("bondi beach", "NSW");
const { result } = response;

console.log(result.postcodes);

from prontiq import Prontiq

client = Prontiq()

response = client.address.lookup.by_suburb(
    suburb="bondi beach",
    state="NSW",
)

print(response.postcodes)

Response

{
  "suburb": "BONDI BEACH",
  "state": "NSW",
  "postcodes": ["2026"],
  "bounds": {
    "top_left": { "lat": -33.8847, "lon": 151.2633 },
    "bottom_right": { "lat": -33.9035, "lon": 151.2849 }
  },
  "address_count": 9477
}

Field notes

Field	Meaning
`suburb`	Normalised suburb/locality name.
`state`	State filter applied, if any.
`postcodes`	Postcodes covering the suburb.
`bounds`	Optional geographic bounding box for the suburb.
`address_count`	Total addresses matched for the suburb.

When state is omitted, matching localities across states may be aggregated. Use the state filter when the user has already selected a state.

Integration tips

Keep state optional in early search flows, then ask the user to confirm where names are ambiguous.
Use bounds to frame a map, not as a delivery boundary.
Treat address_count as dataset context, not a commercial usage value.

See the Suburb lookup API reference for the generated schema and live playground.

Getting Started

Address API

SDKs

When to use it

Request

Examples

Response

Field notes

Integration tips

​When to use it

​Request

​Examples

​Response

​Field notes

​Integration tips

When to use it

Request

Examples

Response

Field notes

Integration tips