Postal Code Format & Regex by Country

Q: How do I get a postal code regex for a country?

/api/postal-code-formats/lookup?country=NL returns every accepted mask with a ready-to-paste anchored regex. The default separators=optional accepts 1012AB as well as 1012 AB; separators=exact requires the space.

Q: Which countries do not use postal codes?

?system=none returns them — 68 entries today. Both upstreams agree on 60 of those; the remaining rows were adjudicated one by one, because telling a developer that Chad uses TKCA 1ZZ would be a fabricated fact.

Q: What is the difference between precision national-rule and shape-only?

national-rule (23 rows) means every pattern encodes the operator's published rule — Canadian postal codes never using D, F, I, O, Q or U, for instance. shape-only (155 rows) means the pattern constrains only the count and kind of characters, so a five-digit mask will accept 00000. Filter with ?precision=national-rule when you need the strict ones.

REAL DATA

Postal code masks, copy-paste validation regexes and shape checking for 178 countries — plus the 68 that have no postal code system at all.

Authoritative reference data or standards computation

Base URL: /api/postal-code-formats
Category: Geo & Reference
Capabilities: 3 routes
Last updated: July 30, 2026

Data sources · 3: GeoNames countryInfo.txt — Postal Code Format column (snapshot 2026-07-30, CC BY 4.0)
Google libaddressinput — RegionDataConstants.java (Apache-2.0), cross-check for postal-code presence, requirement, field name and display prefix
National postal operators, cited per country by the officialSource field of GET /api/postal-code-formats

GET /api/postal-code-formats List every country's postal code format (or the countries that have none) Returns a list

All 249 entries, alphabetical by country name, 100 per request — page with offset. Filters genuinely filter; separators only changes which derived regex each pattern exposes.

Live requestRuns against the public API

No key required

GET/api/postal-code-formats?system=none

Request parameters

systemdefault any

Only return entries with this `postalCodeSystem`: `national`, `limited`, `none` or `unverified`.

search

Case- and diacritic-insensitive substring of the English country name (so `aland` finds Åland Islands), or an exact ISO 3166-1 alpha-2 or alpha-3 code.

required

Only return entries where a postal code is (or is not) required in a complete address. The entries where the source records no requirement either way have `requiredInAddress: null` and match neither value.

precisiondefault any

Only return entries whose patterns encode the operator's published rule (`national-rule`) or only a character shape (`shape-only`). Entries with no patterns have `precision: null` and are excluded by either value.

separatorsdefault optional

Which derived regex each pattern exposes: `optional` accepts one optional separator character wherever the mask writes a space or hyphen (so `1012AB` and `1012 AB` both pass); `exact` requires the mask's separators verbatim. Transforms the output, never filters it.

offsetdefault 0

Skip this many matches before returning records, for paging past the first 100.

Advanced response options6 options

countdefault 100

Limit the number of returned records (1–100). Defaults to 100.

fields

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

exclude

Return all fields except these (comma-separated).

formatdefault json

Response format: json envelope, ndjson (one record per line) or csv.

prettydefault false

Pretty-print the JSON response.

unwrapdefault false

Drop the envelope: return the raw array/object without data/meta wrapper.

Response

Example parameters are ready. Send the request to inspect the live response.

Route reference

Code, request parameters, response fields and verified examples 12 params · 10 fields · 6 examples

Code samples Ready-to-copy requests in 4 languages

curl JavaScript Python PHP

curl "https://randomapi.dev/api/postal-code-formats?system=none"

const res = await fetch("https://randomapi.dev/api/postal-code-formats?system=none");
const { data, meta } = await res.json();

import requests

data = requests.get("https://randomapi.dev/api/postal-code-formats?system=none").json()["data"]

$json = json_decode(file_get_contents(
  "https://randomapi.dev/api/postal-code-formats?system=none"
), true);
$data = $json["data"];

Parameters Route-specific request inputs 6

Parameter	Type	Default & allowed	Description
`system`	enum	default: any allowed: national \| limited \| none \| unverified \| any example: none	Only return entries with this `postalCodeSystem`: `national`, `limited`, `none` or `unverified`.
`search`	string	allowed: 1 – 60 example: nether	Case- and diacritic-insensitive substring of the English country name (so `aland` finds Åland Islands), or an exact ISO 3166-1 alpha-2 or alpha-3 code.
`required`	boolean	example: true	Only return entries where a postal code is (or is not) required in a complete address. The entries where the source records no requirement either way have `requiredInAddress: null` and match neither value.
`precision`	enum	default: any allowed: national-rule \| shape-only \| any example: national-rule	Only return entries whose patterns encode the operator's published rule (`national-rule`) or only a character shape (`shape-only`). Entries with no patterns have `precision: null` and are excluded by either value.
`separators`	enum	default: optional allowed: optional \| exact example: exact	Which derived regex each pattern exposes: `optional` accepts one optional separator character wherever the mask writes a space or hyphen (so `1012AB` and `1012 AB` both pass); `exact` requires the mask's separators verbatim. Transforms the output, never filters it.
`offset`	int	default: 0 allowed: 0 – 248 example: 100	Skip this many matches before returning records, for paging past the first 100.

system enum

Only return entries with this `postalCodeSystem`: `national`, `limited`, `none` or `unverified`.

default: any

allowed: national | limited | none | unverified | any

example: system=none

search string

Case- and diacritic-insensitive substring of the English country name (so `aland` finds Åland Islands), or an exact ISO 3166-1 alpha-2 or alpha-3 code.

allowed: 1 – 60

example: search=nether

required boolean

example: required=true

precision enum

default: any

allowed: national-rule | shape-only | any

example: precision=national-rule

separators enum

default: optional

allowed: optional | exact

example: separators=exact

offset int

Skip this many matches before returning records, for paging past the first 100.

default: 0

allowed: 0 – 248

example: offset=100

Universal parameters Shared response and formatting options 6

Parameter	Type	Default & allowed	Description
`count`	int	default: 100 allowed: 1 – 100 example: 3	Limit the number of returned records (1–100). Defaults to 100.
`fields`	list	example: country,countryCode	Return only these fields (comma-separated). Mutually exclusive with 'exclude'.
`exclude`	list	example: officialSource	Return all fields except these (comma-separated).
`format`	enum	default: json allowed: json \| ndjson \| csv example: csv	Response format: json envelope, ndjson (one record per line) or csv.
`pretty`	boolean	default: false example: true	Pretty-print the JSON response.
`unwrap`	boolean	default: false example: true	Drop the envelope: return the raw array/object without data/meta wrapper.

count int

Limit the number of returned records (1–100). Defaults to 100.

default: 100

allowed: 1 – 100

example: count=3

fields list

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

example: fields=country,countryCode

exclude list

Return all fields except these (comma-separated).

example: exclude=officialSource

format enum

Response format: json envelope, ndjson (one record per line) or csv.

default: json

allowed: json | ndjson | csv

example: format=csv

pretty boolean

Pretty-print the JSON response.

default: false

example: pretty=true

unwrap boolean

Drop the envelope: return the raw array/object without data/meta wrapper.

default: false

example: unwrap=true

Response schema Fields returned in each record 10

Field	Type	Description	Example
`country`	string	English ISO 3166-1 name, joined from the country dataset at load time.	Netherlands
`countryCode`	string	ISO 3166-1 alpha-2 code (uppercase).	NL
`postalCodeSystem`	string	`national` (a system covering the territory, with at least one verified format), `limited` (codes cover part of the territory, or no single expressible format is published), `none` (no postal code system — an address form should not ask for one) or `unverified` (the two upstreams disagree and we could not settle it against the operator).	national
`patterns`	object[]	Every accepted written form, most common first. Each entry has `mask` (the written form in this API's mask alphabet), `regex` (an anchored, capture-free ECMAScript source in the requested `separators` mode — case-insensitive by construction, so it needs no `/i` flag and works unchanged in an HTML `pattern=` attribute) and `example` (a shape-conforming illustration of the written form, not necessarily a code the operator has assigned). Empty unless `postalCodeSystem` is `national` or `limited`.	[{"mask":"#### @@","regex":"^[1-9]\\d{3}[ -]?(?:[A-RT-Za-rt-z][A-Za-z]\|[Ss][BCE-RT-Zbce-rt-z])$","example":"1012 AB"}]
`precision` nullable	string	`national-rule` when every pattern encodes the operator's published rule (letter sets, digit ranges, fixed prefixes); `shape-only` when at least one pattern constrains only the count and kind of characters, so it accepts shape-correct codes the operator never assigns; `null` when there are no patterns.	national-rule
`postalCodeName`	string	What the country's own address metadata calls the field: `postal code`, `zip code`, `eircode` or `PIN code`. Mapped 1:1 from libaddressinput's `zip_name_type`, with the key absent meaning `postal code`. Not a claim about the local-language term — `CEP`, `PLZ`, `CAP` and 郵便番号 are deliberately out of scope.	postal code
`requiredInAddress` nullable	boolean	Whether a postal code is required in a complete address: `true` where libaddressinput's `require` contains `Z`, `false` where `require` is present without it, and `null` where `require` is absent entirely — the source records no requirement either way. Rows where it is `null` match neither `required=true` nor `required=false`.	true
`countryPrefix` nullable	string	The optional international display prefix written before the code (`L-`, `LT-`, `CH-`, `AZ `). The prefix is not part of the code; `/validate` accepts it with or without its trailing separator and strips it. `null` where none is documented.	null
`note` nullable	string	Honest caveats: partial coverage, legacy forms, letters the operator excludes, why this row departs from the primary source, what is deliberately excluded. Every factual claim here is covered by `officialSource` or by a defect visible in the pinned snapshot itself. `null` where there is nothing to disclose.	PostNL does not assign the letter combinations SA, SD or SS, and the numeric part never starts with 0. GeoNames' mask encodes neither restriction.
`officialSource` nullable	string	HTTPS URL of the national operator or standards publication this row was verified against — a citation for a human, never fetched at request time. Non-null for every `national-rule` row. `null` where the row is taken verbatim from the agreeing upstreams, or where a divergence is proven by a defect inside the pinned snapshots and needs no external fact.	https://www.postnl.nl/en/find-a-postcode/

country string

English ISO 3166-1 name, joined from the country dataset at load time.

example: Netherlands

countryCode string

ISO 3166-1 alpha-2 code (uppercase).

example: NL

postalCodeSystem string

`national` (a system covering the territory, with at least one verified format), `limited` (codes cover part of the territory, or no single expressible format is published), `none` (no postal code system — an address form should not ask for one) or `unverified` (the two upstreams disagree and we could not settle it against the operator).

example: national

patterns object[]

Every accepted written form, most common first. Each entry has `mask` (the written form in this API's mask alphabet), `regex` (an anchored, capture-free ECMAScript source in the requested `separators` mode — case-insensitive by construction, so it needs no `/i` flag and works unchanged in an HTML `pattern=` attribute) and `example` (a shape-conforming illustration of the written form, not necessarily a code the operator has assigned). Empty unless `postalCodeSystem` is `national` or `limited`.

example: [{"mask":"#### @@","regex":"^[1-9]\\d{3}[ -]?(?:[A-RT-Za-rt-z][A-Za-z]|[Ss][BCE-RT-Zbce-rt-z])$","example":"1012 AB"}]

precision string nullable

`national-rule` when every pattern encodes the operator's published rule (letter sets, digit ranges, fixed prefixes); `shape-only` when at least one pattern constrains only the count and kind of characters, so it accepts shape-correct codes the operator never assigns; `null` when there are no patterns.

example: national-rule

postalCodeName string

What the country's own address metadata calls the field: `postal code`, `zip code`, `eircode` or `PIN code`. Mapped 1:1 from libaddressinput's `zip_name_type`, with the key absent meaning `postal code`. Not a claim about the local-language term — `CEP`, `PLZ`, `CAP` and 郵便番号 are deliberately out of scope.

example: postal code

requiredInAddress boolean nullable

Whether a postal code is required in a complete address: `true` where libaddressinput's `require` contains `Z`, `false` where `require` is present without it, and `null` where `require` is absent entirely — the source records no requirement either way. Rows where it is `null` match neither `required=true` nor `required=false`.

example: true

countryPrefix string nullable

The optional international display prefix written before the code (`L-`, `LT-`, `CH-`, `AZ `). The prefix is not part of the code; `/validate` accepts it with or without its trailing separator and strips it. `null` where none is documented.

example: null

note string nullable

Honest caveats: partial coverage, legacy forms, letters the operator excludes, why this row departs from the primary source, what is deliberately excluded. Every factual claim here is covered by `officialSource` or by a defect visible in the pinned snapshot itself. `null` where there is nothing to disclose.

example: PostNL does not assign the letter combinations SA, SD or SS, and the numeric part never starts with 0. GeoNames' mask encodes neither restriction.

officialSource string nullable

HTTPS URL of the national operator or standards publication this row was verified against — a citation for a human, never fetched at request time. Non-null for every `national-rule` row. `null` where the row is taken verbatim from the agreeing upstreams, or where a divergence is proven by a defect inside the pinned snapshots and needs no external fact.

example: https://www.postnl.nl/en/find-a-postcode/

Documented examples

Build-generated requests and complete responses 6

Countries with no postal code system /api/postal-code-formats?system=none

GET /api/postal-code-formats?system=none

{
  "data": [
    {
      "country": "Angola",
      "countryCode": "AO",
      "postalCodeSystem": "none",
      "patterns": [],
      "precision": null,
      "postalCodeName": "postal code",
      "requiredInAddress": null,
      "countryPrefix": null,
      "note": null,
      "officialSource": null
    },
    {
      "country": "Antarctica",
      "countryCode": "AQ",
      "postalCodeSystem": "none",
      "patterns": [],
      "precision": null,
      "postalCodeName": "postal code",
      "requiredInAddress": null,
      "countryPrefix": null,
      "note": null,
      "officialSource": null
    },
    {
      "country": "Antigua and Barbuda",
      "countryCode": "AG",
      "postalCodeSystem": "none",
      "patterns": [],
      "precision": null,
      "postalCodeName": "postal code",
      "requiredInAddress": false,
      "countryPrefix": null,
      "note": null,
      "officialSource": null
    },
    {
      "country": "Aruba",
    …
    "generatedAt": "2026-07-30T15:14:08.000Z"
  }
}

Every format we encode to the operator's own rule /api/postal-code-formats?precision=national-rule&count=100

GET /api/postal-code-formats?precision=national-rule&count=100

{
  "data": [
    {
      "country": "Canada",
      "countryCode": "CA",
      "postalCodeSystem": "national",
      "patterns": [
        {
          "mask": "@#@ #@#",
          "regex": "^[ABCEGHJ-NPRSTVXYabceghj-nprstvxy]\\d[ABCEGHJ-NPRSTV-Zabceghj-nprstv-z][ -]?\\d[ABCEGHJ-NPRSTV-Zabceghj-nprstv-z]\\d$",
          "example": "K1A 0B1"
        }
      ],
      "precision": "national-rule",
      "postalCodeName": "postal code",
      "requiredInAddress": true,
      "countryPrefix": null,
      "note": "The cited Canada Post page publishes only the written form — the first three characters separated from the last three by a space, never a hyphen — and states no letter set at all, so the letter classes encoded here are not sourced to Canada Post. The first character is restricted to the 18 postal-district letters A, B, C, E, G, H, J, K, L, M, N, P, R, S, T, V, X and Y, the third and sixth to those plus W and Z; D, F, I, O, Q and U are therefore rejected in all three positions and W and Z never appear first. Both classes are the ones GeoNames' own regex column records, which is the only source this dataset has for them. GeoNames' mask encodes neither restriction, and its regex cell for the same row ends in a stray space after its `$` anchor, so as written it matches nothing at all.",
      "officialSource": "https://www.canadapost-postescanada.ca/cpc/en/support/kb/sending/general-information/how-to-address-mail-and-parcels"
    },
    {
      "country": "Christmas Island",
      "countryCode": "CX",
      "postalCodeSystem": "national",
      "patterns": [
        {
          "mask": "6798",
          "regex": "^6798$",
          "example": "6798"
        }
      ],
      "precision": "national-rule",
      "postalCodeName": "postal code",
      "requiredInAddress": null,
      "countryPrefix": null,
      "note": "Christmas Island has a single Australian postcode, 6798. GeoNames records only the four-digit shape.",
      "officialSource": "https://auspost.com.au/postcode"
    },
    {
      "country": "Cocos (Keeling) Islands",
    …
    "generatedAt": "2026-07-30T15:14:08.000Z"
  }
}

Find the Netherlands without typing the whole name /api/postal-code-formats?search=nether

GET /api/postal-code-formats?search=nether

{
  "data": [
    {
      "country": "Caribbean Netherlands",
      "countryCode": "BQ",
      "postalCodeSystem": "none",
      "patterns": [],
      "precision": null,
      "postalCodeName": "postal code",
      "requiredInAddress": null,
      "countryPrefix": null,
      "note": null,
      "officialSource": null
    },
    {
      "country": "Netherlands",
      "countryCode": "NL",
      "postalCodeSystem": "national",
      "patterns": [
        {
          "mask": "#### @@",
          "regex": "^[1-9]\\d{3}[ -]?(?:[A-RT-Za-rt-z][A-Za-z]|[Ss][BCE-RT-Zbce-rt-z])$",
          "example": "1012 AB"
        }
      ],
      "precision": "national-rule",
      "postalCodeName": "postal code",
      "requiredInAddress": true,
      "countryPrefix": null,
      "note": "PostNL does not assign the letter combinations SA, SD or SS, and the numeric part never starts with 0. GeoNames' mask encodes neither restriction.",
      "officialSource": "https://www.postnl.nl/en/find-a-postcode/"
    }
  ],
  "meta": {
    "endpoint": "postal-code-formats",
    "count": 2,
    "params": {
      "system": "any",
      "search": "nether",
      "precision": "any",
    …
    "generatedAt": "2026-07-30T15:14:08.000Z"
  }
}

Where a postal code is mandatory in the address /api/postal-code-formats?required=true&count=100

GET /api/postal-code-formats?required=true&count=100

{
  "data": [
    {
      "country": "Åland Islands",
      "countryCode": "AX",
      "postalCodeSystem": "national",
      "patterns": [
        {
          "mask": "22###",
          "regex": "^22\\d{3}$",
          "example": "22123"
        }
      ],
      "precision": "shape-only",
      "postalCodeName": "postal code",
      "requiredInAddress": true,
      "countryPrefix": "AX-",
      "note": "Åland has no numbering plan of its own: its codes are Finnish five-digit codes beginning 22, where GeoNames records only the bare five-digit shape and its own regex column records no prefix either. Neither Posti nor Åland Post publishes the reserved block on a page we could cite, so the 22 prefix comes from other address metadata and the row is labelled shape-only. We record the relationship but do not model it.",
      "officialSource": "https://www.posti.fi/en/private/sending/postal-codes"
    },
    {
      "country": "American Samoa",
      "countryCode": "AS",
      "postalCodeSystem": "national",
      "patterns": [
        {
          "mask": "96799",
          "regex": "^96799$",
          "example": "96799"
        },
        {
          "mask": "96799-####",
          "regex": "^96799[ -]?\\d{4}$",
          "example": "96799-1234"
        }
      ],
      "precision": "shape-only",
      "postalCodeName": "zip code",
      "requiredInAddress": true,
      "countryPrefix": null,
    …
    "generatedAt": "2026-07-30T15:14:08.000Z"
  }
}

Second page of the whole table /api/postal-code-formats?count=100&offset=100

GET /api/postal-code-formats?count=100&offset=100

{
  "data": [
    {
      "country": "Hungary",
      "countryCode": "HU",
      "postalCodeSystem": "national",
      "patterns": [
        {
          "mask": "####",
          "regex": "^\\d{4}$",
          "example": "1234"
        }
      ],
      "precision": "shape-only",
      "postalCodeName": "postal code",
      "requiredInAddress": true,
      "countryPrefix": null,
      "note": null,
      "officialSource": null
    },
    {
      "country": "Iceland",
      "countryCode": "IS",
      "postalCodeSystem": "national",
      "patterns": [
        {
          "mask": "###",
          "regex": "^\\d{3}$",
          "example": "123"
        }
      ],
      "precision": "shape-only",
      "postalCodeName": "postal code",
      "requiredInAddress": null,
      "countryPrefix": null,
      "note": null,
      "officialSource": null
    },
    {
      "country": "India",
    …
    ]
  }
}

The whole table as CSV /api/postal-code-formats?format=csv&count=100

GET /api/postal-code-formats?format=csv&count=100

country,countryCode,postalCodeSystem,patterns,precision,postalCodeName,requiredInAddress,countryPrefix,note,officialSource
Afghanistan,AF,national,"[{""mask"":""####"",""regex"":""^\\d{4}$"",""example"":""1234""}]",shape-only,postal code,,,"GeoNames records no format for Afghanistan; Google's address metadata does carry a postal code field. No Afghan Post publication of the format could be retrieved, so only the four-digit count that other address metadata records is encoded, and the row stays shape-only.",https://www.afghanpost.gov.af/
Åland Islands,AX,national,"[{""mask"":""22###"",""regex"":""^22\\d{3}$"",""example"":""22123""}]",shape-only,postal code,true,AX-,"Åland has no numbering plan of its own: its codes are Finnish five-digit codes beginning 22, where GeoNames records only the bare five-digit shape and its own regex column records no prefix either. Neither Posti nor Åland Post publishes the reserved block on a page we could cite, so the 22 prefix comes from other address metadata and the row is labelled shape-only. We record the relationship but do not model it.",https://www.posti.fi/en/private/sending/postal-codes
Albania,AL,national,"[{""mask"":""####"",""regex"":""^\\d{4}$"",""example"":""1234""}]",shape-only,postal code,,,,
Algeria,DZ,national,"[{""mask"":""#####"",""regex"":""^\\d{5}$"",""example"":""12345""}]",shape-only,postal code,,,,
American Samoa,AS,national,"[{""mask"":""96799"",""regex"":""^96799$"",""example"":""96799""},{""mask"":""96799-####"",""regex"":""^96799[ -]?\\d{4}$"",""example"":""96799-1234""}]",shape-only,zip code,true,,"American Samoa's mail is carried by USPS under the single ZIP Code 96799. GeoNames records `#####-####` as the format and, in its regex column, the bare string `96799` — not a regex. The optional four-digit ZIP+4 add-on follows USPS Publication 28.",https://pe.usps.com/text/pub28/welcome.htm
Andorra,AD,national,"[{""mask"":""AD###"",""regex"":""^[Aa][Dd]\\d{3}$"",""example"":""AD123""}]",shape-only,postal code,,,"GeoNames writes the `AD` prefix inside the mask but treats it as strippable in its own regex (`^(?:AD)*(\d{3})$`). We keep it as part of the code, as the mask writes it. Correus Andorrà's site does not resolve, so the assigned range inside the AD prefix is not encoded.",
Angola,AO,none,[],,postal code,,,,
Anguilla,AI,national,"[{""mask"":""####"",""regex"":""^\\d{4}$"",""example"":""1234""}]",shape-only,postal code,,AI-,"GeoNames' regex cell for Anguilla is Azerbaijan's (`^(?:AZ)*(\d{4})$`) against the mask `AI-####`, so it is not used. `AI-` is a display prefix and is exposed as `countryPrefix`; only the four-digit shape is encoded, because Anguilla's single assigned code could not be verified against the operator. This is the one `countryPrefix` in the dataset that libaddressinput's `postprefix` column does not document: it is a hand-adjudicated reading of GeoNames' own mask, which writes `AI-` in front of the digits.",
Antarctica,AQ,none,[],,postal code,,,,
Antigua and Barbuda,AG,none,[],,postal code,false,,,
Argentina,AR,national,"[{""mask"":""@####@@@"",""regex"":""^[A-Za-z]\\d{4}[A-Za-z]{3}$"",""example"":""A1234BCD""},{""mask"":""####"",""regex"":""^\\d{4}$"",""example"":""1234""}]",shape-only,postal code,,,"The Argentine CPA is a province letter, four digits and three letters. Correo Argentino does not publish the province-letter set in a form we could verify, so no letter is excluded here. The legacy four-digit code is still the form most Argentines write and is accepted as a second pattern: GeoNames' mask records only the CPA, while its own regex for the same row (`^[A-Z]?\d{4}[A-Z]{0,3}$`) admits the bare four digits.",https://www.correoargentino.com.ar/
Armenia,AM,national,"[{""mask"":""####"",""regex"":""^\\d{4}$"",""example"":""1234""},{""mask"":""37####"",""regex"":""^37\\d{4}$"",""example"":""371234""}]",shape-only,postal code,,,"Armenia's four-digit postal code could not be confirmed against a HayPost publication, so the four-digit form that other address metadata records is shipped first and the legacy six-digit Soviet form beginning 37, which is what GeoNames records, is accepted as a second pattern.",https://www.haypost.am/
Aruba,AW,none,[],,postal code,,,,
Australia,AU,national,"[{""mask"":""####"",""regex"":""^\\d{4}$"",""example"":""1234""}]",shape-only,postal code,true,,,
Austria,AT,national,"[{""mask"":""####"",""regex"":""^\\d{4}$"",""example"":""1234""}]",shape-only,postal code,true,,,
Azerbaijan,AZ,national,"[{""mask"":""####"",""regex"":""^\\d{4}$"",""example"":""1234""}]",shape-only,postal code,,AZ ,GeoNames writes the international display prefix `AZ` inside the mask. The code itself is four digits; the prefix is exposed as `countryPrefix` and accepted (but not required) by /validate.,
Bahamas,BS,none,[],,postal code,,,,
Bahrain,BH,national,"[{""mask"":""####"",""regex"":""^\\d{4}$"",""example"":""1234""},{""mask"":""###"",""regex"":""^\\d{3}$"",""example"":""123""}]",shape-only,postal code,,,"Bahrain writes the block number as three or four digits and GeoNames records both forms. Bahrain Post's site is reachable only from a browser, so the assigned block ranges are not encoded.",https://www.bahrainpost.gov.bh/
Bangladesh,BD,national,"[{""mask"":""####"",""regex"":""^\\d{4}$"",""example"":""1234""}]",shape-only,postal code,,,,
Barbados,BB,national,"[{""mask"":""BB#####"",""regex"":""^[Bb]{2}\\d{5}$"",""example"":""BB12345""}]",shape-only,postal code,,,,
Belarus,BY,national,"[{""mask"":""######"",""regex"":""^\\d{6}$"",""example"":""123456""}]",shape-only,postal code,,,,
Belgium,BE,national,"[{""mask"":""####"",""regex"":""^\\d{4}$"",""example"":""1234""}]",shape-only,postal code,true,,,
Belize,BZ,none,[],,postal code,,,,
Benin,BJ,none,[],,postal code,,,,
Bermuda,BM,national,"[{""mask"":""@@ ##"",""regex"":""^[A-Za-z]{2}[ -]?\\d{2}$"",""example"":""AB 12""}]",shape-only,postal code,,,"GeoNames' own regex for Bermuda (`^([A-Z]{2}\d{2})$`) rejects the space its own mask writes, so the mask is kept and the space is treated as an optional separator. The alphanumeric second group that other address metadata records — the form of PO-box codes such as `HM GX` — is not accepted.",
Bhutan,BT,national,"[{""mask"":""#####"",""regex"":""^\\d{5}$"",""example"":""12345""}]",shape-only,postal code,,,"GeoNames records no format for Bhutan; Bhutan Post's own postcode page publishes five-digit codes. Only the digit count is encoded, not the assigned ranges.",https://bhutanpost.bt/postcode/
Bolivia,BO,none,[],,postal code,,,,
Bosnia and Herzegovina,BA,national,"[{""mask"":""#####"",""regex"":""^\\d{5}$"",""example"":""12345""}]",shape-only,postal code,,,,
Botswana,BW,none,[],,postal code,,,,
Bouvet Island,BV,none,[],,postal code,,,,
Brazil,BR,national,"[{""mask"":""#####-###"",""regex"":""^\\d{5}[ -]?\\d{3}$"",""example"":""12345-678""}]",shape-only,postal code,true,,,
British Indian Ocean Territory,IO,national,"[{""mask"":""BBND 1ZZ"",""regex"":""^[Bb]{2}[Nn][Dd][ -]?1[Zz]{2}$"",""example"":""BBND 1ZZ""}]",shape-only,postal code,true,,,
British Virgin Islands,VG,national,"[{""mask"":""VG####"",""regex"":""^[Vv][Gg]\\d{4}$"",""example"":""VG1234""}]",shape-only,postal code,false,,"GeoNames records no format for the British Virgin Islands, while the cross-check's address format carries a postal code field. No BVI Post publication of the format could be retrieved, so only the `VG` and four digits that other address metadata records is encoded.",https://www.vgpost.vg/
Brunei,BN,national,"[{""mask"":""@@####"",""regex"":""^[A-Za-z]{2}\\d{4}$"",""example"":""AB1234""}]",shape-only,postal code,,,,
Bulgaria,BG,national,"[{""mask"":""####"",""regex"":""^\\d{4}$"",""example"":""1234""}]",shape-only,postal code,,,,
Burkina Faso,BF,none,[],,postal code,,,,
Burundi,BI,none,[],,postal code,,,,
Cabo Verde,CV,national,"[{""mask"":""####"",""regex"":""^\\d{4}$"",""example"":""1234""}]",shape-only,postal code,,,,
Cambodia,KH,national,"[{""mask"":""#####"",""regex"":""^\\d{5}$"",""example"":""12345""}]",shape-only,postal code,,,,
    …
Honduras,HN,national,"[{""mask"":""#####"",""regex"":""^\\d{5}$"",""example"":""12345""}]",shape-only,postal code,false,,GeoNames' mask for Honduras is five digits while its own regex for the same row demands six. The five-digit mask is kept.,
Hong Kong,HK,none,[],,postal code,false,,"GeoNames gives Hong Kong mainland China's six-digit format. Hong Kong has no postal code system: the cross-check's address format for Hong Kong contains no postal code field, and no Hongkong Post publication of one could be retrieved.",https://www.hongkongpost.hk/en/about_us/index.html

GET /api/postal-code-formats/lookup Look up one country's postal code format, regex and display prefix Single-record lookup

Accepts an ISO 3166-1 alpha-2 or alpha-3 code, case-insensitively. Countries with no postal code system return a real record with postalCodeSystem: "none" — only unassigned codes are 404s, including GeoNames' withdrawn CS and the user-assigned XK.

Live requestRuns against the public API

No key required

GET/api/postal-code-formats/lookup?country=NL

Request parameters

countryrequired

ISO 3166-1 alpha-2 or alpha-3 code, case-insensitive (NL or NLD).

separatorsdefault optional

Advanced response options4 options

fields

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

exclude

Return all fields except these (comma-separated).

prettydefault false

Pretty-print the JSON response.

unwrapdefault false

Drop the envelope: return the raw array/object without data/meta wrapper.

Response

Example parameters are ready. Send the request to inspect the live response.

Route reference

Code, request parameters, response fields and verified examples 6 params · 10 fields · 4 examples

Code samples Ready-to-copy requests in 4 languages

curl JavaScript Python PHP

curl "https://randomapi.dev/api/postal-code-formats/lookup?country=NL"

const res = await fetch("https://randomapi.dev/api/postal-code-formats/lookup?country=NL");
const { data, meta } = await res.json();

import requests

data = requests.get("https://randomapi.dev/api/postal-code-formats/lookup?country=NL").json()["data"]

$json = json_decode(file_get_contents(
  "https://randomapi.dev/api/postal-code-formats/lookup?country=NL"
), true);
$data = $json["data"];

Parameters Route-specific request inputs 2

Parameter	Type	Default & allowed	Description
`country` required	string	allowed: 2 – 3 example: NL	ISO 3166-1 alpha-2 or alpha-3 code, case-insensitive (NL or NLD).
`separators`	enum	default: optional allowed: optional \| exact example: exact	Which derived regex each pattern exposes: `optional` accepts one optional separator character wherever the mask writes a space or hyphen (so `1012AB` and `1012 AB` both pass); `exact` requires the mask's separators verbatim. Transforms the output, never filters it.

country string required

ISO 3166-1 alpha-2 or alpha-3 code, case-insensitive (NL or NLD).

allowed: 2 – 3

example: country=NL

separators enum

default: optional

allowed: optional | exact

example: separators=exact

Universal parameters Shared response and formatting options 4

Parameter	Type	Default & allowed	Description
`fields`	list	example: country,countryCode	Return only these fields (comma-separated). Mutually exclusive with 'exclude'.
`exclude`	list	example: officialSource	Return all fields except these (comma-separated).
`pretty`	boolean	default: false example: true	Pretty-print the JSON response.
`unwrap`	boolean	default: false example: true	Drop the envelope: return the raw array/object without data/meta wrapper.

fields list

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

example: fields=country,countryCode

exclude list

Return all fields except these (comma-separated).

example: exclude=officialSource

pretty boolean

Pretty-print the JSON response.

default: false

example: pretty=true

unwrap boolean

Drop the envelope: return the raw array/object without data/meta wrapper.

default: false

example: unwrap=true

Response schema Fields returned in each record 10

Field	Type	Description	Example
`country`	string	English ISO 3166-1 name, joined from the country dataset at load time.	Netherlands
`countryCode`	string	ISO 3166-1 alpha-2 code (uppercase).	NL
`postalCodeSystem`	string	`national` (a system covering the territory, with at least one verified format), `limited` (codes cover part of the territory, or no single expressible format is published), `none` (no postal code system — an address form should not ask for one) or `unverified` (the two upstreams disagree and we could not settle it against the operator).	national
`patterns`	object[]	Every accepted written form, most common first. Each entry has `mask` (the written form in this API's mask alphabet), `regex` (an anchored, capture-free ECMAScript source in the requested `separators` mode — case-insensitive by construction, so it needs no `/i` flag and works unchanged in an HTML `pattern=` attribute) and `example` (a shape-conforming illustration of the written form, not necessarily a code the operator has assigned). Empty unless `postalCodeSystem` is `national` or `limited`.	[{"mask":"#### @@","regex":"^[1-9]\\d{3}[ -]?(?:[A-RT-Za-rt-z][A-Za-z]\|[Ss][BCE-RT-Zbce-rt-z])$","example":"1012 AB"}]
`precision` nullable	string	`national-rule` when every pattern encodes the operator's published rule (letter sets, digit ranges, fixed prefixes); `shape-only` when at least one pattern constrains only the count and kind of characters, so it accepts shape-correct codes the operator never assigns; `null` when there are no patterns.	national-rule
`postalCodeName`	string	What the country's own address metadata calls the field: `postal code`, `zip code`, `eircode` or `PIN code`. Mapped 1:1 from libaddressinput's `zip_name_type`, with the key absent meaning `postal code`. Not a claim about the local-language term — `CEP`, `PLZ`, `CAP` and 郵便番号 are deliberately out of scope.	postal code
`requiredInAddress` nullable	boolean	Whether a postal code is required in a complete address: `true` where libaddressinput's `require` contains `Z`, `false` where `require` is present without it, and `null` where `require` is absent entirely — the source records no requirement either way. Rows where it is `null` match neither `required=true` nor `required=false`.	true
`countryPrefix` nullable	string	The optional international display prefix written before the code (`L-`, `LT-`, `CH-`, `AZ `). The prefix is not part of the code; `/validate` accepts it with or without its trailing separator and strips it. `null` where none is documented.	null
`note` nullable	string	Honest caveats: partial coverage, legacy forms, letters the operator excludes, why this row departs from the primary source, what is deliberately excluded. Every factual claim here is covered by `officialSource` or by a defect visible in the pinned snapshot itself. `null` where there is nothing to disclose.	PostNL does not assign the letter combinations SA, SD or SS, and the numeric part never starts with 0. GeoNames' mask encodes neither restriction.
`officialSource` nullable	string	HTTPS URL of the national operator or standards publication this row was verified against — a citation for a human, never fetched at request time. Non-null for every `national-rule` row. `null` where the row is taken verbatim from the agreeing upstreams, or where a divergence is proven by a defect inside the pinned snapshots and needs no external fact.	https://www.postnl.nl/en/find-a-postcode/

country string

English ISO 3166-1 name, joined from the country dataset at load time.

example: Netherlands

countryCode string

ISO 3166-1 alpha-2 code (uppercase).

example: NL

postalCodeSystem string

example: national

patterns object[]

example: [{"mask":"#### @@","regex":"^[1-9]\\d{3}[ -]?(?:[A-RT-Za-rt-z][A-Za-z]|[Ss][BCE-RT-Zbce-rt-z])$","example":"1012 AB"}]

precision string nullable

example: national-rule

postalCodeName string

example: postal code

requiredInAddress boolean nullable

example: true

countryPrefix string nullable

example: null

note string nullable

example: PostNL does not assign the letter combinations SA, SD or SS, and the numeric part never starts with 0. GeoNames' mask encodes neither restriction.

officialSource string nullable

example: https://www.postnl.nl/en/find-a-postcode/

Documented examples

Build-generated requests and complete responses 4

Dutch postal code format /api/postal-code-formats/lookup?country=NL

GET /api/postal-code-formats/lookup?country=NL

{
  "data": {
    "country": "Netherlands",
    "countryCode": "NL",
    "postalCodeSystem": "national",
    "patterns": [
      {
        "mask": "#### @@",
        "regex": "^[1-9]\\d{3}[ -]?(?:[A-RT-Za-rt-z][A-Za-z]|[Ss][BCE-RT-Zbce-rt-z])$",
        "example": "1012 AB"
      }
    ],
    "precision": "national-rule",
    "postalCodeName": "postal code",
    "requiredInAddress": true,
    "countryPrefix": null,
    "note": "PostNL does not assign the letter combinations SA, SD or SS, and the numeric part never starts with 0. GeoNames' mask encodes neither restriction.",
    "officialSource": "https://www.postnl.nl/en/find-a-postcode/"
  },
  "meta": {
    "endpoint": "postal-code-formats",
    "route": "/lookup",
    "params": {
      "country": "NL",
      "separators": "optional"
    },
    "generatedAt": "2026-07-30T15:14:08.000Z"
  }
}

All seven UK forms, by alpha-3 /api/postal-code-formats/lookup?country=GBR

GET /api/postal-code-formats/lookup?country=GBR

{
  "data": {
    "country": "United Kingdom",
    "countryCode": "GB",
    "postalCodeSystem": "national",
    "patterns": [
      {
        "mask": "@# #@@",
        "regex": "^[A-PR-UWYZa-pr-uwyz]\\d[ -]?\\d[ABD-HJLNP-UW-Zabd-hjlnp-uw-z]{2}$",
        "example": "M1 1AA"
      },
      {
        "mask": "@## #@@",
        "regex": "^[A-PR-UWYZa-pr-uwyz]\\d{2}[ -]?\\d[ABD-HJLNP-UW-Zabd-hjlnp-uw-z]{2}$",
        "example": "M60 1NW"
      },
      {
        "mask": "@@# #@@",
        "regex": "^[A-PR-UWYZa-pr-uwyz][A-HJ-Ya-hj-y]\\d[ -]?\\d[ABD-HJLNP-UW-Zabd-hjlnp-uw-z]{2}$",
        "example": "CR2 6XH"
      },
      {
        "mask": "@@## #@@",
        "regex": "^[A-PR-UWYZa-pr-uwyz][A-HJ-Ya-hj-y]\\d{2}[ -]?\\d[ABD-HJLNP-UW-Zabd-hjlnp-uw-z]{2}$",
        "example": "DN55 1PT"
      },
      {
        "mask": "@#@ #@@",
        "regex": "^[A-PR-UWYZa-pr-uwyz]\\d[A-HJKPS-Xa-hjkps-x][ -]?\\d[ABD-HJLNP-UW-Zabd-hjlnp-uw-z]{2}$",
        "example": "W1P 1BB"
      },
      {
        "mask": "@@#@ #@@",
        "regex": "^[A-PR-UWYZa-pr-uwyz][A-HJ-Ya-hj-y]\\d[A-Za-z][ -]?\\d[ABD-HJLNP-UW-Zabd-hjlnp-uw-z]{2}$",
        "example": "EC1A 1BB"
      },
      {
        "mask": "GIR 0AA",
        "regex": "^[Gg][Ii][Rr][ -]?0[Aa]{2}$",
        "example": "GIR 0AA"
    …
    "generatedAt": "2026-07-30T15:14:08.000Z"
  }
}

A country with no postal codes /api/postal-code-formats/lookup?country=JM

GET /api/postal-code-formats/lookup?country=JM

{
  "data": {
    "country": "Jamaica",
    "countryCode": "JM",
    "postalCodeSystem": "none",
    "patterns": [],
    "precision": null,
    "postalCodeName": "postal code",
    "requiredInAddress": false,
    "countryPrefix": null,
    "note": null,
    "officialSource": null
  },
  "meta": {
    "endpoint": "postal-code-formats",
    "route": "/lookup",
    "params": {
      "country": "JM",
      "separators": "optional"
    },
    "generatedAt": "2026-07-30T15:14:08.000Z"
  }
}

Strict separators for Portugal /api/postal-code-formats/lookup?country=PT&separators=exact

GET /api/postal-code-formats/lookup?country=PT&separators=exact

{
  "data": {
    "country": "Portugal",
    "countryCode": "PT",
    "postalCodeSystem": "national",
    "patterns": [
      {
        "mask": "####-###",
        "regex": "^\\d{4}-\\d{3}$",
        "example": "1234-567"
      }
    ],
    "precision": "shape-only",
    "postalCodeName": "postal code",
    "requiredInAddress": true,
    "countryPrefix": null,
    "note": null,
    "officialSource": null
  },
  "meta": {
    "endpoint": "postal-code-formats",
    "route": "/lookup",
    "params": {
      "country": "PT",
      "separators": "exact"
    },
    "generatedAt": "2026-07-30T15:14:08.000Z"
  }
}

GET /api/postal-code-formats/validate Normalise a postal code and check its shape against the country's format Computed answer

Shape checking only: a true verdict means the code matches a written form the country uses, never that it has been assigned or is deliverable. valid is null — with a reason — for the countries where no format could be verified.

Live requestRuns against the public API

No key required

GET/api/postal-code-formats/validate?country=NL&code=1012ab

Request parameters

countryrequired

ISO 3166-1 alpha-2 or alpha-3 code, case-insensitive (NL or NLD).

coderequired

The postal code to check, exactly as your user typed it — whitespace is preserved so `input` can echo it back. Up to 16 characters.

separatorsdefault optional

Advanced response options4 options

fields

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

exclude

Return all fields except these (comma-separated).

prettydefault false

Pretty-print the JSON response.

unwrapdefault false

Drop the envelope: return the raw array/object without data/meta wrapper.

Response

Example parameters are ready. Send the request to inspect the live response.

Route reference

Code, request parameters, response fields and verified examples 7 params · 12 fields · 5 examples

Code samples Ready-to-copy requests in 4 languages

curl JavaScript Python PHP

curl "https://randomapi.dev/api/postal-code-formats/validate?country=NL&code=1012ab"

const res = await fetch("https://randomapi.dev/api/postal-code-formats/validate?country=NL&code=1012ab");
const { data, meta } = await res.json();

import requests

data = requests.get("https://randomapi.dev/api/postal-code-formats/validate?country=NL&code=1012ab").json()["data"]

$json = json_decode(file_get_contents(
  "https://randomapi.dev/api/postal-code-formats/validate?country=NL&code=1012ab"
), true);
$data = $json["data"];

Parameters Route-specific request inputs 3

Parameter	Type	Default & allowed	Description
`country` required	string	allowed: 2 – 3 example: NL	ISO 3166-1 alpha-2 or alpha-3 code, case-insensitive (NL or NLD).
`code` required	string	allowed: 1 – 16 example: 1012ab	The postal code to check, exactly as your user typed it — whitespace is preserved so `input` can echo it back. Up to 16 characters.
`separators`	enum	default: optional allowed: optional \| exact example: exact	Which derived regex each pattern exposes: `optional` accepts one optional separator character wherever the mask writes a space or hyphen (so `1012AB` and `1012 AB` both pass); `exact` requires the mask's separators verbatim. Transforms the output, never filters it.

country string required

ISO 3166-1 alpha-2 or alpha-3 code, case-insensitive (NL or NLD).

allowed: 2 – 3

example: country=NL

code string required

The postal code to check, exactly as your user typed it — whitespace is preserved so `input` can echo it back. Up to 16 characters.

allowed: 1 – 16

example: code=1012ab

separators enum

default: optional

allowed: optional | exact

example: separators=exact

Universal parameters Shared response and formatting options 4

Parameter	Type	Default & allowed	Description
`fields`	list	example: country,input	Return only these fields (comma-separated). Mutually exclusive with 'exclude'.
`exclude`	list	example: precision	Return all fields except these (comma-separated).
`pretty`	boolean	default: false example: true	Pretty-print the JSON response.
`unwrap`	boolean	default: false example: true	Drop the envelope: return the raw array/object without data/meta wrapper.

fields list

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

example: fields=country,input

exclude list

Return all fields except these (comma-separated).

example: exclude=precision

pretty boolean

Pretty-print the JSON response.

default: false

example: pretty=true

unwrap boolean

Drop the envelope: return the raw array/object without data/meta wrapper.

default: false

example: unwrap=true

Response schema Fields returned in each record 12

Field	Type	Description	Example
`country`	string	The resolved ISO 3166-1 alpha-2 code.	NL
`input`	string	The `code` value exactly as supplied.	1012ab
`normalized`	string	The code after the documented normalisation pipeline (trim, collapse inner whitespace, uppercase, strip the country prefix). Always populated, even when invalid — input that failed the ASCII character check is echoed as typed rather than uppercased, so the offending character stays visible.	1012 AB
`prefixStripped`	boolean	Whether the country's documented `countryPrefix` was removed during normalisation.	false
`postalCodeSystem`	string	The country's classification — same values as the list route.	national
`checkable`	boolean	Whether there is anything to check against: `true` when the country has at least one pattern, or when it has no postal code system at all (in which case nothing is a valid code).	true
`valid` nullable	boolean	The shape verdict: `true` only when `checkable` and `reasons` is empty, and `null` exactly when `checkable` is `false` — we do not report a verdict we cannot support. Never a claim that the code is assigned, in service or deliverable.	true
`reasons`	string[]	Stable reason codes in the documented order. Empty exactly when `valid` is `true`; non-empty when `valid` is `null`.	[]
`matchedMask` nullable	string	The mask of the first pattern that matched; `null` when nothing matched.	#### @@
`matchedRegex` nullable	string	That pattern's regex in the requested `separators` mode; `null` when nothing matched.	^[1-9]\d{3}[ -]?(?:[A-RT-Za-rt-z][A-Za-z]\|[Ss][BCE-RT-Zbce-rt-z])$
`expectedMasks`	string[]	Every mask this country accepts, so a failing caller can be told the shape. Empty when there are none.	["#### @@"]
`precision` nullable	string	The row's `precision`, so you know what a `true` here is worth.	national-rule

country string

The resolved ISO 3166-1 alpha-2 code.

example: NL

input string

The `code` value exactly as supplied.

example: 1012ab

normalized string

The code after the documented normalisation pipeline (trim, collapse inner whitespace, uppercase, strip the country prefix). Always populated, even when invalid — input that failed the ASCII character check is echoed as typed rather than uppercased, so the offending character stays visible.

example: 1012 AB

prefixStripped boolean

Whether the country's documented `countryPrefix` was removed during normalisation.

example: false

postalCodeSystem string

The country's classification — same values as the list route.

example: national

checkable boolean

Whether there is anything to check against: `true` when the country has at least one pattern, or when it has no postal code system at all (in which case nothing is a valid code).

example: true

valid boolean nullable

The shape verdict: `true` only when `checkable` and `reasons` is empty, and `null` exactly when `checkable` is `false` — we do not report a verdict we cannot support. Never a claim that the code is assigned, in service or deliverable.

example: true

reasons string[]

Stable reason codes in the documented order. Empty exactly when `valid` is `true`; non-empty when `valid` is `null`.

example: []

matchedMask string nullable

The mask of the first pattern that matched; `null` when nothing matched.

example: #### @@

matchedRegex string nullable

That pattern's regex in the requested `separators` mode; `null` when nothing matched.

example: ^[1-9]\d{3}[ -]?(?:[A-RT-Za-rt-z][A-Za-z]|[Ss][BCE-RT-Zbce-rt-z])$

expectedMasks string[]

Every mask this country accepts, so a failing caller can be told the shape. Empty when there are none.

example: ["#### @@"]

precision string nullable

The row's `precision`, so you know what a `true` here is worth.

example: national-rule

Documented examples

Build-generated requests and complete responses 5

Normalise a lowercase Dutch code /api/postal-code-formats/validate?country=NL&code=1012ab

GET /api/postal-code-formats/validate?country=NL&code=1012ab

{
  "data": {
    "country": "NL",
    "input": "1012ab",
    "normalized": "1012AB",
    "prefixStripped": false,
    "postalCodeSystem": "national",
    "checkable": true,
    "valid": true,
    "reasons": [],
    "matchedMask": "#### @@",
    "matchedRegex": "^[1-9]\\d{3}[ -]?(?:[A-RT-Za-rt-z][A-Za-z]|[Ss][BCE-RT-Zbce-rt-z])$",
    "expectedMasks": [
      "#### @@"
    ],
    "precision": "national-rule"
  },
  "meta": {
    "endpoint": "postal-code-formats",
    "route": "/validate",
    "params": {
      "country": "NL",
      "code": "1012ab",
      "separators": "optional"
    },
    "generatedAt": "2026-07-30T15:14:08.000Z"
  }
}

A letter Canada Post never assigns /api/postal-code-formats/validate?country=CA&code=D1A%201A1

GET /api/postal-code-formats/validate?country=CA&code=D1A%201A1

{
  "data": {
    "country": "CA",
    "input": "D1A 1A1",
    "normalized": "D1A 1A1",
    "prefixStripped": false,
    "postalCodeSystem": "national",
    "checkable": true,
    "valid": false,
    "reasons": [
      "NO_PATTERN_MATCHED"
    ],
    "matchedMask": null,
    "matchedRegex": null,
    "expectedMasks": [
      "@#@ #@#"
    ],
    "precision": "national-rule"
  },
  "meta": {
    "endpoint": "postal-code-formats",
    "route": "/validate",
    "params": {
      "country": "CA",
      "code": "D1A 1A1",
      "separators": "optional"
    },
    "generatedAt": "2026-07-30T15:14:08.000Z"
  }
}

UK postcode without the space /api/postal-code-formats/validate?country=GB&code=SW1A1AA

GET /api/postal-code-formats/validate?country=GB&code=SW1A1AA

{
  "data": {
    "country": "GB",
    "input": "SW1A1AA",
    "normalized": "SW1A1AA",
    "prefixStripped": false,
    "postalCodeSystem": "national",
    "checkable": true,
    "valid": true,
    "reasons": [],
    "matchedMask": "@@#@ #@@",
    "matchedRegex": "^[A-PR-UWYZa-pr-uwyz][A-HJ-Ya-hj-y]\\d[A-Za-z][ -]?\\d[ABD-HJLNP-UW-Zabd-hjlnp-uw-z]{2}$",
    "expectedMasks": [
      "@# #@@",
      "@## #@@",
      "@@# #@@",
      "@@## #@@",
      "@#@ #@@",
      "@@#@ #@@",
      "GIR 0AA"
    ],
    "precision": "national-rule"
  },
  "meta": {
    "endpoint": "postal-code-formats",
    "route": "/validate",
    "params": {
      "country": "GB",
      "code": "SW1A1AA",
      "separators": "optional"
    },
    "generatedAt": "2026-07-30T15:14:08.000Z"
  }
}

The same code with strict separators /api/postal-code-formats/validate?country=GB&code=SW1A1AA&separators=exact

GET /api/postal-code-formats/validate?country=GB&code=SW1A1AA&separators=exact

{
  "data": {
    "country": "GB",
    "input": "SW1A1AA",
    "normalized": "SW1A1AA",
    "prefixStripped": false,
    "postalCodeSystem": "national",
    "checkable": true,
    "valid": false,
    "reasons": [
      "SEPARATORS_REQUIRED"
    ],
    "matchedMask": null,
    "matchedRegex": null,
    "expectedMasks": [
      "@# #@@",
      "@## #@@",
      "@@# #@@",
      "@@## #@@",
      "@#@ #@@",
      "@@#@ #@@",
      "GIR 0AA"
    ],
    "precision": "national-rule"
  },
  "meta": {
    "endpoint": "postal-code-formats",
    "route": "/validate",
    "params": {
      "country": "GB",
      "code": "SW1A1AA",
      "separators": "exact"
    },
    "generatedAt": "2026-07-30T15:14:08.000Z"
  }
}

A country that has no postal codes /api/postal-code-formats/validate?country=JM&code=12345

GET /api/postal-code-formats/validate?country=JM&code=12345

{
  "data": {
    "country": "JM",
    "input": "12345",
    "normalized": "12345",
    "prefixStripped": false,
    "postalCodeSystem": "none",
    "checkable": true,
    "valid": false,
    "reasons": [
      "COUNTRY_HAS_NO_POSTAL_CODES"
    ],
    "matchedMask": null,
    "matchedRegex": null,
    "expectedMasks": [],
    "precision": null
  },
  "meta": {
    "endpoint": "postal-code-formats",
    "route": "/validate",
    "params": {
      "country": "JM",
      "code": "12345",
      "separators": "optional"
    },
    "generatedAt": "2026-07-30T15:14:08.000Z"
  }
}

About this API

Coverage, behavior and common use cases

Coverage & behavior

A postal code shape reference for all 249 officially assigned ISO 3166-1 entries: the written forms each country accepts, a ready-to-paste anchored regex for every one of them, and a /validate route that normalises a code and tells you whether it matches. 178 entries carry at least one pattern; 68 have no postal code system at all, which is a fact your address form needs as much as any format.

It checks shape, never existence. Nothing here says a code has been assigned, is in service, or is deliverable — there is no code-to-place lookup and no geocoding. Even a national-rule regex encodes the operator's published rule, so it will happily accept unassigned codes inside a valid range.

Why the regexes are ours

The masks are anchored on GeoNames' Postal Code Format column, pinned by SHA-256 at the 2026-07-30 snapshot. The neighbouring Postal Code Regex column is deliberately not redistributed: 31 of its 178 rows have a mask their own regex cell rejects, and several rows carry another country's data outright — Anguilla's regex is Azerbaijan's, Chad's row is Turks and Caicos', Samoa's is American Samoa's, American Samoa's regex cell is the bare string 96799, and Guernsey, the Isle of Man and Jersey all carry the United Kingdom's mask and regex. Every regex this endpoint publishes is derived from a hand-adjudicated mask instead, by one deterministic function.

Masks use # for a digit, @ for a letter, * for either, literal digits and letters for fixed parts (969##, GIR 0AA), and space or hyphen for a separator. Derived regexes are anchored, contain no capture groups, and are case-insensitive by construction (GIR becomes [Gg][Ii][Rr]) — so they need no /i flag and drop straight into new RegExp(), Python's re or an HTML pattern= attribute.

How honest each row is

precision says so per row: 23 rows are national-rule, where every pattern encodes the operator's published rule — the United Kingdom's PAF letter exclusions, the letters Canadian postal codes never use (D, F, I, O, Q, U), PostNL's unassigned SA/SD/SS and its non-zero first digit, Eircode's 3 + 4 split without the letter O, and the fixed French, Monégasque and Australian-territory prefixes. 155 rows are shape-only: they constrain the count and kind of characters and nothing more, so a five-digit mask accepts 00000. Those rows are labelled, not hidden, and /validate echoes precision so you know what a true is worth. Each row's note names the document its restrictions come from — and says so plainly when the evidence is a defect inside the pinned snapshot rather than an operator publication, as it is for Canada's letter classes.

4 rows are limited (codes cover part of the territory, or the operator publishes nothing we can express as a mask) and 2 are unverified — Guinea (GN) and Panama (PA), where one upstream records a postal code and the other records none, and no reachable operator publication settles it either way. Both states answer valid: null rather than guess.

`/validate` normalisation, in order

input is the code value verbatim (up to 16 characters; longer is a 400).
Leading and trailing ASCII whitespace is trimmed and internal runs of space or tab collapse to one space.
Any character outside [A-Za-z0-9 -] yields INVALID_CHARACTERS. The check runs on the raw ASCII, before uppercasing, because toUpperCase() would otherwise expand ı, ſ, ß and the ﬁ ligature into I, S, SS and FI and smuggle them past it. Nothing is transliterated or NFKC-folded, so full-width １０１２ stays visibly invalid — and a mistyped letter O in an Eircode is not read as a zero, whatever Eircode advises consumer systems to do.
The value is uppercased. It is ASCII by then, so this can never introduce a character the check did not see; input the check rejected is left exactly as typed, so you can see what was wrong with it.
A documented countryPrefix is stripped (with or without its trailing separator) and prefixStripped says so. Only this country's prefix, never a foreign one.
normalized is the result, always populated — even when invalid.
Patterns are tried in declared order; the first match wins.

Failures come back as stable reason codes, checked in this order: COUNTRY_HAS_NO_POSTAL_CODES, NO_VERIFIED_FORMAT, EMPTY_AFTER_NORMALIZATION, INVALID_CHARACTERS, WRONG_LENGTH (no pattern is that long, even with the separators left out), SEPARATORS_REQUIRED (only under separators=exact, when optional would have matched) and NO_PATTERN_MATCHED as the catch-all. reasons is empty exactly when valid is true; when valid is null it is non-empty.

Deliberate limits

No code-to-place or place-to-code lookup. The full GeoNames postal dump is over 1.8 million rows and is permanently out of budget for a bundled dataset.
No local-language field names. postalCodeName is the four-valued zip_name_type term and nothing more.
Sub-national scope is recorded, not modelled. Åland sits inside Finland's plan and Western Sahara inside Morocco's; note says so, and that is all.
Withdrawn and user-assigned codes are absent. GeoNames' CS (Serbia and Montenegro, withdrawn 2006) and the user-assigned XK both return 404, consistent with /api/countries.
Uninhabited and quasi-territories get real records, not 404s. ?country=AQ answers with postalCodeSystem: "none"; Heard Island and McDonald Islands carry an Australian postcode in both upstreams despite having no postal service, and the row says so.
British Forces Post Office codes are not accepted for the United Kingdom: they are not geographic Royal Mail postcodes, and the row's note states the exclusion.

Nothing is fetched while your request is served. requiredInAddress is true for 74 entries, false for 21, and null for 154 where the cross-check records no requirement either way.

Use it for

Drop a per-country regex into a checkout form's postal code field without hand-maintaining the list
Hide the postal code input entirely for the countries that have no postal code system
Normalise user-typed codes (case, spacing, LT-/L- prefixes) before storing them
Label a form's postal code field with the term the country actually uses — zip code, Eircode or PIN code
Decide whether your validation can be strict for a country or has to stay shape-only

Frequently asked questions

Practical answers about this endpoint 6

How do I get a postal code regex for a country?

/api/postal-code-formats/lookup?country=NL returns every accepted mask with a ready-to-paste anchored regex. The default separators=optional accepts 1012AB as well as 1012 AB; separators=exact requires the space.

Can this API tell me whether a postal code exists?

No. It checks shape only — nothing about assignment, coverage, routing or deliverability, and there is no code-to-place lookup. A valid: true means the code matches the country's written form, not that anyone lives there.

Which countries do not use postal codes?

?system=none returns them — 68 entries today. Both upstreams agree on 60 of those; the remaining rows were adjudicated one by one, because telling a developer that Chad uses TKCA 1ZZ would be a fabricated fact.

Why don't you use the GeoNames postal code regex?

Because 31 of its 178 rows have a mask that its own regex cell rejects, and several rows are cross-country copy-pastes: Anguilla's regex is Azerbaijan's, Chad's row carries Turks and Caicos' TKCA 1ZZ in both columns, Samoa's carries American Samoa's ZIP, American Samoa's regex cell is not a regex at all but the bare string 96799, and Guernsey, the Isle of Man and Jersey all carry the United Kingdom's. We ship hand-adjudicated masks and derive every regex ourselves.

What is the difference between precision national-rule and shape-only?

national-rule (23 rows) means every pattern encodes the operator's published rule — Canadian postal codes never using D, F, I, O, Q or U, for instance. shape-only (155 rows) means the pattern constrains only the count and kind of characters, so a five-digit mask will accept 00000. Filter with ?precision=national-rule when you need the strict ones.

Does the returned regex work in an HTML pattern attribute?

Yes. Every regex is anchored, free of capture groups and case-insensitive by construction — literal letters are emitted as [Aa]-style classes rather than relying on an /i flag — so the same string works in new RegExp(), in Python's re and in <input pattern=…>.

Useful next tools in the catalog

Fake Address API MOCK DATA

Locale-aware fake postal addresses — street, city, state, zip, country and coordinates that all agree, plus a one-line formatted form in the local layout.

International Address Format API REAL DATA

Which fields an address needs in each of 252 countries and territories, and the order they print on the envelope — plus a live envelope renderer.

ISO 3166 Countries API REAL DATA

All 249 ISO 3166-1 countries and territories with codes, regions, capitals, currencies, languages, calling codes, flags and label-safe land points.

Fake Form Submission API MOCK DATA

Generate coherent fake contact, signup, survey and application submissions with exact validation, attachment, spam and processing states.

Email Address Syntax Validator API (RFC 5322, RFC 5321, HTML) REAL DATA

Validate email syntax against RFC 5322, RFC 5321 transport limits or the HTML input profile — local/domain split and the exact rule that failed. No DNS, ever.

Check Digit Validator and Calculator API REAL DATA

Validate or compute check digits for Luhn, GTIN/EAN/UPC, ISBN, ISSN, IMEI, ISIN, LEI, VIN, NPI, ABA and ISO 7064 — one cited algorithm per scheme.

GET /api/postal-code-formats List every country's postal code format (or the countries that have none) Returns a list

Request parameters

Response

Route reference

Documented examples

GET /api/postal-code-formats/lookup Look up one country's postal code format, regex and display prefix Single-record lookup

Request parameters

Response

Route reference

Documented examples

GET /api/postal-code-formats/validate Normalise a postal code and check its shape against the country's format Computed answer

Request parameters

Response

Route reference

Documented examples

About this API

Coverage & behavior

Why the regexes are ours

How honest each row is

/validate normalisation, in order

Deliberate limits

Use it for

Frequently asked questions

Related APIs

`/validate` normalisation, in order