country-codes-list

country-codes-list

A list of 250 countries with ISO codes, currencies, languages, phone codes and tax identifiers.

Why this package

• One record per country. It includes data that other packages do not ship together: TIN/VAT identifiers, local-language names, alternative codes (UK, EL) and national phone number lengths.
• Zero runtime dependencies.
• TypeScript types for every record and every function.
• A test suite that checks dataset-wide invariants (unique codes, valid ISO 4217, ITU-T E.164 limits).
• The same data as JSON and CSV files, on npm and on a CDN.

Install

npm install country-codes-list

The package is CommonJS with named exports. import works through Node's CommonJS interop. There is no native ESM build.

const countryCodes = require("country-codes-list");
// or
import * as countryCodes from "country-codes-list";
import { findOneByCode } from "country-codes-list";

Quick start

Look up a country by any code:

const countryCodes = require("country-codes-list");

countryCodes.findOneByCode("UK").countryCode; // 'GB'
countryCodes.findOneByCode("840").countryNameEn; // 'United States of America'

Build the options of a <select> element:

countryCodes.customArray(
  { name: "{countryNameEn}", value: "{countryCode}" },
  { sortBy: "name" }
);
// [{ name: 'Afghanistan', value: 'AF' }, { name: 'Åland Islands', value: 'AX' }, ...]

Group countries by calling code:

countryCodes.customGroupedList("countryCallingCode", "{countryCode}")["1"];
// ['AG', 'AI', 'AS', 'BB', 'BM', 'CA', 'DM', 'GD', 'GU', 'JM', 'KN', 'LC',
//  'MS', 'PR', 'SX', 'TT', 'US', 'VC', 'VG', 'VI', 'DO', 'BS', 'KY', 'MP',
//  'TC', 'UM']

Data fields

Each record is a CountryData object. The example column shows the US record.

Field	Type	Example	Notes and source
countryNameEn	string	"United States of America"	English name.
countryNameLocal	string	"United States of America"	Name in the local language.
countryCode	string	"US"	ISO 3166-1 alpha-2. Unique.
countryCodeAlpha3	string	"USA"	ISO 3166-1 alpha-3. Unique.
countryCodeNumeric	string	"840"	ISO 3166-1 numeric, three digits with leading zeros ("004" for AF). Empty only for XK (Kosovo).
altCodes	string[] (optional)	absent	Other 2-letter codes in use. Only GB (["UK"]) and GR (["EL"]) have it. Use findOneByCode to search it.
currencyCode	string	"USD"	ISO 4217 code. Empty for AQ (Antarctica).
currencyNameEn	string	"United States dollar"	ISO 4217 English name. Empty for AQ.
currencyNumeric	string	"840"	ISO 4217 numeric, three digits. Empty for AQ. Source: ISO 4217 List One.
currencyDecimals	number | null	2	ISO 4217 minor units: 0 for JPY, 3 for BHD. null for AQ. Same source.
currencySymbol	string	"$"	CLDR English narrow symbol from Node's ICU. Not unique. Falls back to the code ("CHF"). Empty for AQ.
tinType	string	"EIN"	Short name of the tax identifier. Populated for 62 of 250 records. Source: Wikipedia.
tinName	string	"Tax Identification Number"	Full name of the tax identifier. Populated for 64 of 250 records. Same source.
officialLanguageCode	string	"en"	ISO 639-1 code of the first official language. ISO 639-3 when the language has no 639-1 code. Source: OSM Nominatim.
officialLanguageNameEn	string	"English"	English name of that language.
officialLanguageNameLocal	string	"English"	Name of that language in the language itself.
countryCallingCode	string	"1"	ITU-T E.164 country code, 1 to 3 digits, no +. Source: Wikipedia.
areaCodes	string[]	[]	National area codes after the calling code. Populated for NANP members (not US or UM), plus CC, CX and SJ. An empty array means "not recorded".
nationalNumberLengths	number[]	[10]	Possible digit counts of the national number, sorted. Empty for AQ, BV, GS, HM, PN, TF, UM. Source: libphonenumber (fixed-line and mobile only).
region	string	"North America"	One of six values adapted from the ITU regions.
flag	string	"🇺🇸"	Flag emoji, derived from countryCode.

Things to know

nationalNumberLengths is a set, not a range. Numbering plans have holes. The Netherlands is [9, 11], so a 10-digit Dutch number is not valid. Use includes, never a min/max comparison.

const nl = countryCodes.findOneByCode("NL").nationalNumberLengths; // [9, 11]
nl.includes(10); // false, correct
10 >= Math.min(...nl) && 10 <= Math.max(...nl); // true, wrong

The area code is counted, the trunk prefix is not. The British number 020 7946 0958 has a national number of 2079460958. That is 10 digits, area code included. Remove the leading 0 before you compare.

countryCodes.findOneByCode("GB").nationalNumberLengths.includes("2079460958".length); // true

currencySymbol is not unique. 29 currencies show "$" (USD, CAD, AUD, MXN and more). "£", "kr", "¥" and "₩" are also shared. Do not use the symbol as a key.

customList keys must be unique. countryCode and countryCodeAlpha3 are unique. countryCallingCode, currencyCode, region and officialLanguageCode are not. With a shared key, only the last country survives. Use customGroupedList for shared keys.

Array fields are not keys or placeholders. altCodes, areaCodes and nationalNumberLengths are arrays. filter, findOne, customList, customGroupedList and sortDataBy reject them (a TypeScript error). A placeholder such as {areaCodes} stays in the output as written.

all() returns a new array on each call. all() === all() is false. You can sort or change the returned array without effect on the dataset. The country objects inside are shared. Treat them as read-only.

Dataset order is not alphabetical. Most records are sorted by countryCode. 33 records (SZ, MK, PH, NL, AE, ..., XK) come at the end, and KI, KN come after KR. If you need a specific order, sort the result.

findOneByCode validates before it uppercases. Input must be 2 or 3 ASCII letters, or 3 ASCII digits, after trim. All other input returns undefined. Unicode case mapping ("ß" to "SS") cannot make a valid code from invalid input.

UK and EL are not ISO codes. findOneByCode("UK") returns the United Kingdom, but countryCode stays "GB". findOne("countryCode", "UK") returns undefined.

region has six values. Africa, Arab States, Asia & Pacific, Europe, North America and South/Latin America. They follow the ITU classification, with two changes: ITU's "The Americas" is split in two, and ITU's "CIS" countries are placed in Europe or Asia & Pacific.

API reference

All examples use const countryCodes = require("country-codes-list");.

all()

all(): CountryData[]

Returns every country in dataset order, as a new array.

countryCodes.all().length; // 250
countryCodes.all()[0].countryNameEn; // 'Andorra'

filter(key, value)

filter(key: CountryScalarProperty, value: string): CountryData[]

Returns every country where key equals value exactly.

countryCodes.filter("currencyCode", "XCG").map((c) => c.countryCode);
// ['CW', 'SX']

findOne(key, value)

findOne(key: CountryScalarProperty, value: string): CountryData | undefined

Returns the first country where key equals value exactly. The comparison is case-sensitive and ignores altCodes.

countryCodes.findOne("countryCodeAlpha3", "ARG").countryNameEn; // 'Argentina'
countryCodes.findOne("countryCode", "ZZ"); // undefined

findOneByCode(code)

findOneByCode(code: string): CountryData | undefined

Resolves an alpha-2, alpha-3, alternative or numeric code to a country. The match is case-insensitive and ignores surrounding spaces. Official codes win over alternative codes. Use it for codes from a browser locale, a VAT number or an external API.

countryCodes.findOneByCode("UK").countryCode; // 'GB'
countryCodes.findOneByCode("gbr").countryCode; // 'GB'
countryCodes.findOneByCode("EL").countryCode; // 'GR'
countryCodes.findOneByCode("004").countryCode; // 'AF'
countryCodes.findOneByCode("4"); // undefined, numeric codes need three digits
countryCodes.findOneByCode("ZZ"); // undefined

customList(key?, label?, options?)

customList(
  key?: CountryScalarProperty,   // default "countryCode"
  label?: string,                // default "{countryNameEn} ({countryCode})"
  options?: { filter?: (country: CountryData) => boolean }
): Record<string, string>

Returns an object with one entry per country. key selects the property that becomes the object key. label is a template. Each {placeholder} is replaced with the value of that property. Unknown placeholders and array fields stay as written.

countryCodes.customList("countryCode", "[{countryCode}] {countryNameEn}: +{countryCallingCode}");
// {
//   AD: '[AD] Andorra: +376',
//   AF: '[AF] Afghanistan: +93',
//   AG: '[AG] Antigua and Barbuda: +1',
//   ...
// }

customGroupedList(key?, label?, options?)

customGroupedList(
  key?: CountryScalarProperty,   // default "countryCallingCode"
  label?: string,                // default "{countryNameEn} ({countryCode})"
  options?: { filter?: (country: CountryData) => boolean }
): Partial<Record<string, string[]>>

Same as customList, but each key maps to an array of all matching countries. Groups keep dataset order. A key that no country matched is absent, so the type is Partial.

countryCodes.customGroupedList("region", "{countryNameEn}", {
  filter: (country) => country.currencyCode === "EUR",
});
// { Europe: ['Andorra', 'Austria', 'Åland Islands', 'Belgium', ...], 'South/Latin America': [...], ... }

const onlyAR = countryCodes.customGroupedList("region", "{countryCode}", {
  filter: (country) => country.countryCode === "AR",
});
onlyAR["Europe"]; // undefined
onlyAR["Europe"]?.length ?? 0; // 0

customArray(fields?, options?)

customArray<F extends Record<string, string>>(
  fields?: F,   // default { name: "{countryNameEn} ({countryCode})", value: "{countryCode}" }
  options?: {
    sortBy?: keyof F;                             // a key of YOUR template
    sortDataBy?: CountryScalarProperty;           // a dataset property
    filter?: (country: CountryData) => boolean;
  }
): Record<keyof F, string>[]

Returns one object per country, shaped like fields. Each value is a template with {placeholder} syntax.

Option	Applies to	Effect
filter	dataset	Keeps only the countries that return true. Runs first.
sortDataBy	dataset property ("countryNameEn")	Sorts the countries before rendering.
sortBy	key of your template ("name")	Sorts the output after rendering.

Both sorts use Intl.Collator with accent sensitivity.

countryCodes.customArray(
  { label: "{flag} {countryNameEn}", value: "{countryCode}" },
  { filter: (c) => c.region === "North America", sortBy: "label" }
);
// [
//   { label: '🇧🇲 Bermuda', value: 'BM' },
//   { label: '🇨🇦 Canada', value: 'CA' },
//   { label: '🇵🇲 Saint Pierre and Miquelon', value: 'PM' },
//   { label: '🇺🇸 United States of America', value: 'US' }
// ]

utils.groupBy(array, key)

utils.groupBy<T>(array: T[], key: keyof T): Record<string, T[]>

Groups any array of objects by one key. customGroupedList uses it internally.

countryCodes.utils.groupBy(countryCodes.all(), "region")["Arab States"].length; // 22

Types

import type { CountryData, CountryProperty, CountryScalarProperty } from "country-codes-list";

Type	Meaning
CountryData	One record. See Data fields.
CountryProperty	Every key of CountryData, arrays and currencyDecimals included.
CountryScalarProperty	Only the string-valued keys. filter, findOne, customList, customGroupedList and sortDataBy accept this type.

const key: CountryScalarProperty = "currencyCode";
const pick = (country: CountryData) => country[key];

Data exports

The package also ships the dataset as files, for spreadsheets, Python, SQL or a web page:

File	Content
dist/countries.json	The array that all() returns, pretty-printed.
dist/countries.csv	One row per country. The header lists every field.

Both files are on jsDelivr, pinned to the major version:

https://cdn.jsdelivr.net/npm/country-codes-list@3/dist/countries.json
https://cdn.jsdelivr.net/npm/country-codes-list@3/dist/countries.csv

const countries = await fetch(
  "https://cdn.jsdelivr.net/npm/country-codes-list@3/dist/countries.json"
).then((r) => r.json());

CSV format notes:

• UTF-8 without a BOM. Import the file as UTF-8.
• Rows end with LF. Cells are quoted per RFC 4180.
• Array fields (altCodes, areaCodes, nationalNumberLengths) are joined with |. null is an empty cell.
• countryCodeNumeric and currencyNumeric keep their leading zeros. Read these columns as text, or "004" becomes 4.

Contributing

Build and test:

npm ci
npm run build   # tsc, then writes dist/countries.json and dist/countries.csv
npm test        # jest, 8 suites

CI runs the same steps on Node 22 and 24. Write PR titles and bodies in English.

Generated fields

Five fields are written by scripts, not by hand. Do not edit them manually. The currency and number-length scripts need network access. No script runs in CI.

Command	Fields	Source
npm run data:numeric	countryCodeNumeric	ISO 3166-1 table embedded in the script.
npm run data:currencies	currencyNumeric, currencyDecimals, currencySymbol	ISO 4217 List One XML (SIX Group) and Node's ICU.
npm run data:number-lengths	nationalNumberLengths	libphonenumber PhoneNumberMetadata.xml, pinned to a tag.
npm run data:all	All of the above	Runs the three scripts in order.

Each script replaces only its own field in src/countriesData.ts. A second run makes no change. Add --check for a dry run that exits with code 1 on drift.

Invariant tests and the known-gaps ledger

tests/dataset-invariants.test.ts asserts rules for every record: unique codes, valid ISO 4217, valid ISO 639, E.164 limits, the six regions. Some rules have known exceptions. Each exception is listed in a KNOWN_GAPS_* constant with a reason.

The test asserts that the ledger is exactly the set of violators. If you fix a data gap, remove its ledger entry in the same PR. If you do not, the test fails.

Migration

v2.x to v3.0

Change	Before (v2)	After (v3)
countryCallingCode holds the E.164 code only.	JM was '876'.	JM is '1', and areaCodes is ['876', '658'].
areaCodes is a required string[].	Optional any[].	Always present. Empty means "not recorded".
Key parameters accept CountryScalarProperty only.	customList("altCodes", ...) compiled.	TypeScript error. Use findOneByCode("UK") for alternative codes.

To dial a full number, join the calling code and an area code: `+${cc}${areaCodes[0]}`.

v1.x to v2.0

Change	Before (v1)	After (v2)
CountryProperty is a type, not an enum.	CountryProperty.countryCode	"countryCode", with import type.
Named CommonJS exports.	require("country-codes-list")	Same, or import * as countryCodes through interop.
Property keys are type-checked.	filter("invalidKey", "x") compiled.	TypeScript error.