Choose an Australian suburb from a postcode

Fill one clear suburb or offer editable suburb choices for an Australian geographic postcode.

JavaScript (browser)Get the complete example ↓
On this page

Working example

HTML + form.js
Use this example

Keep the postcode and suburb separate

An Australian postcode can cover several suburbs. Bind an editable suburb input to city, then bind its native datalist to localities. The host owns these controls, their labels, their field names, and submission.

HTML
<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>
  <button class="submit" type="submit">Use these details</button>
</form>

Replace YOUR_PUBLIC_API_KEY with a Public key from example setup. Allow your site's hostname and localhost when developing. Serve the file over HTTP.

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.

Choose when a postcode covers several suburbs

A non-null city fills the suburb input. A null city leaves it editable and offers the returned localities as suggestions. Do not infer a primary suburb from one returned option: conflicting source evidence can prevent automatic filling even when only one option qualifies for display.

Choosing a suggestion fills the host's bound city, state, and state_name fields. Only fields present in your HTML are filled. The bubbling parse event keeps the unchanged API response in answer; selection separately records an explicit { city, state, state_name } choice. Hosts with their own suggestion UI can call the event's select(index) callback. Old callbacks stop working after postcode or country changes.

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.

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.

Download HTML
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; font-family: system-ui, sans-serif; color: #172126; background: #fff; }
    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: #57656b; font-size: 14px; }
    .notice { padding: 12px 14px; background: #f2f6f7; border-radius: 8px; }
    .examples { display: flex; flex-wrap: wrap; gap: 8px; margin: 20px 0; }
    button, input { font: inherit; } button { cursor: pointer; }
    .examples button { background: white; border: 1px solid #cad3d7; border-radius: 20px; padding: 6px 12px; font-size: 13px; }
    label { display: block; font-size: 14px; font-weight: 600; margin: 18px 0 7px; }
    input { box-sizing: border-box; padding: 11px 12px; width: 100%; border: 1px solid #b8c5cc; border-radius: 7px; color: inherit; background: white; }
    input:focus, button:focus-visible { outline: 2px solid #177d96; outline-offset: 2px; }
    .row { display: grid; grid-template-columns: 1fr 110px; gap: 16px; }
    .status { min-height: 42px; font-size: 14px; color: #44565f; }
    .submit { color: white; background: #172126; padding: 12px 18px; border: 0; border-radius: 7px; }
    pre { overflow-x: auto; background: #f4f6f7; padding: 14px; border-radius: 8px; font-size: 12px; line-height: 1.5; }
    details { margin-top: 24px; } summary { cursor: pointer; font-size: 14px; }
    footer { margin-top: 28px; } a { color: #126981; }
    @media (max-width: 420px) { body { padding: 20px; } .row { grid-template-columns: 1fr; gap: 0; } }
  </style>
  <script src="https://cdn.parseapi.com/v1/form.js" data-key="YOUR_PUBLIC_API_KEY" defer></script>
</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 -->
  <div class="examples" aria-label="Example postcodes">
    <button type="button" data-postcode="2000">2000 · Sydney area</button>
    <button type="button" data-postcode="3000">3000 · Melbourne</button>
    <button type="button" data-postcode="0800">0800 · Darwin</button>
  </div>
  <!-- example:form -->
  <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>
    <button class="submit" type="submit">Use these details</button>
  </form>
  <!-- /example:form -->
  <div id="submitted" hidden>
    <p>These editable details are ready for your form.</p>
    <pre id="submitted-values"></pre>
  </div>
  <details>
    <summary>Postcode response and selected suburb</summary>
    <p class="hint">The postcode response stays unchanged. Your suburb choice is shown separately.</p>
    <pre id="response">Enter a postcode to see its response.</pre>
  </details>
  <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');
  const response = document.getElementById('response');
  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.';
    response.textContent = JSON.stringify({ postcode_response: detail.answer, selected_suburb: detail.selection || null }, null, 2);
    document.getElementById('submitted').hidden = true;
  });
  document.querySelectorAll('[data-postcode]').forEach(button => button.addEventListener('click', () => {
    postcode.value = button.dataset.postcode;
    postcode.dispatchEvent(new Event('input', { bubbles: true }));
    postcode.dispatchEvent(new Event('blur'));
  }));
  document.getElementById('place').addEventListener('submit', event => {
    event.preventDefault(); // Demo only: a real host form uses its own submission.
    document.getElementById('submitted-values').textContent = JSON.stringify(Object.fromEntries(new FormData(event.currentTarget)), null, 2);
    document.getElementById('submitted').hidden = false;
  });
</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 →