wooorm / iso-3166

ISO 3166 (standard for country codes and codes for their subdivisions)

iso-3166

Info on ISO 3166.

Contents

• What is this?
• When should I use this?
• Matrix
• Install
• Use
• API
  • iso31661
  • iso31661Reserved
  • iso31662
  • iso31663
• Types
• Compatibility
• Security
• Related
• Contribute
• License

What is this?

This package contains info on ISO 3166. The purpose of ISO 3166 is to define internationally recognized codes that we can use when we refer to countries and their subdivisions.

ISO 3166 includes three parts:

• ISO 3166-1 defines codes for countries (such as US USA United States of America)
• ISO 3166-2 defines codes for subdivisions (such as US-CA for California in US USA United States of America)
• ISO 3166-3 defines codes for former countries (such as BUMM to refer to when BU BUR Burma revised its name to MM MMR Myanmar in 1989)

While the information in ISO 3166 is well known and freely available through for example WikiPedia, it is not freely available in a machine readable format from ISO. That’s where this project comes in: it scrapes WikiPedia.

ISO 3166 is closely tied to the work of the United Nations: the names for countries stem from the UN and ISO 3166 maps to numerical UN M49 codes and vice versa. UN M49 also includes information on bigger regions between our earth and countries.

This project includes all three parts of ISO 3166 as separate exports:

• iso31661 — countries: list of assigned ISO 3166-1 entries
• iso31662 — subdivisions: list of ISO 3166-2 entries
• iso31663 — revisions: list of ISO 3166-3 entries

Additionally, a list of reserved ISO 3166-1 entries is available:

• iso31661Reserved — list of reserved ISO 3166-1 entries

Finally, indexes are available to map between different codes:

• iso31661Alpha2ToAlpha3 — map ISO 3166-1 alpha-2 codes to ISO 3166-1 alpha-3 codes
• iso31661Alpha2ToNumeric — map ISO 3166-1 alpha-2 codes to ISO 3166-1 numeric (UN M49) codes
• iso31661Alpha3ToAlpha2 — map ISO 3166-1 alpha-3 codes to ISO 3166-1 alpha-2 codes
• iso31661NumericToAlpha2 — map ISO 3166-1 numeric (UN M49) codes to ISO 3166-1 alpha-2 codes

When should I use this?

You can use this package any time you have to deal with countries and subdivisions or ISO 3166 in particular. The alphabetical codes from ISO 3166 are more useful to humans, but the numerical codes from UN M49 are more resilient to changes. UN M49 also encodes regions bigger than countries, such as (sub)contintents.

Matrix

Show ISO 3166-1 alpha-2 code matrix

	A	B	C	D	E	F	G	H	I	J	K	L	M	N	O	P	Q	R	S	T	U	V	W	X	Y	Z
A	AA	AB	AC	AD	AE	AF	AG	AH	AI	AJ	AK	AL	AM	AN	AO	AP	AQ	AR	AS	AT	AU	AV	AW	AX	AY	AZ
B	BA	BB	BC	BD	BE	BF	BG	BH	BI	BJ	BK	BL	BM	BN	BO	BP	BQ	BR	BS	BT	BU	BV	BW	BX	BY	BZ
C	CA	CB	CC	CD	CE	CF	CG	CH	CI	CJ	CK	CL	CM	CN	CO	CP	CQ	CR	CS	CT	CU	CV	CW	CX	CY	CZ
D	DA	DB	DC	DD	DE	DF	DG	DH	DI	DJ	DK	DL	DM	DN	DO	DP	DQ	DR	DS	DT	DU	DV	DW	DX	DY	DZ
E	EA	EB	EC	ED	EE	EF	EG	EH	EI	EJ	EK	EL	EM	EN	EO	EP	EQ	ER	ES	ET	EU	EV	EW	EX	EY	EZ
F	FA	FB	FC	FD	FE	FF	FG	FH	FI	FJ	FK	FL	FM	FN	FO	FP	FQ	FR	FS	FT	FU	FV	FW	FX	FY	FZ
G	GA	GB	GC	GD	GE	GF	GG	GH	GI	GJ	GK	GL	GM	GN	GO	GP	GQ	GR	GS	GT	GU	GV	GW	GX	GY	GZ
H	HA	HB	HC	HD	HE	HF	HG	HH	HI	HJ	HK	HL	HM	HN	HO	HP	HQ	HR	HS	HT	HU	HV	HW	HX	HY	HZ
I	IA	IB	IC	ID	IE	IF	IG	IH	II	IJ	IK	IL	IM	IN	IO	IP	IQ	IR	IS	IT	IU	IV	IW	IX	IY	IZ
J	JA	JB	JC	JD	JE	JF	JG	JH	JI	JJ	JK	JL	JM	JN	JO	JP	JQ	JR	JS	JT	JU	JV	JW	JX	JY	JZ
K	KA	KB	KC	KD	KE	KF	KG	KH	KI	KJ	KK	KL	KM	KN	KO	KP	KQ	KR	KS	KT	KU	KV	KW	KX	KY	KZ
L	LA	LB	LC	LD	LE	LF	LG	LH	LI	LJ	LK	LL	LM	LN	LO	LP	LQ	LR	LS	LT	LU	LV	LW	LX	LY	LZ
M	MA	MB	MC	MD	ME	MF	MG	MH	MI	MJ	MK	ML	MM	MN	MO	MP	MQ	MR	MS	MT	MU	MV	MW	MX	MY	MZ
N	NA	NB	NC	ND	NE	NF	NG	NH	NI	NJ	NK	NL	NM	NN	NO	NP	NQ	NR	NS	NT	NU	NV	NW	NX	NY	NZ
O	OA	OB	OC	OD	OE	OF	OG	OH	OI	OJ	OK	OL	OM	ON	OO	OP	OQ	OR	OS	OT	OU	OV	OW	OX	OY	OZ
P	PA	PB	PC	PD	PE	PF	PG	PH	PI	PJ	PK	PL	PM	PN	PO	PP	PQ	PR	PS	PT	PU	PV	PW	PX	PY	PZ
Q	QA	QB	QC	QD	QE	QF	QG	QH	QI	QJ	QK	QL	QM	QN	QO	QP	QQ	QR	QS	QT	QU	QV	QW	QX	QY	QZ
R	RA	RB	RC	RD	RE	RF	RG	RH	RI	RJ	RK	RL	RM	RN	RO	RP	RQ	RR	RS	RT	RU	RV	RW	RX	RY	RZ
S	SA	SB	SC	SD	SE	SF	SG	SH	SI	SJ	SK	SL	SM	SN	SO	SP	SQ	SR	SS	ST	SU	SV	SW	SX	SY	SZ
T	TA	TB	TC	TD	TE	TF	TG	TH	TI	TJ	TK	TL	TM	TN	TO	TP	TQ	TR	TS	TT	TU	TV	TW	TX	TY	TZ
U	UA	UB	UC	UD	UE	UF	UG	UH	UI	UJ	UK	UL	UM	UN	UO	UP	UQ	UR	US	UT	UU	UV	UW	UX	UY	UZ
V	VA	VB	VC	VD	VE	VF	VG	VH	VI	VJ	VK	VL	VM	VN	VO	VP	VQ	VR	VS	VT	VU	VV	VW	VX	VY	VZ
W	WA	WB	WC	WD	WE	WF	WG	WH	WI	WJ	WK	WL	WM	WN	WO	WP	WQ	WR	WS	WT	WU	WV	WW	WX	WY	WZ
X	XA	XB	XC	XD	XE	XF	XG	XH	XI	XJ	XK	XL	XM	XN	XO	XP	XQ	XR	XS	XT	XU	XV	XW	XX	XY	XZ
Y	YA	YB	YC	YD	YE	YF	YG	YH	YI	YJ	YK	YL	YM	YN	YO	YP	YQ	YR	YS	YT	YU	YV	YW	YX	YY	YZ
Z	ZA	ZB	ZC	ZD	ZE	ZF	ZG	ZH	ZI	ZJ	ZK	ZL	ZM	ZN	ZO	ZP	ZQ	ZR	ZS	ZT	ZU	ZV	ZW	ZX	ZY	ZZ

Install

This package is ESM only. In Node.js (version 14.14+, 16.0+), install with npm:

npm install iso-3166

In Deno with esm.sh:

import * as iso3166 from 'https://esm.sh/iso-3166@4'

In browsers with esm.sh:

<script type="module">
  import * as iso3166 from 'https://esm.sh/iso-3166@4?bundle'
</script>

Use

See examples below.

API

This package exports the identifiers iso31661, iso31661Alpha2ToAlpha3, iso31661Alpha2ToNumeric, iso31661Alpha3ToAlpha2, iso31661NumericToAlpha2, iso31661Reserved, iso31662, iso31663. There is no default export.

iso31661

List of assigned ISO 3166-1 countries (Array<ISO31661Entry>).

Example

import {iso31661} from 'iso-3166'

console.log(iso31661)

Yields:

[
  {state: 'assigned', alpha2: 'AD', alpha3: 'AND', numeric: '020', name: 'Andorra'},
  {state: 'assigned', alpha2: 'AE', alpha3: 'ARE', numeric: '784', name: 'United Arab Emirates'},
  {state: 'assigned', alpha2: 'AF', alpha3: 'AFG', numeric: '004', name: 'Afghanistan'},
  {state: 'assigned', alpha2: 'AG', alpha3: 'ATG', numeric: '028', name: 'Antigua and Barbuda'},
  {state: 'assigned', alpha2: 'AI', alpha3: 'AIA', numeric: '660', name: 'Anguilla'},
  // …
]

iso31661Reserved

List of reserved ISO 3166-1 countries (Array<ISO31661Entry>).

Example

import {iso31661Reserved} from 'iso-3166'

console.log(iso31661Reserved)

Yields:

[
  {state: 'exceptionally-reserved', alpha2: 'AC', name: 'Ascension Island'},
  {state: 'transitionally-reserved', alpha2: 'AN', name: 'Netherlands Antilles'},
  {state: 'indeterminately-reserved', alpha2: 'AP', name: 'African Regional Industrial Property Organization'},
  {state: 'transitionally-reserved', alpha2: 'BU', name: 'Burma'},
  {state: 'indeterminately-reserved', alpha2: 'BX', name: 'Benelux Trademarks and Designs Office'},
  // …
]

iso31662

List of ISO 3166-2 subdivisions (Array<ISO31662Entry>).

Example

import {iso31662} from 'iso-3166'

console.log(iso31662)

Yields:

[
  {code: 'AD-02', name: 'Canillo', parent: 'AD'},
  {code: 'AD-03', name: 'Encamp', parent: 'AD'},
  // …
  {code: 'BD-01', name: 'Bandarban', parent: 'BD-B'},
  {code: 'BD-02', name: 'Barguna', parent: 'BD-A'},
  // …
  {code: 'BD-A', name: 'Barisal', parent: 'BD'},
  {code: 'BD-B', name: 'Chittagong', parent: 'BD'},
  // …
]

iso31663

List of ISO 3166-3 changes (Array<ISO31663Entry>).

Example

import {iso31663} from 'iso-3166'

console.log(iso31663)

Yields:

[
  {
    alpha4: 'AIDJ',
    type: 'change',
    from: {state: 'formerly-assigned', alpha2: 'AI', alpha3: 'AFI', numeric: '262', name: 'French Afars and Issas'},
    to: [
      {state: 'assigned', alpha2: 'DJ', alpha3: 'DJI', numeric: '262', name: 'Djibouti'}
    ]
  },
  {
    alpha4: 'ANHH',
    type: 'split',
    from: {state: 'formerly-assigned', alpha2: 'AN', alpha3: 'ANT', numeric: '530', name: 'Netherlands Antilles'},
    to: [
      {state: 'assigned', alpha2: 'BQ', alpha3: 'BES', numeric: '535', name: 'Bonaire, Sint Eustatius and Saba'},
      {state: 'assigned', alpha2: 'CW', alpha3: 'CUW', numeric: '531', name: 'Curaçao'},
      {state: 'assigned', alpha2: 'SX', alpha3: 'SXM', numeric: '534', name: 'Sint Maarten (Dutch part)'}
    ]
  },
  {
    alpha4: 'BQAQ',
    type: 'merge',
    from: {state: 'formerly-assigned', alpha2: 'BQ', alpha3: 'ATB', name: 'British Antarctic Territory'},
    to: [
      {state: 'assigned', alpha2: 'AQ', alpha3: 'ATA', numeric: '010', name: 'Antarctica'}
    ]
  },
  // …
]

ISO31661Entry

Object representing a country.

• state (State) — state (example: 'assigned')
• alpha2 (string) — ISO 3166-1 alpha-2 code (example: 'GB')
• alpha3 (string?) — ISO 3166-1 alpha-3 code (example: 'GBR')
• numeric (string?) — ISO 3166-1 numeric (UN M49) code (example: '826')
• name (string?) — name (example: 'United Kingdom of Great Britain and Northern Ireland')

Based on the state of the entry, fields may be available. Assigned entries have all fields. Reserved entries have alpha2 and name fields.

State

string, one of the following:

• 'assigned' — currently assigned (example: VA VAT Holy See)
• 'indeterminately-reserved' — reserved as other coding systems use them (example: FL was used on some car vehicle distinguishing signs from LI LIE Liechtenstein before 1949)
• 'exceptionally-reserved' — reserved by a national ISO member body (example: UK is reserved by United Kingdom)
• 'transitionally-reserved' — reserved for a while after removing a country (example: BU Burma as it changed names to MM MMR Myanmar in 1989)
• 'formerly-assigned' — codes that were previously in use but are no longer strictly reserved (example: PZ Panama Canal Zone, which was a US USA United States of America controlled area until 1979)

Assigned

Many ISO 3166-1 entries are assigned and therefore have a state of 'assigned'.

Reserved

Some ISO 3166-1 entries are not assigned but still have some data attached to them.

User-assigned

ISO 3166-1 also has a concept of “user-assigned” codes, which can be used by users (like you) to represent things not in ISO 3166 (example: XZ represents international waters in UN/LOCODE).

The user-assigned codes are:

• ISO 3166-1 alpha-2: AA, QM to QZ, XA to XZ, and ZZ
• ISO 3166-1 alpha-3: AAA to AAZ, QMA to QZZ, XAA to XZZ, and ZZA to ZZZ
• ISO 3166-1 numeric: 900 to 999

User-assigned codes will not be used by ISO 3166 and are not exposed by this package.

Unassigned

All other codes are unassigned and may be used by ISO 3166 in the future.

Unassigned codes are not exposed by this package.

ISO31662Entry

Object representing a subdivision of a country.

• code (string) — ISO 3166-2 code (example: GB-BFS)
• name (string) — name (example: 'Belfast')
• parent (string) — ISO 3166-1 alpha-2 code or ISO 3166-2 code (example: 'GB')

The code field always has the format of an ISO 3166 alpha-2 code, followed by a hyphen minus (-), and one, two, or three upper alphabetical or numerical characters. The latter part of the code is not unique: ID-RI is the Riau province of Indonesia and NG-RI is the Rivers province in Nigeria.

The parent field can be either the ISO 3166-1 alpha-2 of a country, or another ISO 3166-2 code of a subdivision. The latter is true for BE-WNA Namur, whose parent is BE-WAL Waals Gewest, whose parent in turn is BE BEL Belgium. To get the country a subdivision is a part of, do something like code.slice(0, 2) to get the ISO 3166-1 alpha-2 code from an ISO 3166-2 code.

ISO31663Entry

Object representing a change to a country.

• alpha4 (string) — ISO 3166-3 alpha-4 code (example: ANHH)
• type (Type) — type of revision (example: 'split')
• from (ISO31661Entry) — country before revision
• to (ISO31661Entry[]) — list of countries after revision

The entries in from and to may not match current ISO 3166-1 entries. For example, CSHH represents the split of CS CSK Czechoslovakia to CZ CZE Czech Republic and SK SVK Slovakia, but the former now uses CZ CZE Czechia. Another example, YUCS represents the change of YU YUG Yugoslavia to CS SCG Serbia and Montenegro, but the latter later split with CSXX to ME MNE Montenegro and RS SRB Serbia.

Type

string, one of the following:

• 'merge' — revision where one country merged with others (example: DDDE represents the merger from DD DDR German Democratic Republic to form DE DEU Germany in 1990)
• 'change' — significant name revision (example: BYAA represents the name change from BY BYS Byelorussian SSR to BY BLR Belarus in 1992)
• 'split' — revision where one country split into others (example: NTHH represents the division of NT NTZ Neutral Zone to IQ IRQ Iraq and SA SAU Saudi Arabia in 1993)

Types

This package is fully typed with TypeScript. It exports the additional types ISO31661Entry, ISO31661AssignedEntry, ISO31661ReservedEntry, ISO31662Entry, ISO31663Entry, State, and Type.

Compatibility

This package is at least compatible with all maintained versions of Node.js. As of now, that is Node.js 14.14+ and 16.0+. It also works in Deno and modern browsers.

Security

This package is safe.

Related

• wooorm/bcp-47 — parse and stringify BCP 47 language tags
• wooorm/bcp-47-normalize — normalize, canonicalize, and format BCP 47 tags
• wooorm/bcp-47-match — match BCP 47 language tags with language ranges per RFC 4647
• wooorm/iso-639-2 — ISO 639-2 codes
• wooorm/iso-639-3 — ISO 639-3 codes
• wooorm/iso-15924 — ISO 15924 codes
• wooorm/un-m49 — UN M49 codes

Contribute

Yes please! See How to Contribute to Open Source.

License

MIT © Titus Wormer

iso-3166's Issues

Spanish subdivisions are in double language with no space/split character

I am looking at the library and caught a possible issue. In Spain some subdivisions have the name in 2 languages. However, the string of the name concatenates the two versions.

Example:

{ code: 'ES-NA', name: 'NavarraNafarroa', parent: true },

This is Navarra in Spanish, and Nafarroa in Basque. But the name is not usable in this way.

Either the object should contain the two languages, or allow a better split. In theory, the iso table contains the language code which would make this much easier.

Shall we consider to refactor the list including the language code?

Name in two languages without any space between them

Hi,

Hi,

I stumbled upon some names in the 2.js file that I'm not sure if they're 100% correct.
Code 'ES-A' has 'AlicanteAlacant' as a name. That is in fact Alicante (name of the region in Spanish) and Alacant (name of the region in Catalan) joined in a single word. Same happens in 'ES-CS' - 'CastellónCastelló' (Castellón in Spanish and Castelló in Catalan), 'ES-NA' - 'Navarra, Comunidad Foral deNafarroako Foru Komunitatea' (Navarra, Comunidad Foral de in Spanish, Nafarroako Foru Komunitatea in Basque) and 'ES-PV' - 'País VascoEuskal Herria' (País Vasco in Spanish, Euskal Herria in Basque).

While the data is correct for those cases, as both names are official, the representation of the data, joining both without anything that indicates so, seems misleading. I think they'd be better with the local variant indicator, as 'LR-RI', 'MU-CC' and some others.

I'd be happy to do the PR myself but wanted to open the issue first to check that I'm not wrong about that.

Thank you

ISO Org

The ISO codes and the mapping is collected from ISO.org???
Data is as per standards but still there are some extra information that user may need to implement some business logic.
Can someone please confirm?

Trouble retrieving English names for South African provinces

For some reason I have yet to figure out, the English names for South African provinces aren't being consistently retrieved:

iso-3166/2.js

Lines 25208 to 25252 in 7aacab6

	{
	code: 'ZA-EC',
	name: 'Kapa-Vuxa',
	parent: 'ZA'
	},
	{
	code: 'ZA-FS',
	name: 'Free State',
	parent: 'ZA'
	},
	{
	code: 'ZA-GP',
	name: 'Gauteng',
	parent: 'ZA'
	},
	{
	code: 'ZA-KZN',
	name: 'Kwazulu-Natal',
	parent: 'ZA'
	},
	{
	code: 'ZA-LP',
	name: 'Limpopo',
	parent: 'ZA'
	},
	{
	code: 'ZA-MP',
	name: 'Mpumalanga',
	parent: 'ZA'
	},
	{
	code: 'ZA-NC',
	name: "Kapa-N'walungu",
	parent: 'ZA'
	},
	{
	code: 'ZA-NW',
	name: "N'walungu-Vupeladyambu",
	parent: 'ZA'
	},
	{
	code: 'ZA-WC',
	name: 'Kapa-Vupeladyambu',
	parent: 'ZA'
	},

For reference it should be:

  {
    code: 'ZA-EC',
    name: 'Eastern Cape',
    parent: 'ZA'
  },
  {
    code: 'ZA-FS',
    name: 'Free State',
    parent: 'ZA'
  },
  {
    code: 'ZA-GP',
    name: 'Gauteng',
    parent: 'ZA'
  },
  {
    code: 'ZA-KZN',
    name: 'Kwazulu-Natal',
    parent: 'ZA'
  },
  {
    code: 'ZA-LP',
    name: 'Limpopo',
    parent: 'ZA'
  },
  {
    code: 'ZA-MP',
    name: 'Mpumalanga',
    parent: 'ZA'
  },
  {
    code: 'ZA-NC',
    name: 'Northern Cape',
    parent: 'ZA'
  },
  {
    code: 'ZA-NW',
    name: 'North-West',
    parent: 'ZA'
  },
  {
    code: 'ZA-WC',
    name: 'Western Cape',
    parent: 'ZA'
  },