Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/wooorm/iso-3166

ISO 3166 (standard for country codes and codes for their subdivisions)
https://github.com/wooorm/iso-3166

code country iso iso-3166 iso-3166-1 iso-3166-2 iso-3166-3 region state subdivision territory

Last synced: 8 days ago
JSON representation

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

Host: GitHub
URL: https://github.com/wooorm/iso-3166
Owner: wooorm
License: mit
Created: 2020-04-22T18:39:29.000Z (almost 5 years ago)
Default Branch: main
Last Pushed: 2023-11-01T12:08:18.000Z (about 1 year ago)
Last Synced: 2025-01-15T18:05:23.927Z (15 days ago)
Topics: code, country, iso, iso-3166, iso-3166-1, iso-3166-2, iso-3166-3, region, state, subdivision, territory
Language: JavaScript
Homepage:
Size: 658 KB
Stars: 82
Watchers: 4
Forks: 13
Open Issues: 1
Metadata Files:
- Readme: readme.md
- Funding: funding.yml
- License: license

Awesome Lists containing this project

README

# iso-3166

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]

Info on [ISO 3166][i3166].

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Matrix](#matrix)
* [Install](#install)
* [Use](#use)
* [API](#api)
* [`iso31661`](#iso31661)
* [`iso31661Reserved`](#iso31661reserved)
* [`iso31662`](#iso31662)
* [`iso31663`](#iso31663)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Related](#related)
* [Contribute](#contribute)
* [License](#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][um49] 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`][1]
— countries: list of [assigned][] ISO 3166-1 entries
* [`iso31662`][2]
— subdivisions: list of ISO 3166-2 entries
* [`iso31663`][3]
— revisions: list of ISO 3166-3 entries

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

* [`iso31661Reserved`][1-reserved]
— list of [reserved][] ISO 3166-1 entries

Finally, indexes are available to map between different codes:

* [`iso31661Alpha2ToAlpha3`][1-a2-to-1-a3]
— map ISO 3166-1 alpha-2 codes to ISO 3166-1 alpha-3 codes
* [`iso31661Alpha2ToNumeric`][1-a2-to-1-n]
— map ISO 3166-1 alpha-2 codes to ISO 3166-1 numeric (UN M49) codes
* [`iso31661Alpha3ToAlpha2`][1-a3-to-1-a2]
— map ISO 3166-1 alpha-3 codes to ISO 3166-1 alpha-2 codes
* [`iso31661NumericToAlpha2`][1-n-to-1-a2]
— 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][um49] 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][esm].
In Node.js (version 14.14+, 16.0+), install with [npm][]:

```sh
npm install iso-3166
```

In Deno with [`esm.sh`][esmsh]:

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

In browsers with [`esm.sh`][esmsh]:

```html

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

```

## 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`][1-entry]).

###### Example

```js
import {iso31661} from 'iso-3166'

console.log(iso31661)
```

Yields:

```js
[
{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`][1-entry]).

###### Example

```js
import {iso31661Reserved} from 'iso-3166'

console.log(iso31661Reserved)
```

Yields:

```js
[
{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`][2-entry]).

###### Example

```js
import {iso31662} from 'iso-3166'

console.log(iso31662)
```

Yields:

```js
[
{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`][3-entry]).

###### Example

```js
import {iso31663} from 'iso-3166'

console.log(iso31663)
```

Yields:

```js
[
{
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])
— 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])
— type of revision (example: `'split'`)
* `from` ([`ISO31661Entry`][1-entry])
— country before revision
* `to` ([`ISO31661Entry[]`][1-entry])
— 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`](https://github.com/wooorm/bcp-47)
— parse and stringify BCP 47 language tags
* [`wooorm/bcp-47-normalize`](https://github.com/wooorm/bcp-47-normalize)
— normalize, canonicalize, and format BCP 47 tags
* [`wooorm/bcp-47-match`](https://github.com/wooorm/bcp-47-match)
— match BCP 47 language tags with language ranges per RFC 4647
* [`wooorm/iso-639-2`](https://github.com/wooorm/iso-639-2)
— ISO 639-2 codes
* [`wooorm/iso-639-3`](https://github.com/wooorm/iso-639-3)
— ISO 639-3 codes
* [`wooorm/iso-15924`](https://github.com/wooorm/iso-15924)
— ISO 15924 codes
* [`wooorm/un-m49`](https://github.com/wooorm/un-m49)
— UN M49 codes

## Contribute

Yes please!
See [How to Contribute to Open Source][contribute].

## License

[build-badge]: https://github.com/wooorm/iso-3166/workflows/main/badge.svg

[build]: https://github.com/wooorm/iso-3166/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/iso-3166.svg

[coverage]: https://codecov.io/github/wooorm/iso-3166

[downloads-badge]: https://img.shields.io/npm/dm/iso-3166.svg

[downloads]: https://www.npmjs.com/package/iso-3166

[size-badge]: https://img.shields.io/bundlephobia/minzip/iso-3166.svg

[size]: https://bundlephobia.com/result?p=iso-3166

[npm]: https://docs.npmjs.com/cli/install

[esmsh]: https://esm.sh

[license]: license

[author]: https://wooorm.com

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[typescript]: https://www.typescriptlang.org

[contribute]: https://opensource.guide/how-to-contribute/

[i3166]: https://www.iso.org/iso-3166-country-codes.html

[um49]: https://unstats.un.org/unsd/methodology/m49/

[1]: 1.js

[2]: 2.js

[3]: 3.js

[1-reserved]: 1-reserved.js

[1-a2-to-1-a3]: 1-a2-to-1-a3.js

[1-a2-to-1-n]: 1-a2-to-1-n.js

[1-a3-to-1-a2]: 1-a3-to-1-a2.js

[1-n-to-1-a2]: 1-n-to-1-a2.js

[1-entry]: #iso31661entry

[2-entry]: #iso31662entry

[3-entry]: #iso31663entry

[state]: #state

[type]: #type

[assigned]: #assigned

[reserved]: #reserved