Choose an Australian suburb from a postcode

Add Australian postcode autofill with editable suburb suggestions and state fields.

On this page

Working example

HTML + form.js

Run the example

australian-postcode-suburbs.html

Replace YOUR_PUBLIC_API_KEY in the downloaded file with your public key. Add localhost to that key's allowed domains. In a terminal in the download folder, run:

Terminal · Python 3

python3 -m http.server 8000

Open localhost:8000/australian-postcode-suburbs.html. When publishing, add your website's hostname to the key. Keep secret keys on your server.

Need a key? Set up this example

Keep the postcode and suburb separate

An Australian postcode can cover several suburbs, so postcode autofill needs a choice as well as a lookup. Connect your suburb input to city and its native datalist to localities. The fields remain part of your own form.

HTML

<script src="https://cdn.parseapi.com/v1/form.js" data-key="YOUR_PUBLIC_API_KEY" data-parse-version="2.0.0" defer></script>
<form id="place">
  <label for="postcode">Postcode</label>
  <input id="postcode" name="postcode" type="text" inputmode="numeric" autocomplete="postal-code" maxlength="4" data-parse="postal" data-parse-country="AU" data-parse-ui="none" aria-describedby="status" placeholder="e.g. 2000">
  <div class="row">
    <div>
      <label for="suburb">Suburb</label>
      <input id="suburb" name="suburb" type="text" autocomplete="off" list="suburbs" data-parse-from="postcode" data-parse-fill="city" placeholder="Type or choose a suburb" aria-describedby="suburb-hint">
      <datalist id="suburbs" data-parse-from="postcode" data-parse-fill="localities"></datalist>
    </div>
    <div>
      <label for="state">State</label>
      <input id="state" name="state" type="text" autocomplete="address-level1" data-parse-from="postcode" data-parse-fill="state" placeholder="NSW">
    </div>
  </div>
  <p id="suburb-hint" class="hint">Click the suburb field to see suggestions. You can always type your own.</p>
  <p id="status" class="status" role="status">Enter all four postcode digits to look up the area.</p>
</form>

The postcode remains text to preserve leading zeroes. data-parse-country="AU" makes Australia explicit, and form.js waits for four digits before requesting a lookup. The include selects API 2.0.0 with data-parse-version, so suburb choices work even when your team's default is an older version.

Choose when a postcode covers several suburbs

Try 2000: the suburb field offers several choices and the state fills as NSW. Choosing SYDNEY keeps that suburb with the postcode. Both fields remain editable.

When city has a value, the script fills it. When it is null, the person chooses from localities or types their own suburb. Leave that choice to them even if only one suggestion is shown; the API has not identified it as the primary suburb.

Choosing a suggestion fills any bound city, state, and state_name fields present in your HTML. The download submits postcode, suburb, and state under those field names.

Fields stay editable and pending responses respect manual corrections. A lookup failure leaves manual entry and submission available. Changing the postcode clears generated values and old suggestions. If your own country picker changes data-parse-country, call parseform.scan() immediately.

For your own menu, listen for the bubbling parse event. Its answer contains the unchanged postcode response and selection holds an explicit { city, state, state_name } choice. Call that event's select(index) callback when the person chooses a suggestion. Old callbacks stop working after postcode or country changes. Keep the host's fields editable.

Geographic lookup

This example selects geographic postcode localities. It does not verify an individual address or postal delivery. Using G-NAF-derived data for mailing requires the additional address-confirmation step specified in the source licence; this example does not perform that workflow.

Incorporates or developed using G-NAF © Geoscape Australia licensed by the Commonwealth of Australia under the Open Geo-coded National Address File (G-NAF) End User Licence Agreement. August 2026 edition, selected and reformatted by ParseAPI. Source notice and reuse terms, G-NAF licence.

Complete example

One HTML file with your fields, styles, and the form.js include. Replace YOUR_PUBLIC_API_KEY with your public key, then run it on a domain you have added to that key.

View and copy the complete source

australian-postcode-suburbs.html

<!doctype html>
<html lang="en-AU">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Australian postcode and suburb</title>
  <style>
    :root { color-scheme: light dark; --ink: #172126; --muted: #57656b; --surface: #fff; --line: #b8c5cc; --focus: #177d96; font-family: system-ui, sans-serif; color: var(--ink); background: var(--surface); }
    @media (prefers-color-scheme: dark) { :root:not([data-theme="light"]) { --ink: #e8eef0; --muted: #a6b4ba; --surface: #151b1e; --line: #50626c; --focus: #72d1e5; } }
    :root[data-theme="dark"] { color-scheme: dark; --ink: #e8eef0; --muted: #a6b4ba; --surface: #151b1e; --line: #50626c; --focus: #72d1e5; }
    :root[data-theme="light"] { color-scheme: light; }
    body { margin: 0; padding: 28px; }
    main { max-width: 560px; margin: auto; }
    h1 { font-size: 28px; letter-spacing: -.03em; margin: 0 0 12px; }
    p { line-height: 1.55; } .intro, .notice, .hint, footer { color: var(--muted); font-size: 14px; }
    .notice { padding: 12px 14px; border: 1px solid var(--line); border-radius: 8px; }
    label { display: block; font-size: 14px; font-weight: 600; margin: 18px 0 7px; }
    input { font: inherit; box-sizing: border-box; padding: 11px 12px; width: 100%; border: 1px solid var(--line); border-radius: 7px; color: inherit; background: var(--surface); }
    input:focus { outline: 2px solid var(--focus); outline-offset: 2px; }
    .row { display: grid; grid-template-columns: 1fr 110px; gap: 16px; }
    .status { min-height: 22px; font-size: 14px; color: var(--muted); }
    footer { margin-top: 28px; font-size: 12px; line-height: 1.6; } a { color: var(--focus); }
    @media (max-width: 420px) { body { padding: 20px; } .row { grid-template-columns: 1fr; gap: 0; } }
  </style>
</head>
<body>
<main>
  <h1>Find your suburb.</h1>
  <p class="intro">Enter an Australian postcode. Choose a suburb when there are several, or keep your own entry.</p>
  <!-- PREVIEW_NOTICE -->
  <!-- example:form -->
  <script src="https://cdn.parseapi.com/v1/form.js" data-key="YOUR_PUBLIC_API_KEY" data-parse-version="2.0.0" defer></script>
  <form id="place">
    <label for="postcode">Postcode</label>
    <input id="postcode" name="postcode" type="text" inputmode="numeric" autocomplete="postal-code" maxlength="4" data-parse="postal" data-parse-country="AU" data-parse-ui="none" aria-describedby="status" placeholder="e.g. 2000">
    <div class="row">
      <div>
        <label for="suburb">Suburb</label>
        <input id="suburb" name="suburb" type="text" autocomplete="off" list="suburbs" data-parse-from="postcode" data-parse-fill="city" placeholder="Type or choose a suburb" aria-describedby="suburb-hint">
        <datalist id="suburbs" data-parse-from="postcode" data-parse-fill="localities"></datalist>
      </div>
      <div>
        <label for="state">State</label>
        <input id="state" name="state" type="text" autocomplete="address-level1" data-parse-from="postcode" data-parse-fill="state" placeholder="NSW">
      </div>
    </div>
    <p id="suburb-hint" class="hint">Click the suburb field to see suggestions. You can always type your own.</p>
    <p id="status" class="status" role="status">Enter all four postcode digits to look up the area.</p>
  </form>
  <!-- /example:form -->
  <footer>
    Geographic postcode lookup does not confirm a mailing address or delivery.<br>
    Incorporates or developed using G-NAF © Geoscape Australia licensed by the Commonwealth of Australia under the Open Geo-coded National Address File (G-NAF) End User Licence Agreement. August 2026 edition, selected and reformatted by ParseAPI.<br>
    <a href="https://parseapi.com/legal/attribution#postal-au">Source notice and reuse terms</a> · <a href="https://data.gov.au/data/dataset/19432f89-dc3a-4ef3-b943-5326ef1dbecc/resource/09f74802-08b1-4214-a6ea-3591b2753d30/download/20160226-eula-open-g-naf.pdf">G-NAF licence</a>
  </footer>
</main>
<script>
  const postcode = document.getElementById('postcode');
  const status = document.getElementById('status');
  postcode.addEventListener('parse', event => {
    const detail = event.detail;
    if (detail.status === 'checking') status.textContent = 'Finding suburbs…';
    else if (detail.selection) status.textContent = detail.selection.city + ', ' + detail.selection.state + ' selected. You can edit these details.';
    else if (detail.answer && detail.answer.city) status.textContent = 'Suburb found. Check the details and edit if needed.';
    else if (detail.suggestions.length) status.textContent = detail.suggestions.length + ' suburb suggestions. Choose a suburb or type your own.';
    else if (detail.status === 'filled') status.textContent = 'No suburb suggestions for this postcode. Enter your suburb manually.';
    else if (detail.reason === 'unavailable') status.textContent = 'Lookup unavailable. You can still enter and use your details.';
    else status.textContent = 'Enter all four postcode digits to look up the area.';
  });
  // Demo only: the host application owns submission.
  document.getElementById('place').addEventListener('submit', event => event.preventDefault());
</script>
</body>
</html>

Need a key? Set up this browser example. For every field and parameter, see Postal API reference.

Build something else

All tutorials →