# countries-list

> Continents & countries: ISO 3166-1 alpha-2 code, name, ISO 639-1 languages, capital, ISO 4217 currencies (symbols & numeric codes), native name, phone. JSON, CSV and SQL.

Latest version **3.4.1** (published 2026-07-14) · MIT license · 0 weekly downloads

## Install

```sh
npm install countries-list
pnpm add countries-list
yarn add countries-list
bun add countries-list
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 3.4.1 |
| Published | 2026-07-14 |
| First published | 2014-08-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 387 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 1329 |
| Author | Dmytro Klymenko |
| Maintainers | dmythro |
| Keywords | country, countries, continent, emoji, languages, capital, currency, data, csv, json, sql, typings, currency symbol, ISO 3166-1, ISO 639-1, ISO 4217, node, typescript |

## Links

- npm: https://www.npmjs.com/package/countries-list
- Repository: https://github.com/annexare/Countries
- Homepage: http://annexare.github.io/Countries/
- Issues: https://github.com/annexare/Countries/issues
- npm.io page: https://npm.io/package/countries-list

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 3.4.1 (latest) — 2026-07-14
- 3.4.0 — 2026-07-08
- 3.3.0 — 2026-03-04
- 3.2.2 — 2025-12-04
- 3.2.1 — 2025-12-04
- 3.2.0 — 2025-10-20
- 3.1.1 — 2024-07-31
- 3.1.0 — 2024-03-04
- 3.0.6 — 2023-10-20
- 3.0.5 — 2023-09-29
- 3.0.4 — 2023-09-29
- 3.0.3 — 2023-09-29
- 3.0.2 — 2023-09-29
- 3.0.1 — 2023-09-12
- 3.0.0 — 2023-09-12
- … 30 more at https://npm.io/package/countries-list/versions

## README

# Countries, Languages & Continents data

[![Monthly Downloads](https://img.shields.io/npm/dm/countries-list.svg)](https://www.npmjs.com/package/countries-list)
[![NPM](https://img.shields.io/npm/v/countries-list.svg 'NPM package version')](https://www.npmjs.com/package/countries-list)
[![Packagist](https://img.shields.io/packagist/v/annexare/countries-list.svg 'Packagist version')](https://packagist.org/packages/annexare/countries-list)
[![CI: JS](https://github.com/annexare/Countries/workflows/Countries%20JS/badge.svg 'CI: JS')](https://github.com/annexare/Countries/actions)
[![CI: PHP](https://github.com/annexare/Countries/workflows/Countries%20PHP/badge.svg 'CI: PHP')](https://github.com/annexare/Countries/actions)
[![Twitter](https://img.shields.io/twitter/follow/annexare.svg?label=follow+@annexare)](https://twitter.com/annexare)

Continents & countries: **ISO 3166-1 alpha-2** code (with **alpha-2** to **alpha-3** set), name, **ISO 639-1** languages, capital, **ISO 4217** currencies (with symbols & numeric codes), native name, calling codes.
Lists are available in JSON, CSV and SQL formats.
Also, contains separate JSON files with additional country **Emoji** flags data.

## Version 3.0: Breaking changes

Version 3 comes with some data structure changes.
It was completely reworked under the hood with **TypeScript**, **ESM** exports and a **Bun workspaces** monorepo structure.

Everything is strongly typed so you can easily use data with auto-complete in your IDE.

**Note**: If your projects depend on the old structure, carefully specify required versions in your dependencies.

## Installation

Package is available via:

- **Bun** `bun add countries-list`
- **NPM** `npm install countries-list`
- **Composer / Packagist** `composer require annexare/countries-list`

## Usage (version 3.x)

Module exports `continents`, `countries`, `languages` and utility functions.

```ts
// Interfaces and types
import type {
  ICountry,
  ICountryData,
  ILanguage,
  TContinentCode,
  TCountryCode,
  TLanguageCode,
} from 'countries-list'

// Main data and utils
import { continents, countries, languages } from 'countries-list'
// Utils
import { getCountryCode, getCountryData, getCountryDataList, getEmojiFlag } from 'countries-list'

// Minimal data in JSON
import countries2to3 from 'countries-list/minimal/countries.2to3.min.json'
import countries3to2 from 'countries-list/minimal/countries.3to2.min.json'
import languageNames from 'countries-list/minimal/languages.native.min'

getCountryCode('Ukraine') // 'UA'
getCountryCode('Україна') // 'UA'
getCountryData('UA') // ICountryData
```

Built files are in the `dist` directory of this repository, and `packages/countries` directory contains source data.

**Note**: JS build contains ES modules, CommonJS and IIFE (for now)

- CJS `cjs/index.js`
- ESM `mjs/index.js`
- IIFE `index.iife.js`

## Currencies (ISO 4217)

Full **ISO 4217** currency data — English and native **name**, UI **symbol**, native symbol, 3-digit **numeric** code and minor-unit **decimals** — is an **opt-in** import via the `countries-list/currencies` subpath, so it does not affect the main bundle size:

```ts
import type { ICurrency, ICurrencyData, TCurrencyCode } from 'countries-list'
import { currencies, getCurrency, getCurrencyByNumeric } from 'countries-list/currencies'

// Minimal maps (code -> value)
import currencySymbols from 'countries-list/minimal/currencies.symbol.min.json'
import currencyNumbers from 'countries-list/minimal/currencies.numeric.min.json'

currencies.UAH // { name: 'Ukrainian Hryvnia', native: 'українська гривня', symbol: '₴', symbolNative: '₴', numeric: '980', decimals: 2 }
getCurrency('JPY') // ICurrencyData: { code: 'JPY', name: 'Japanese Yen', symbol: '¥', decimals: 0, ... }
getCurrencyByNumeric('840') // ICurrencyData for USD — numeric lookup, e.g. for banking
```

The dataset covers the complete active ISO 4217 list plus a few withdrawn codes still referenced by country data (e.g. `ANG`, flagged with `withdrawn: true`). `symbol` falls back to the ISO code where a currency has no distinct Latin glyph (e.g. `CHF`, `KWD`); the local glyph is then in `symbolNative`. Symbols come from Unicode CLDR (ISO 4217 itself defines no symbols).

## Data structure examples

```ts
const continents = {
  AF: 'Africa',
  AN: 'Antarctica',
  AS: 'Asia',
  EU: 'Europe',
  NA: 'North America',
  OC: 'Oceania',
  SA: 'South America',
}

const countries = {
  // ...
  UA: {
    name: 'Ukraine',
    native: 'Україна',
    phone: [380],
    continent: 'EU',
    capital: 'Kyiv',
    currency: ['UAH'],
    languages: ['uk'],
  },
  // ...
}

const languages = {
  // ...
  uk: {
    name: 'Ukrainian',
    native: 'Українська',
  },
  ur: {
    name: 'Urdu',
    native: 'اردو',
    rtl: 1,
  },
  // ...
}

const currencies = {
  // ...
  UAH: {
    name: 'Ukrainian Hryvnia',
    native: 'українська гривня',
    symbol: '₴',
    symbolNative: '₴',
    numeric: '980',
    decimals: 2,
  },
  // ...
}
```

## Contributing to this repository

Everything is generated from strongly typed files in `packages/countries/src`, including SQL file.

Everything in `dist` is generated,
so please make data related changes **ONLY** to files from `packages/countries`, commit them.
Use `bun run build` / `bun run test` to build/test generated files.

The `currencies` dataset (`packages/countries/src/data/currencies.ts`) is generated from the official ISO 4217 list and Unicode CLDR via `packages/scripts/generateCurrencies.ts`. Refresh it with `cd packages/scripts && bun run generate:currencies` (requires network) when ISO 4217 publishes an update, rather than editing the data by hand.

## Credits

Prepared by [Annexare Studio](https://annexare.com/) from different public sources.
Feel free to use it as you need in your apps
or send updates into [this](https://github.com/annexare/Countries) public repository.
It's under MIT license.

---
_Source: https://npm.io/package/countries-list · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._