iso-3166-2.js

Lookup information about ISO-3166-2 subdivisions with flexible address validation for countries without postal codes.

Country code format

The country codes in the data are in the ISO 3166-1 alpha 2 format (US, SE ...), but there is a conversion table that makes possible to input alpha 3 codes (USA, SWE ...) to the subdivision and country functions.

https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2

https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3

Installation

npm install iso-3166-2

Examples

> iso3166.subdivision("SE-O");

{ type: 'County',
  name: 'Västra Götalands län',
  countryName: 'Sweden',
  countryCode: 'SE',
  regionCode: 'O',
  code: 'SE-O' }

> iso3166.subdivision("UN-1");
null

> iso3166.subdivision("SE", "O");

{ type: 'County',
  name: 'Västra Götalands län',
  countryName: 'Sweden',
  countryCode: 'SE',
  regionCode: 'O',
  code: 'SE-O' }

> iso3166.subdivision("USA", "Indiana");

{ type: 'state',
  name: 'Indiana',
  countryName: 'United States',
  countryCode: 'US',
  regionCode: 'IN',
  code: 'US-IN' }

> iso3166.country("Sweden");
{ name: 'Sweden',
  sub:
   { 'SE-O': { type: 'County', name: 'Västra Götalands län' },
     'SE-N': { type: 'County', name: 'Hallands län' },
     'SE-M': { type: 'County', name: 'Skåne län' },
     'SE-K': { type: 'County', name: 'Blekinge län' },
     'SE-I': { type: 'County', name: 'Gotlands län' },
     'SE-H': { type: 'County', name: 'Kalmar län' },
     'SE-G': { type: 'County', name: 'Kronobergs län' },
     'SE-F': { type: 'County', name: 'Jönköpings län' },
     'SE-E': { type: 'County', name: 'Östergötlands län' },
     'SE-D': { type: 'County', name: 'Södermanlands län' },
     'SE-C': { type: 'County', name: 'Uppsala län' },
     'SE-W': { type: 'County', name: 'Dalarnas län' },
     'SE-Z': { type: 'County', name: 'Jämtlands län' },
     'SE-Y': { type: 'County', name: 'Västernorrlands län' },
     'SE-X': { type: 'County', name: 'Gävleborgs län' },
     'SE-AC': { type: 'County', name: 'Västerbottens län' },
     'SE-AB': { type: 'County', name: 'Stockholms län' },
     'SE-BD': { type: 'County', name: 'Norrbottens län' },
     'SE-T': { type: 'County', name: 'Örebro län' },
     'SE-S': { type: 'County', name: 'Värmlands län' },
     'SE-U': { type: 'County', name: 'Västmanlands län' } },
  code: 'SE' }

> iso3166.country("United Nations");
null

Flexible Address Validation

This package includes enhanced address validation that handles countries without postal codes. Use the flexible validator extension:

const iso3166 = require('iso-3166-2/flexible_validator_extension');

// Countries without postal codes (like UAE, Hong Kong) always return true
console.log(iso3166.validateFlexible('AE', 'DU', null));
// { isValid: true, flexible: true, reason: 'United Arab Emirates doesn't require postal codes - always valid' }

// Countries with postal codes require them
console.log(iso3166.validateFlexible('US', 'CA', null));
// { isValid: false, reason: 'United States requires postal code' }

console.log(iso3166.validateFlexible('US', 'CA', '90210'));
// { isValid: true, flexible: false, reason: 'Valid address' }

// Check if a country is flexible
console.log(iso3166.isFlexible('AE')); // true
console.log(iso3166.isFlexible('US')); // false

// Get list of flexible countries
console.log(iso3166.flexibleCountries);
// ['AE', 'AG', 'AO', 'AW', 'BB', 'BF', 'BI', 'BJ', 'BO', 'BS', 'BW', 'BZ', ...]

Functions

iso3166.subdivision(code)

Retrieves a subdivision by its full code, ex "SE-O", "US-IN". Returns null if not found.

iso3166.subdivision(country code, subdivision code)

Retrieves a subdivision by its country code and subdivision code, ex ("SWE", "O"). Returns null if not found.

iso3166.subdivision(country code, subdivision name)

Retrieves a subdivision by its country code and subdivision name, ex ("US", "Indiana"). Returns null if not found.

iso3166.country(country code)

Retrieves a country by its code, ex "US", "SE", "SWE". Returns null if not found.

iso3166.country(country name)

Retrieves a country by its name, ex "United States", "Sweden". Returns null if not found.

iso3166.data

The raw ISO 3166-2 data, the layout is:

{
  country code (alpha 2): {
    name: country name, ex Sweden, United States ...
    sub: {
      subdivision code: {
        type: subdivision type, ex county, divison ...
        name: subdivision name, ex Västra Götaland, Indiana
      }
    }
  }
}

iso3166.codes

The ISO 3166-1 alpha 3 to alpha 2 conversion table, the layout is:

{
  country code (alpha 3): country code (alpha 2)
}

iso3166.validateFlexible(countryCode, subdivisionCode, postalCode)

Enhanced address validation that returns true for countries without postal codes regardless of input. Returns an object with validation details:

{
  isValid: boolean,
  flexible: boolean,
  reason: string,
  country: string
}

iso3166.isFlexible(countryCode)

Returns true if the country doesn't require postal codes.

iso3166.flexibleCountries

Array of country codes that don't require postal codes.

Contributors

• Ola Holmström (@olahol) - Original author
• Ben Ilegbodu (@benmvp)
• David García (@davidgf)
• lhchavez (@lhchavez)
• Peter Pinch (@pdpinch)
• Meyank Singh (@meyank-ssh) - Flexible validator extension