🌍 TS-Countries-List

A comprehensive, type-safe TypeScript library for querying country information including names, codes, currencies, languages, regions, and more.

Note: All country data in this library was generated by Grok, an AI assistant by xAI.

✨ Features

• 🔍 Multiple lookup methods - Search by name, alpha-2, alpha-3, numeric codes, phone codes, or capital cities
• 🌐 Rich filtering - Filter by continent, region, subregion, language, or currency
• 📊 Aggregation functions - Group and count countries by various attributes
• ✅ Validation utilities - Validate country codes, currencies, and languages
• 🎯 100% TypeScript - Full type safety with excellent IDE autocomplete
• 🚀 Zero dependencies - Lightweight and fast
• 📦 Tree-shakeable - Import only what you need

📦 Installation

npm install ts-countries-list

yarn add ts-countries-list

pnpm add ts-countries-list

🚀 Quick Start

import {
  getCountryByAlpha2,
  getCountriesByContinent,
  searchCountriesByName,
} from "ts-countries-list";

// Get country by code
const usa = getCountryByAlpha2("US");
console.log(usa?.name); // "United States"
console.log(usa?.currency); // { code: "USD", name: "United States dollar", symbol: "$" }

// Search countries
const countries = searchCountriesByName("united");
// Returns: United States, United Kingdom, United Arab Emirates

// Filter by continent
const asianCountries = getCountriesByContinent(["Asia"]);

📚 API Reference

Lookup Functions (Single Country)

getCountryByName(name: CountryName): Country | undefined

Get a country by its exact name.

const country = getCountryByName("Japan");

getCountryByAlpha2(code: CountryCode): Country | undefined

Get a country by its ISO 3166-1 alpha-2 code.

const country = getCountryByAlpha2("JP");

getCountryByAlpha3(code: CountryAlpha3): Country | undefined

Get a country by its ISO 3166-1 alpha-3 code.

const country = getCountryByAlpha3("JPN");

getCountryByCode(code: string): Country | undefined

Search by any code type (alpha-2, alpha-3, or numeric).

const country = getCountryByCode("392"); // Japan by numeric code

getCountryByCapital(capital: string): Country | undefined

Get a country by its capital city (case-insensitive).

const country = getCountryByCapital("Tokyo");

searchCountriesByName(query: string): Country[]

Search countries by partial name match (case-insensitive).

const results = searchCountriesByName("republic");

getCountriesByPhoneCode(phoneCode: string): Country[]

Get countries by phone dialing code.

const countries = getCountriesByPhoneCode("+44"); // UK

Filter Functions (Multiple Countries)

getCountriesByCurrency(code: CurrencyCode): Country[]

Get all countries using a specific currency.

const euroCountries = getCountriesByCurrency("EUR");

getCountriesByContinent(continents: Continents[]): Country[]

Get countries by continent(s).

const countries = getCountriesByContinent(["Europe", "Asia"]);

getCountriesByRegion<R>(region: R, subRegion?: SubregionsOf<R>): Country[]

Get countries by region and optional subregion.

const countries = getCountriesByRegion("Americas", "South America");

getCountriesByLanguage(language: Language): Country[]

Get countries where a language is spoken.

const spanishSpeaking = getCountriesByLanguage("Spanish");

getCountriesByMultipleFilters(filters: CountryFilterOptions): Country[]

Advanced filtering with multiple criteria.

const countries = getCountriesByMultipleFilters({
  continent: "Europe",
  currency: "EUR",
  language: "German",
});

Projection Functions

getCountriesByFields<F>(filters: CountryFilterOptions, fields: F[]): Pick<Country, F>[]

Get countries with only specific fields.

const simplified = getCountriesByFields({ continent: "Africa" }, [
  "name",
  "capital",
  "alpha2",
]);
// Returns: [{ name: '...', capital: '...', alpha2: '...' }, ...]

Aggregation & Metadata

getAllRegions(): CountryRegion[]

Get all available regions.

getSubregions<R>(region: R): SubregionsOf<R>[]

Get all subregions for a specific region.

getAllContinents(): Continents[]

Get all continents.

getAllCurrencies(): CurrencyCode[]

Get all unique currency codes.

getAllLanguages(): Language[]

Get all unique languages.

getAllPhoneCodes(): string[]

Get all unique phone codes.

getCountryNames(): CountryName[]

Get all country names.

getCountryAlpha2Codes(): CountryCode[]

Get all ISO alpha-2 codes.

getCountryAlpha3Codes(): CountryAlpha3[]

Get all ISO alpha-3 codes.

Grouping Functions

getCountriesGroupedByContinent(): Record<Continents, Country[]>

Group all countries by continent.

getCountriesGroupedByRegion(): Record<CountryRegion, Country[]>

Group all countries by region.

getCountriesGroupedByCurrency(): Record<CurrencyCode, Country[]>

Group all countries by currency.

getCountriesGroupedByLanguage(): Record<Language, Country[]>

Group all countries by language.

Counting Functions

getCountryCountByContinent(): Record<Continents, number>

Count countries per continent.

getCountryCountByRegion(): Record<CountryRegion, number>

Count countries per region.

getTotalCountries(): number

Get total number of countries.

Validation Functions

isValidCountryCode(code: string): boolean

Check if a country code is valid.

isValidCountryCode("US"); // true
isValidCountryCode("ZZ"); // false

isValidCurrencyCode(code: CurrencyCode): boolean

Check if a currency code is valid.

isValidLanguage(language: Language): boolean

Check if a language exists in the dataset.

Utility Functions

getPotentialNeighbors(countryCode: CountryCode): Country[]

Get countries in the same subregion (potential neighbors).

const neighbors = getPotentialNeighbors("DE"); // Other Western European countries

compareCountries(code1: CountryCode, code2: CountryCode): CountryComparison

Compare two countries.

const comparison = compareCountries("US", "CA");
console.log(comparison.sameContinent); // true
console.log(comparison.sharedLanguages); // ['English']

getCountryRegion(identifier: string): CountryRegion | undefined

Get the region of a country by any identifier (name, alpha2, alpha3, or numeric code).

const region = getCountryRegion("US"); // 'Americas'
const region2 = getCountryRegion("Japan"); // 'Asia'
const region3 = getCountryRegion("DEU"); // 'Europe' (using alpha3)

🏗️ Country Data Structure

Each country object contains:

interface Country {
  name: string;
  officialName: string;
  alpha2: string; // ISO 3166-1 alpha-2
  alpha3: string; // ISO 3166-1 alpha-3
  numeric: string; // ISO 3166-1 numeric
  capital: string;
  region: string;
  subregion: string;
  continent: string;
  nativeName: string;
  languages: readonly string[];
  currency: {
    code: string;
    name: string;
    symbol: string;
  };
  phoneCode: string;
  phoneMask: string;
}

🎯 TypeScript Support

This library is written in TypeScript and provides excellent type inference:

import { getCountriesByRegion, type Country } from "ts-countries-list";

// TypeScript knows the exact subregions for each region
const countries = getCountriesByRegion("Asia", "Eastern Asia"); // ✅
const countries = getCountriesByRegion("Asia", "Western Europe"); // ❌ Type error!

// Full autocomplete support
const country: Country = getCountryByAlpha2("FR")!;
country.currency.code; // Full autocomplete for all properties

📊 Example Use Cases

Get all EU countries using Euro

import { getCountriesByMultipleFilters } from "ts-countries-list";

const euEuroCountries = getCountriesByMultipleFilters({
  region: "Europe",
  currency: "EUR",
});

Build a country selector dropdown

import { getCountryNames, getCountryByName } from "ts-countries-list";

const countryOptions = getCountryNames().map((name) => ({
  label: name,
  value: getCountryByName(name)?.alpha2,
}));

Find countries that share a language

import { getCountriesByLanguage } from "ts-countries-list";

const frenchSpeaking = getCountriesByLanguage("French");
console.log(frenchSpeaking.map((c) => c.name));
// ['France', 'Belgium', 'Canada', 'Switzerland', ...]

Compare two countries

import { compareCountries } from "ts-countries-list";

const comparison = compareCountries("US", "GB");
console.log({
  sameCurrency: comparison.sameCurrency, // false
  sharedLanguages: comparison.sharedLanguages, // ['English']
  sameContinent: comparison.sameContinent, // false (North America vs Europe)
});

🤝 Data Source

All country data in this library was generated by Grok, an AI assistant developed by xAI. While we strive for accuracy, please verify critical information for production use cases.

📝 License

MIT

🐛 Issues & Contributions

Found a bug or want to contribute? Please open an issue or pull request on GitHub.

⚠️ Disclaimer

This library is provided as-is. The country data was AI-generated and may contain inaccuracies. Always verify important information against official sources such as:

• ISO 3166-1 for country codes
• ISO 4217 for currency codes
• Official government and UN sources for political boundaries and territories

Made with ❤️ using data generated by Grok