My Geocode

Guides

Validate a postal code before you save it

· 3 min read · My Geocode · #postal-code#validation#forms

A postal code field that only checks length and character format will happily accept a code that is perfectly formatted and completely wrong. Actual validation means checking that the code resolves to a real place.

The validation call

Pass the code and the country's ISO 3166-1 alpha-2 code to /v1/postcode. A valid combination returns at least one result with coordinates and location components.

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"}}
  ]
}

Treating an empty result as invalid

If results comes back empty, the postal code and country combination does not correspond to a known location. That is your signal to reject the form field with a clear message, rather than letting a fabricated code slip through to a shipping label later.

Validation is not the same as an exact address match

A postal code covers an area, sometimes a small one and sometimes a large one depending on the country, so a passing validation confirms the code exists, not that it matches the specific street address also entered on the form. Pair a postcode validation with a forward geocoding check against the full address when you need both the code and the street to agree.

A mistake worth avoiding

Rejecting a code purely because it does not match your own formatting expectations, before you have even sent it to the API, throws away valid input over a cosmetic difference. A code typed with a missing space, extra spacing, or inconsistent case is often still a valid postal code once normalized. Trim and normalize whitespace and case in the field before you call /v1/postcode, rather than rejecting the entry outright for a formatting quirk that the lookup itself would have tolerated.

An edge case: right code, wrong country

A postal code that is syntactically valid can still fail validation simply because the wrong country was selected alongside it, since the same numeric or alphanumeric pattern can be a valid code in more than one country's system. If a lookup comes back empty for a code the customer insists is correct, double check that the country field matches what the customer actually meant before treating the postal code itself as the problem.

Where to run this check

Run the check when the field loses focus or on form submission, not on every keystroke, since a postal code is usually typed in full before it is meaningful to validate. This keeps the check to one request per submission attempt rather than one per character typed.

Cost of doing this everywhere

One validation call per form submission is a single request. Even a form with heavy traffic will use a small fraction of the 2,500 free requests a day included with every key, or available from a single address without one, purely on postal code validation.

Catching a bad postal code before it reaches a shipping label is worth the one extra request it takes. Full parameter details are on the postal code lookup docs.

More in Guides