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

# Postcode Lookup

> Find localities inside an Australian postcode.

Postcode lookup returns localities inside a 4-digit Australian postcode. Use it
for postcode-first forms, locality dropdowns, and coverage checks.

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

## When to use it

* Populate locality options after a user enters a postcode.
* Check whether a postcode exists in the address dataset.
* Show address-count context for localities inside a postcode.

Use [Suburb lookup](/guides/address/suburb-lookup) when your starting point is a
suburb or locality name.

## Request

| Parameter  | Type    | Required | Default | Description                         |
| ---------- | ------- | -------- | ------- | ----------------------------------- |
| `postcode` | string  | Yes      | —       | Australian 4-digit postcode.        |
| `limit`    | integer | No       | `10`    | Maximum localities to return, 1-50. |

## Examples

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.prontiq.dev/v1/address/lookup/postcode?postcode=2000&limit=3" \
    -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.lookupPostcode("2000", 3);
  const { result } = response;

  for (const locality of result.localities) {
    console.log(`${locality.name} ${locality.state}`);
  }
  ```

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

  client = Prontiq()

  response = client.address.lookup.by_postcode(
      postcode="2000",
      limit=3,
  )

  for locality in response.localities:
      print(locality.name, locality.state)
  ```
</CodeGroup>

## Response

```json theme={null}
{
  "postcode": "2000",
  "localities": [
    { "name": "SYDNEY", "state": "NSW", "address_count": 41157 },
    { "name": "HAYMARKET", "state": "NSW", "address_count": 8650 },
    { "name": "MILLERS POINT", "state": "NSW", "address_count": 2261 }
  ]
}
```

## Field notes

| Field                        | Meaning                                                   |
| ---------------------------- | --------------------------------------------------------- |
| `postcode`                   | The postcode from the request.                            |
| `localities[].name`          | Locality/suburb name.                                     |
| `localities[].state`         | State code when available.                                |
| `localities[].address_count` | Number of addresses in that locality within the postcode. |

`address_count` is useful for ranking locality choices. It is not billing or
quota data.

## Integration tips

* Use `limit` to keep dropdowns short.
* Postcodes are strings so leading zeroes remain intact.
* If the response has no localities, let the user enter suburb/state manually or
  try [Validate](/guides/address/validate).

See the [Postcode lookup API reference](/api-reference/postcode-lookup) for the
generated schema and live playground.