i18n-iso-util

A utility library for ISO-3166 codes

Install

npm install i18n-iso-util # Typescript types are included

Getting Started

The getCountry function accepts alpha-2, alpha-3 and full name search input.

import { getCountry } from 'i18n-iso-util';

/**
 * Accepts alpha-2, alpha-3 or full name input
 * NOTE: All inputs are compared via a case sensitive exact string match
 */
getCountry('IN'); // => {alpha2: 'IN', alpha3: 'IND', fullName: 'India', numericCode: '356'}
getCountry('IND'); // => {alpha2: 'IN', alpha3: 'IND', fullName: 'India', numericCode: '356'}
getCountry('India'); // => {alpha2: 'IN', alpha3: 'IND', fullName: 'India', numericCode: '356'}

For those who want to lookup codes with a specific use-case in mind, the library exposes the following functions.

import {
  alpha2ToAlpha3,
  alpha2ToFullName,
  alpha3ToAlpha2,
  alpha3ToFullName,
  fullNameToAlpha2,
  fullNameToAlpha3,
} from 'i18n-iso-util';

// NOTE: All inputs are compared via a case sensitive exact string match

alpha2ToAlpha3('IN'); // => IND
alpha2ToFullName('IN'); // => India
alpha3ToAlpha2('IND'); // => IN
alpha3ToFullName('IND'); // => India
fullNameToAlpha2('India'); // => IN
fullNameToAlpha3('India'); // => IND

Datasources

A core goal of this library is to auto-generate data from the original source for each published ISO standard. This section aims to establish datasources for each standard in use.

ISO 3166-1 Country Codes

ISO-3166-1 is a standard defining codes for the names of countries.

These codes are maintained by the International Organisation for Standardization (ISO) on their online portal.

NOTE: ISO does not provide this data for free in any easily readable file format. Therefore, this library creates it's datasources through an automated web-scaper script found in scripts/extract-iso-3166-1.ts

Upcoming Features

• Performance improvements for country lookup
• Fuzzy matching for full country names and case insensitive lookups
• Integrate ISO-3166-2 to support country subdivisions
• Integrate ISO-4217 currency codes and suport lookup and standardized currencies by country
• Integrate IANA time zone database by parsing data directly from the source. Support lookup by country code

Credits

• Created and maintained by @AdiRishi
• Inspired by various country and currency lookup libraries like node-i18n-iso-countries and pycountry