⚠️ DEPRECATED

This package is no longer maintained.

Please use html-entities instead. See: https://www.npmjs.com/package/html-entities

---

Original README below:

---

country-capitals

A fully typed mapping of countries (ISO 3166-1 alpha-2 codes) to their official capital cities with zero runtime dependencies.

Features

• 🌍 Complete mapping of ISO 3166-1 alpha-2 country codes to capital cities
• 📦 Zero runtime dependencies
• 🔍 Utility functions for capital <-> country code lookups
• 💪 Fully written in TypeScript with strict typing
• 🔧 Built-in CLI for quick lookups
• 📕 Comprehensive documentation and examples
• ✅ Well-tested with high test coverage
• 📄 MIT licensed

Installation

1# Using npm
2npm install country-capitals
3
4# Using yarn
5yarn add country-capitals
6
7# Using pnpm
8pnpm add country-capitals

Usage Examples

Direct Data Access

1import { countryCapitals } from 'country-capitals';
2
3// Access capital cities directly using country codes
4console.log(countryCapitals.US); // Output: "Washington, D.C."
5console.log(countryCapitals.FR); // Output: "Paris"
6console.log(countryCapitals.JP); // Output: "Tokyo"

Utility Functions

1import {
2  getCapital,
3  getCountryCode,
4  isCapital,
5  isCountryCode
6} from 'country-capitals';
7
8// Get capital by country code (case-insensitive)
9getCapital('US'); // "Washington, D.C."
10getCapital('us'); // "Washington, D.C."
11getCapital('ZZ'); // undefined (invalid code)
12
13// Get country code by capital name (case-insensitive)
14getCountryCode('Paris'); // "FR"
15getCountryCode('paris'); // "FR"
16getCountryCode('Unknown City'); // undefined
17
18// Validate capital names
19isCapital('London'); // true
20isCapital('PARIS'); // true (case-insensitive)
21isCapital('Fake City'); // false
22
23// Validate country codes
24isCountryCode('US'); // true
25isCountryCode('fr'); // true (case-insensitive)
26isCountryCode('ZZ'); // false (invalid code)

Using with JSON Data

For non-TypeScript environments or if you prefer direct JSON access:

1// ESM
2import countryCapitalsData from 'country-capitals/json';
3
4// CommonJS
5const countryCapitalsData = require('country-capitals/json');

Command Line Interface (CLI)

The package includes a CLI for quick lookups:

1# Look up a capital by country code
2npx country-capitals US  # Output: Washington, D.C.
3
4# Look up a country code by capital
5npx country-capitals Paris  # Output: FR
6
7# Display help
8npx country-capitals --help

API Reference

Data Exports

• countryCapitals: Readonly<CountryCapitalData> - Map of ISO 3166-1 alpha-2 country codes to capital city names

Type Exports

• ISO3166A2Code - Type for ISO 3166-1 alpha-2 country codes (e.g., 'US', 'IN')
• CapitalCityName - Type for capital city names (e.g., 'Washington, D.C.', 'New Delhi')
• CountryCapitalData - Interface for the country-to-capital mapping

Function Exports

• getCapital(countryCode: string): CapitalCityName | undefined - Returns capital city for a given country code
• getCountryCode(capitalName: string): ISO3166A2Code | undefined - Returns country code for a given capital city
• isCapital(capitalName: string): boolean - Checks if a city name is a valid capital
• isCountryCode(countryCode: string): boolean - Checks if a country code is valid

Data Source

The country-to-capital mapping is sourced from official international references and curated for accuracy. Primary sources include the UN, ISO standards, and official government data.

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request