Validate postal codes for every country, honestly.
208 countries in one table: 146 with format patterns mirroring the canonical Google libaddressinput shapes, and 62 flagged as having no postal system at all. Canonical normalization for UK, Canada and the Netherlands, the UK→GB alias, and a plain "this country has no postal codes" answer instead of a false failure.
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://almanac.tools/v1/postal-codes/validate?code=90210&country=US"{
"data": {
"input": "90210",
"country": "US",
"isValidFormat": true,
"hasPostalCodes": true,
"normalized": "90210",
"example": "90210"
}
}- 208
- Countries in the validation table
- 146
- Countries with postal-code formats
- 62
- Countries flagged no-postal-code
- 100
- Items per batch request
The Postal Code Validation API checks whether a postal code is structurally valid for a given country, normalizes it to canonical form, and tells you honestly when a country has no postal-code system. It validates format against 208 countries — no live address-database lookup and no paid verification subscription required.
Built for the awkward middle.
Honest "no postal codes" handling
62 of the 208 countries — UAE, Hong Kong, Qatar, Panama and more — operate no national postal-code system. Instead of failing a blank field or accepting garbage, the API returns hasPostalCodes:false and treats only an empty code as valid, so your checkout form stops demanding a code that does not exist.
Canonical normalization, not just a yes/no
A format-valid code comes back normalized: "sw1a1aa" becomes "SW1A 1AA", a Dutch "1011ac" becomes "1011 AC", a Canadian "k1a0b1" becomes "K1A 0B1". US ZIP+4 keeps its hyphen. You store one canonical form instead of every variant your users type.
Format validation without an address subscription
This is structural (format) validation against per-country patterns, not a live address-database lookup. That makes it the cheap first gate for checkout, signup and KYC forms — catch the typos and impossible codes up front before you spend a paid Google or USPS verification call.
Endpoints
Every route takes a Bearer API key. Validation runs before authentication, so a malformed request never costs you a credit.
| GET | /v1/postal-codes/validate | Validate one code against a country format. Query: code, country. |
| GET | /v1/postal-codes/countries | List every supported country, its name and whether it uses postal codes. |
| POST | /v1/postal-codes/batch | Validate up to 100 { code, country } items in one call. |
Frequently asked
Is this live address verification or just format checking?
Format checking only. The API matches a code against the structural pattern for its country (US is five digits with an optional +4, the Netherlands is four digits then two letters, and so on) — it does not look the address up in a live postal database. That is by design: it is the cheap, instant first gate that catches typos and impossible codes before you pay for a real address-verification call.
What happens for a country that has no postal codes?
You get an honest answer. 62 of the 208 supported countries — including the UAE, Hong Kong, Macau, Qatar and Panama — operate no national postal-code system. For those the response has hasPostalCodes:false, and only an empty code is treated as valid (with a reason like "United Arab Emirates does not use postal codes"). Your form can then hide or stop requiring the field instead of rejecting a blank that is actually correct.
Do you accept "UK" or only "GB"?
Both. Country codes are ISO 3166-1 alpha-2 and accepted case-insensitively, and "UK" is aliased to the canonical "GB". A validate call for the United Kingdom returns country:"GB" regardless of which you send, so you do not have to normalize the input yourself.
What is the "normalized" field for?
It is the canonical display form of a valid code: upper-cased, with the canonical single inner space inserted for the UK, Canada and the Netherlands ("sw1a1aa" → "SW1A 1AA", "k1a0b1" → "K1A 0B1", "1011ac" → "1011 AC"). US ZIP+4 keeps its hyphen. Store the normalized form and every user who types the same code in a different shape ends up with one consistent value.
How many codes can I validate in one request?
The POST /v1/postal-codes/batch endpoint takes up to 100 { code, country } items and returns one result per item, in order. It is the same validation logic as the single-code endpoint, just amortized across one round trip — useful for cleaning an existing address list or validating a multi-line cart.
Why not just use Google Address Validation?
Google and similar services do live, deliverable-address lookup and charge per call. That is the right tool when you need to confirm an address exists. This API solves the cheaper problem one step earlier: is this code even structurally possible for this country, and does this country use codes at all? Run it free on every keystroke or form submit, then reserve the paid live-lookup call for the codes that pass.
More from the almanac
Business Days & Settlement
Settlement-date and SLA-calendar math for 21 market & regional calendars.
VAT & GST Validation
Offline format + checksum validation for 36 VAT/GST schemes — no dependency on VIES uptime.
NAICS Industry Codes
NAICS 2022 lookup, keyword search, and SIC→NAICS crosswalk in one call.
Start building with Postal Code Validation.
One key unlocks every Almanac API. Free tier, no credit card, deterministic results you can pin in a test.