Country, State, City Light Dataset

A lightweight, asynchronous TypeScript/JavaScript library for accessing comprehensive country, state, and city data with support for timezones, coordinates, and more.

Features

• 🌍 Complete country data with ISO codes, phone codes, currencies, flags, and timezones
• 🗺️ State/Province data organized by country
• 🏙️ City data organized by country and state
• 🔍 Search functionality with filtering capabilities
• 📦 Lightweight - Only loads data when needed
• ⚡ Asynchronous - Uses dynamic imports for efficient loading
• 📝 TypeScript - Full type definitions included
• 🎯 Zero dependencies - Pure TypeScript implementation

Installation

npm install async-country-state-city

Module Format

This package is ESM-only ("type": "module"). Use import in Node 18+ or modern bundlers. For CommonJS, use dynamic import().

// CommonJS example
(async () => {
  const mod = await import("async-country-state-city");
  const { Country, States, City } = mod;
  await Country.init();
  console.log(Country.getCountryByIsoCode("US"));
})();

Quick Start

import { Country, States, City } from "async-country-state-city";

// IMPORTANT: initialize country data once at app startup
await Country.init();

// Get all countries (after init)
const countries = Country.getAllCountries();

// Get countries by search
const results = Country.getAllCountries("United");

// Get country by ISO code
const usa = Country.getCountryByIsoCode("US");

// Get all states for a country
const usStates = await States.getAllStates("US");

// Get states by search
const californiaStates = await States.getAllStates("US", "Calif");

// Get state by code
const nyState = await States.getStateByCode("US", "NY");

// Get all cities for a state
const cities = await City.getAllCities("US", "NY");

// Get cities by search
const nycCities = await City.getAllCities("US", "NY", "New York");

// Get city by name
const nyc = await City.getCityByName("US", "NY", "New York");

API Reference

Country Class

Methods

init(): Promise<void>

Load and cache all country data. Call once on application startup before using other Country methods.

Returns: Promise that resolves when data is loaded

Example:

await Country.init();

getAllCountries(search?: string | string[]): CCountry[]

Get all countries, optionally filtered by search term.

Parameters:

• search (optional): A string or array of strings used to filter by name, ISO code, phone code, currency, or flag

Returns: Array of country objects

Example:

const allCountries = Country.getAllCountries();
const searchResults = Country.getAllCountries("United");

getCountryByIsoCode(isoCode: string): CCountry | undefined

Get a country by its ISO code (e.g., 'US', 'GB', 'IN').

Parameters:

• isoCode: Two-letter ISO country code

Returns: Country object or undefined

Example:

const country = Country.getCountryByIsoCode("US");

getCountryByName(name: string): CCountry | undefined

Get a country by its name (case-insensitive).

Parameters:

• name: Country name

Returns: Country object or undefined

Example:

const country = Country.getCountryByName("United States");

getCountryByPhoneCode(phoneCode: string): CCountry | undefined

Get a country by its phone code.

Parameters:

• phoneCode: Phone country code

Returns: Country object or undefined

Example:

const country = Country.getCountryByPhoneCode("1");

getCountryByCurrency(currency: string): CCountry | undefined

Get a country by its currency code (case-insensitive).

Parameters:

• currency: Currency code (e.g., 'USD', 'EUR')

Returns: Country object or undefined

Example:

const country = Country.getCountryByCurrency("USD");

State Class

Methods

getAllStates(countryCode: string | string[], search?: string | string[]): Promise<CState[]>

Get all states/provinces for a country, optionally filtered by search term.

Parameters:

• countryCode: A two-letter ISO country code or an array of codes
• search (optional): A string or array of state names to filter by (exact match, case-insensitive)

Returns: Promise resolving to array of state objects

Example:

const states = await States.getAllStates("US");
const searchResults = await States.getAllStates("US", "Calif");

getStateByCode(countryCode: string, stateCode: string): Promise<CState | undefined>

Get a state by its ISO code.

Parameters:

• countryCode: Two-letter ISO country code
• stateCode: State ISO code

Returns: Promise resolving to state object or undefined

Example:

const state = await States.getStateByCode("US", "NY");

getStateByName(countryCode: string, name: string): Promise<CState | undefined>

Get a state by its name (case-insensitive).

Parameters:

• countryCode: Two-letter ISO country code
• name: State name

Returns: Promise resolving to state object or undefined

Example:

const state = await States.getStateByName("US", "New York");

City Class

Methods

getAllCities(countryCode: string | string[], stateCode: string | string[], search?: string | string[]): Promise<CCity[]>

Get all cities for a state, optionally filtered by search term.

Parameters:

• countryCode: A two-letter ISO country code or an array of codes
• stateCode: A state ISO code or an array of codes
• search (optional): A string or array of city names to filter by (exact match, case-insensitive)

Returns: Promise resolving to array of city objects

Example:

const cities = await City.getAllCities("US", "NY");
const searchResults = await City.getAllCities("US", "NY", "New York");

getCityByName(countryCode: string, stateCode: string, name: string): Promise<CCity | undefined>

Get a city by its name (case-insensitive).

Parameters:

• countryCode: Two-letter ISO country code
• stateCode: State ISO code
• name: City name

Returns: Promise resolving to city object or undefined

Example:

const city = await City.getCityByName("US", "NY", "New York");

Data Structures

CCountry Interface

interface CCountry {
  name: string; // Country name
  phonecode: string; // Phone country code
  isoCode: string; // Two-letter ISO code
  flag: string; // Flag emoji
  currency: string; // Currency code
  latitude: string; // Country latitude
  longitude: string; // Country longitude
  timezones?: Timezones[]; // Array of timezone information
}

Timezones Interface

interface Timezones {
  zoneName: string; // Timezone zone name (e.g., "America/New_York")
  gmtOffset: number; // GMT offset in seconds
  gmtOffsetName: string; // GMT offset name (e.g., "UTC-05:00")
  abbreviation: string; // Timezone abbreviation (e.g., "EST")
  tzName: string; // Timezone name
}

CState Interface

interface CState {
  name: string; // State/province name
  isoCode: string; // State ISO code
  countryCode: string; // Country ISO code
  latitude?: string | null; // State latitude (optional)
  longitude?: string | null; // State longitude (optional)
}

CCity Interface

interface CCity {
  name: string; // City name
  countryCode: string; // Country ISO code
  stateCode: string; // State ISO code
  latitude?: string | null; // City latitude (optional)
  longitude?: string | null; // City longitude (optional)
}

Usage Examples

Example 1: Building a Country Selector

import { Country } from "async-country-state-city";

await Country.init();
const countries = Country.getAllCountries();
const countryOptions = countries.map((country) => ({
  value: country.isoCode,
  label: `${country.flag} ${country.name}`,
  phoneCode: country.phonecode,
}));

Example 2: Cascading Dropdowns

import { Country, States, City } from "async-country-state-city";

await Country.init();
async function handleCountryChange(countryCode: string) {
  const states = await States.getAllStates(countryCode);
  // Update state dropdown
}

async function handleStateChange(countryCode: string, stateCode: string) {
  const cities = await City.getAllCities(countryCode, stateCode);
  // Update city dropdown
}

Example 3: Location Autocomplete

import { City } from "async-country-state-city";

async function searchCities(
  query: string,
  countryCode: string,
  stateCode: string
) {
  const results = await City.getAllCities(countryCode, stateCode, query);
  return results.map((city) => ({
    name: city.name,
    coordinates: {
      lat: parseFloat(city.latitude || "0"),
      lng: parseFloat(city.longitude || "0"),
    },
  }));
}

Example 4: Timezone Information

import { Country } from "async-country-state-city";

const usa = Country.getCountryByIsoCode("US");
if (usa?.timezones) {
  usa.timezones.forEach((tz) => {
    console.log(`${tz.zoneName}: ${tz.gmtOffsetName}`);
  });
}

Development

Building

npm run build

Running

npm run dev

Data Coverage

This library includes data for:

• All recognized countries worldwide
• States/provinces for supported countries
• Cities for supported states/provinces
• Timezone information for countries
• Geographic coordinates (latitude/longitude)
• Phone codes and currency information

TypeScript Support

This library is written in TypeScript and includes full type definitions. Type definitions are automatically included when importing the package.

Importing Types

Public types are also exported at ./interface for direct imports when needed.

import type {
  CCountry,
  CState,
  CCity,
  Timezones,
} from "async-country-state-city/interface";

License

MIT

Author

Devesh Kumar Mishra

Contributing

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