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

# Suburb Lookup

> Find postcodes, counts, and bounds for an Australian suburb.

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

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

## 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](/guides/address/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

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.prontiq.dev/v1/address/lookup/suburb?suburb=bondi+beach&state=NSW" \
    -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.lookupSuburb("bondi beach", "NSW");
  const { result } = response;

  console.log(result.postcodes);
  ```

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

  client = Prontiq()

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

  print(response.postcodes)
  ```
</CodeGroup>

## Response

```json theme={null}
{
  "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](/api-reference/suburb-lookup) for the
generated schema and live playground.