Add postal code auto-fill to a shipping form

A shipping form with separate fields for postal code, city, and region asks a customer to type information that a single postal code often already implies.

Looking up the code

Once a customer finishes typing a postal code and selects a country, or if country is already known from their account, send both to /v1/postcode.

GET /v1/postcode?code=SW1A 1AA&country=GB

{
  "status": "ok",
  "postcode": "SW1A 1AA",
  "country_code": "GB",
  "results": [
    {"lat": 51.5014, "lon": -0.1419, "components": {"city": "London", "region": "Greater London", "country": "GB"}}
  ]
}

Filling the form fields

Populate the city and region fields directly from the components object in the result, and let the customer confirm or correct them rather than locking the fields entirely, since a postal code occasionally spans a boundary or covers more than one commonly used place name.

A second example: prefilling a billing region for tax purposes

The same lookup fits a signup or billing form that needs a customer's region for tax calculation purposes, not just a shipping form. Triggering the same postcode lookup once a billing postal code is entered fills the region field consistently in both contexts using the identical request and response shape, so the same client-side and server-side handling code can serve both forms.

Triggering the lookup at the right moment

Run the lookup once the postal code field loses focus, or once it reaches the expected length for the selected country, rather than on every keystroke, since a postal code is only meaningful to look up once it is complete. This keeps the feature to one request per completed field entry rather than one per character typed.

A common mistake to avoid

Do not hard-code a fixed expected length for every country's postal code format. A five-digit assumption that works for one country will trigger the lookup too early or never at all for a country using a different length or an alphanumeric format like the example above. Either trigger on focus loss regardless of length, or maintain a small per-country length table if you want to trigger earlier for countries you support most often.

Handling an unrecognized code

An empty results array means the code was not recognized for that country, most often because of a typo. Leave the city and region fields blank and let the customer fill them in manually rather than blocking form submission, since rejecting the field outright over an auto-fill failure is a worse experience than simply asking for manual entry in that one case.

An edge case: a code covering more than one place name

Some postal codes legitimately cover an area known locally by more than one place name, or sit right at a boundary between two commonly used city names. When this happens, showing the returned value as an editable suggestion rather than a fixed label lets the customer correct it to whichever name they actually use, without treating either as more or less official than the other.

Getting exact coordinates once the address is complete

Auto-fill from a postal code gives an area-level location, which is enough for city and region fields, but once the customer has typed a full street address on top of that, running the complete address through /v1/forward gets you the precise coordinates a shipping label or delivery routing system actually needs.

What it costs

Each completed postal code field triggers one request. A shipping form processing many orders a day still uses this feature at a modest rate, one lookup per order rather than per keystroke, keeping it well within the 2,500 free requests a day included with every key for most stores.

Auto-filling city and region from a postal code cuts a shipping form down by two fields for the large majority of customers who type a valid code. Full field definitions are on the postal code lookup docs.