postcode-format-validator

A lightweight, zero-dependency JavaScript library to validate postcodes / postal codes for 171 countries and territories based on their official format definitions. Returns detailed validation results including country name, matched format, error codes, and more.

Installation

npm install postcode-format-validator

Quick Start

const { validatePostcode, validatePostcodeDetailed } = require('postcode-format-validator');

// Simple boolean validation
validatePostcode('US', '10001');        // true
validatePostcode('US', '1000');         // false
validatePostcode('GB', 'SW1A 1AA');     // true
validatePostcode('CA', 'K1A 0B1');      // true
validatePostcode('DE', '10115');        // true
validatePostcode('JP', '100-0001');     // true
validatePostcode('IN', '110001');       // true
validatePostcode('NG', '100001');       // true
validatePostcode('SA', '12345');        // true

// Detailed validation result
const result = validatePostcodeDetailed('US', '10001');
// → {
//   valid: true,
//   postcode: '10001',
//   countryCode: 'US',
//   countryName: 'United States',
//   matchedFormat: '99999',
//   significantFigures: 5,
//   acceptedFormats: ['99999', '99999-9999'],
//   totalFormats: 2,
//   inputTrimmed: false,
//   error: null
// }

ES Module

import { validatePostcode, validatePostcodeDetailed, getCountryName } from 'postcode-format-validator';

validatePostcode('FR', '75001'); // true
getCountryName('FR');            // 'France'

API

validatePostcode(countryCode, postcode)

Simple boolean validation.

| Parameter | Type | Description | |---------------|----------|------------------------------------------------------------------| | countryCode | string | ISO 3166-1 alpha-2 country/region code (case-insensitive) | | postcode | string | The postcode / postal code to validate |

Returns: boolean — true if the postcode matches at least one accepted format for the country; false otherwise (including unknown countries).

validatePostcodeDetailed(countryCode, postcode)

Full validation with a rich result object.

| Parameter | Type | Description | |---------------|----------|------------------------------------------------------------------| | countryCode | string | ISO 3166-1 alpha-2 country/region code (case-insensitive) | | postcode | string | The postcode / postal code to validate |

Returns: ValidationResult object:

| Property | Type | Description | |----------------------|--------------------|--------------------------------------------------------| | valid | boolean | Whether the postcode is valid | | postcode | string | The postcode value tested (trimmed) | | countryCode | string | Normalised upper-case country code | | countryName | string \| null | Human-readable country name, or null if unknown | | matchedFormat | string \| null | The format pattern that matched (e.g. '99999') | | significantFigures | number \| null | Significant figures of the matched format | | acceptedFormats | string[] \| null | All accepted format strings for the country | | totalFormats | number | Number of accepted formats (0 if country unknown) | | inputTrimmed | boolean | Whether leading/trailing whitespace was trimmed | | error | string \| null | Error code (see below), or null if valid |

Error Codes

| Code | Meaning | |-------------------|--------------------------------------------------| | null | Postcode is valid | | INVALID_INPUT | Non-string argument(s) were passed | | UNKNOWN_COUNTRY | Country code is not in the database | | INVALID_FORMAT | Postcode doesn't match any accepted format |

Examples

// Valid postcode
validatePostcodeDetailed('GB', 'SW1A 1AA');
// → { valid: true, countryName: 'United Kingdom', matchedFormat: 'AA9A 9AA', error: null, ... }

// Invalid format
validatePostcodeDetailed('US', 'ABCDE');
// → { valid: false, countryName: 'United States', error: 'INVALID_FORMAT',
//     acceptedFormats: ['99999', '99999-9999'], ... }

// Unknown country
validatePostcodeDetailed('ZZ', '12345');
// → { valid: false, countryName: null, error: 'UNKNOWN_COUNTRY', ... }

// Trimmed input
validatePostcodeDetailed('DE', '  10115  ');
// → { valid: true, inputTrimmed: true, postcode: '10115', ... }

getFormats(countryCode)

| Parameter | Type | Description | |---------------|----------|------------------------------------------------------------------| | countryCode | string | ISO country/region code (case-insensitive) |

Returns: Array<{ format, regex, significantFigures }> or null if the country is not supported.

getCountryName(countryCode)

| Parameter | Type | Description | |---------------|----------|------------------------------------------------------------------| | countryCode | string | ISO country/region code (case-insensitive) |

Returns: string | null — Human-readable country name, or null if not found.

getCountryName('US'); // 'United States'
getCountryName('JP'); // 'Japan'
getCountryName('ZZ'); // null

getSupportedCountries()

Returns: string[] — Sorted array of all 171 supported ISO country/region codes.

COUNTRY_NAMES

A Record<string, string> mapping all supported country codes to their display names.

const { COUNTRY_NAMES } = require('postcode-format-validator');
console.log(COUNTRY_NAMES.GB); // 'United Kingdom'
console.log(COUNTRY_NAMES.NG); // 'Nigeria'

Format Legend

The format strings use the following convention:

| Character | Meaning | |-----------|-----------------| | 9 | Any digit (0-9) | | A | Any letter (A-Z, a-z) | | (space) | Literal space | | - | Literal hyphen |

Examples

| Country | Format(s) | Example | |---------|----------------------------------|----------------| | US | 99999, 99999-9999 | 10001, 10001-1234 | | GB | A9 9AA, A99 9AA, A9A 9AA, AA9 9AA, AA99 9AA, AA9A 9AA | SW1A 1AA | | CA | A9A 9A, A9A 9A9 | K1A 0B1 | | DE | 99999 | 10115 | | JP | 999-9999 | 100-0001 | | BR | 99999, 99999-999, 99999999 | 01310-100 | | NG | 999999 | 100001 | | SA | 99999, 99999-9999 | 12345 | | IR | 9999999999, 99999-99999 | 1234567890 | | MT | AAA 9999 | VLT 1117 |

Supported Countries (171)

AD, AF, AI, AL, AM, AR, AS, AT, AU, AX, AZ, BA, BB, BD, BE, BG, BH, BM, BN, BR, BT, BY, CA, CC, CH, CL, CN, CO, CR, CU, CV, CX, CY, CZ, DE, DK, DO, DZ, EC, EE, EG, ES, ET, FI, FK, FM, FO, FR, GB, GE, GF, GG, GI, GL, GN, GP, GR, GS, GT, GU, GW, HN, HR, HT, HU, IC, ID, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JO, JP, KE, KG, KH, KR, KV, KW, KY, KZ, LA, LB, LI, LK, LR, LS, LT, LU, LV, MA, MC, MD, ME, MG, MH, MK, MM, MN, MP, MQ, MS, MT, MV, MX, MY, NC, NE, NF, NG, NI, NL, NO, NP, NZ, OM, PA, PE, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, RE, RO, RS, RU, SA, SD, SE, SG, SH, SI, SK, SM, SN, SV, SZ, TC, TH, TJ, TM, TN, TR, TT, TW, TZ, UA, US, UY, UZ, VA, VE, VI, VN, WF, XY, YT, ZA, ZM

License

MIT