i18n-iso-util

A utility library for ISO-3166 codes

Install

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

Getting Started

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

1import { getCountry } from 'i18n-iso-util';
2
3/**
4 * Accepts alpha-2, alpha-3 or full name input
5 * NOTE: All inputs are compared via a case sensitive exact string match
6 */
7getCountry('IN'); // => {alpha2: 'IN', alpha3: 'IND', fullName: 'India', numericCode: '356'}
8getCountry('IND'); // => {alpha2: 'IN', alpha3: 'IND', fullName: 'India', numericCode: '356'}
9getCountry('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.

1import {
2  alpha2ToAlpha3,
3  alpha2ToFullName,
4  alpha3ToAlpha2,
5  alpha3ToFullName,
6  fullNameToAlpha2,
7  fullNameToAlpha3,
8} from 'i18n-iso-util';
9
10// NOTE: All inputs are compared via a case sensitive exact string match
11
12alpha2ToAlpha3('IN'); // => IND
13alpha2ToFullName('IN'); // => India
14alpha3ToAlpha2('IND'); // => IN
15alpha3ToFullName('IND'); // => India
16fullNameToAlpha2('India'); // => IN
17fullNameToAlpha3('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