Country State Data

A comprehensive JSON dataset containing a hierarchical list of countries, states, cities, regions, and languages. This repository provides structured geographical and linguistic data that can be easily integrated into applications requiring location-based functionality.

Features

• Complete list of countries with ISO codes, currencies, timezones, and translations
• States/provinces/regions for each country
• Cities data organized by states and countries
• Regional classifications
• Language data with native names
• TypeScript definitions included
• Multiple file formats (full and minified versions)
• Well-structured JSON format
• Easy to integrate
• Regularly maintained and verified data

Installation

PNPM (Recommended)

pnpm add country-state-data

NPM

npm install country-state-data

Direct Download

Download the JSON files directly from this repository for local use.

Quick Start

Using the main API (Recommended)

// Install the package
pnpm add country-state-data

// Import the main API
import countryStateData from 'country-state-data';

// Get all countries
const countries = countryStateData.getAllCountries();
console.log(countries.length); // 250 countries

// Find USA by code
const usa = countryStateData.getCountryByCode('US');
console.log(usa.name); // "United States"

// Get US states
const usStates = countryStateData.getStatesByCountry('US');
console.log(usStates.length); // 50+ states/territories

// Search for countries
const searchResults = countryStateData.searchCountries('united');
console.log(searchResults); // Returns USA, UAE, UK

// Validate country code
const isValid = countryStateData.isValidCountryCode('US'); // true

// Get country flag emoji
const flag = countryStateData.getCountryFlag('JP'); // 🇯🇵

Direct JSON import (Alternative)

import countries from 'country-state-data/countries';
import states from 'country-state-data/states';

// Direct access to raw data
const usa = countries.find(c => c.iso2 === 'US');
const usStates = states.filter(s => s.country_code === 'US');

Available Data Files

File	Description	Size
countries.json	Complete country data	~119KB
states.json	Complete state/province data	~605KB
cities.json	Cities organized by country and state	~35MB
regions.json	World regions data	~419B
languages.json	World languages with native names	~15KB
types.d.ts	TypeScript definitions	Included

Data Structure

Countries (countries.json)

{
  "id": 1,
  "name": "Afghanistan",
  "iso3": "AFG",
  "iso2": "AF",
  "phone_code": "93",
  "capital": "Kabul",
  "currency": "AFN",
  "currency_symbol": "؋",
  "native": "افغانستان",
  "region": "Asia",
  "subregion": "Southern Asia",
  "latitude": "33.00000000",
  "longitude": "65.00000000",
  "emoji": "🇦🇫"
}

States (states.json)

{
  "id": 3901,
  "name": "Badakhshan",
  "country_id": 1,
  "country_code": "AF",
  "country_name": "Afghanistan",
  "state_code": "BDS",
  "latitude": "36.73477250",
  "longitude": "70.81199530"
}

Cities (cities.json)

{
  "id": 1,
  "states": [
    {
      "id": 3901,
      "cities": [
        {
          "id": 52,
          "name": "Ashkāsham",
          "latitude": "36.68333000",
          "longitude": "71.53333000"
        }
      ]
    }
  ]
}

Regions (regions.json)

{
  "id": "111",
  "name": "Asia",
  "hasCountries": true
}

Languages (languages.json)

{
  "code": "en",
  "name": "English",
  "native": "English"
}

API Documentation

Main API Methods

The package provides a comprehensive API through the main export:

const countryStateData = require('country-state-data');
// or
import countryStateData from 'country-state-data';

Country Methods

• getAllCountries() - Returns all countries
• getCountryByCode(code) - Get country by ISO2 or ISO3 code
• getCountryById(id) - Get country by numeric ID
• getCountriesByRegion(regionName) - Get countries in a region
• getCountriesBySubregion(subregionName) - Get countries in a subregion
• searchCountries(query) - Search countries by name, native name, capital, or nationality
• getCountriesByCurrency(currencyCode) - Get countries using a currency
• getCountriesByPhoneCode(phoneCode) - Get countries by phone code

State/Province Methods

• getAllStates() - Returns all states/provinces
• getStatesByCountry(countryCode) - Get states by country ISO code
• getStatesByCountryId(countryId) - Get states by country ID
• getStateByCode(stateCode, countryCode) - Get specific state
• searchStates(query, countryCode?) - Search states, optionally within a country

City Methods

• getCitiesByState(stateId) - Get cities in a state
• getCitiesByCountry(countryCode) - Get all cities in a country
• searchCities(query, countryCode?, stateId?) - Search cities

Region Methods

• getAllRegions() - Get all regions
• getRegionById(regionId) - Get region by ID
• getUniqueRegions() - Get unique region names
• getUniqueSubregions() - Get unique subregion names

Language Methods

• getAllLanguages() - Get all languages
• getLanguageByCode(code) - Get language by ISO code
• searchLanguages(query) - Search languages

Currency Methods

• getAllCurrencies() - Get all unique currencies
• getCurrencyByCode(currencyCode) - Get currency details

Timezone Methods

• getAllTimezones() - Get all unique timezones
• getCountriesByTimezone(zoneName) - Get countries in a timezone

Validation Methods

• isValidCountryCode(code) - Validate country code
• isValidStateCode(stateCode, countryCode) - Validate state code
• isValidLanguageCode(code) - Validate language code
• isValidCurrencyCode(code) - Validate currency code

Utility Methods

• getCountryFlag(countryCode) - Get country flag emoji
• getCountryPhoneFormat(countryCode) - Get phone format with country code
• getCountryInfo(countryCode) - Get extended country info with state/city counts
• getStatistics() - Get data statistics

Usage Examples

Using the Main API (Recommended)

const countryStateData = require('country-state-data');
// or ES6: import countryStateData from 'country-state-data';

// Get all countries
const allCountries = countryStateData.getAllCountries();
console.log(`Total countries: ${allCountries.length}`);

// Find USA
const usa = countryStateData.getCountryByCode('US');
console.log(usa.name); // "United States"
console.log(usa.capital); // "Washington"
console.log(usa.emoji); // "🇺🇸"

// Get US states
const usStates = countryStateData.getStatesByCountry('US');
console.log(`US has ${usStates.length} states/territories`);

// Search for cities
const newYorkCities = countryStateData.searchCities('New York', 'US');
console.log(newYorkCities);

// Get countries by region
const asianCountries = countryStateData.getCountriesByRegion('Asia');
console.log(`Asia has ${asianCountries.length} countries`);

// Currency operations
const usdCountries = countryStateData.getCountriesByCurrency('USD');
console.log('Countries using USD:', usdCountries.map(c => c.name));

// Validation
console.log(countryStateData.isValidCountryCode('US')); // true
console.log(countryStateData.isValidCountryCode('XX')); // false

// Get statistics
const stats = countryStateData.getStatistics();
console.log(stats);
// {
//   totalCountries: 250,
//   totalStates: 5000+,
//   totalLanguages: 180+,
//   totalRegions: 7,
//   totalCurrencies: 160+,
//   totalTimezones: 400+
// }

Direct JSON Import (Alternative)

const countries = require('country-state-data/countries');
const states = require('country-state-data/states');
const cities = require('country-state-data/cities');

// Direct access to raw JSON data
const usa = countries.find(country => country.iso2 === 'US');
const usStates = states.filter(state => state.country_code === 'US');

JavaScript (ES6 Modules)

import countries from 'country-state-data/countries';
import states from 'country-state-data/states';
import cities from 'country-state-data/cities';

// Get all countries
console.log(countries);

// Create a country dropdown
function createCountryDropdown() {
  const select = document.createElement('select');
  
  countries.forEach(country => {
    const option = document.createElement('option');
    option.value = country.iso2;
    option.textContent = `${country.emoji} ${country.name}`;
    select.appendChild(option);
  });
  
  return select;
}

// Handle country selection change
function onCountryChange(countryCode) {
  const country = countries.find(c => c.iso2 === countryCode);
  const countryStates = states.filter(s => s.country_code === countryCode);
  
  console.log(`Selected: ${country.name}`);
  console.log(`States: ${countryStates.length}`);
}

TypeScript

import { Country, State, Region, Language } from 'country-state-data/types';
import countries from 'country-state-data/countries';
import states from 'country-state-data/states';
import regions from 'country-state-data/regions';
import languages from 'country-state-data/languages';

// Type-safe country operations
const getCountryByCode = (code: string): Country | undefined => {
  return countries.find((country: Country) => country.iso2 === code);
};

// Type-safe state operations
const getStatesByCountry = (countryId: number): State[] => {
  return states.filter((state: State) => state.country_id === countryId);
};

// Get countries by region with type safety
const getCountriesByRegion = (regionName: string): Country[] => {
  return countries.filter((country: Country) => country.region === regionName);
};

// React component example
interface CountrySelectorProps {
  onSelect: (country: Country) => void;
}

const CountrySelector: React.FC<CountrySelectorProps> = ({ onSelect }) => {
  return (
    <select onChange={(e) => {
      const country = getCountryByCode(e.target.value);
      if (country) onSelect(country);
    }}>
      <option value="">Select a country</option>
      {countries.map((country: Country) => (
        <option key={country.id} value={country.iso2}>
          {country.emoji} {country.name}
        </option>
      ))}
    </select>
  );
};

// Language selector component
const LanguageSelector: React.FC = () => {
  return (
    <select>
      {languages.map((language: Language) => (
        <option key={language.code} value={language.code}>
          {language.native} ({language.name})
        </option>
      ))}
    </select>
  );
};

Advanced Usage Examples

Real-World Example: E-commerce Address Form

import { Country, State } from 'country-state-data/types';
import countries from 'country-state-data/countries';
import states from 'country-state-data/states';

class AddressForm {
  private countries: Country[] = countries;
  private states: State[] = states;

  // Create cascading country/state dropdowns
  createCountryDropdown(onCountryChange: (countryCode: string) => void) {
    const select = document.createElement('select');
    select.innerHTML = '<option value="">Select Country</option>';
    
    this.countries.forEach(country => {
      const option = document.createElement('option');
      option.value = country.iso2;
      option.textContent = `${country.emoji} ${country.name}`;
      select.appendChild(option);
    });
    
    select.onchange = (e) => onCountryChange((e.target as HTMLSelectElement).value);
    return select;
  }

  createStateDropdown(countryCode: string) {
    const select = document.createElement('select');
    select.innerHTML = '<option value="">Select State</option>';
    
    const country = this.countries.find(c => c.iso2 === countryCode);
    if (!country) return select;
    
    const countryStates = this.states.filter(state => state.country_id === country.id);
    
    countryStates.forEach(state => {
      const option = document.createElement('option');
      option.value = state.state_code;
      option.textContent = state.name;
      select.appendChild(option);
    });
    
    return select;
  }

  // Validate address data
  validateAddress(countryCode: string, stateCode?: string): boolean {
    const country = this.countries.find(c => c.iso2 === countryCode);
    if (!country) return false;

    if (stateCode) {
      return this.states.some(state => 
        state.state_code === stateCode && 
        state.country_id === country.id
      );
    }
    
    return true;
  }

  // Get phone format for country
  getPhoneFormat(countryCode: string): string {
    const country = this.countries.find(c => c.iso2 === countryCode);
    return country ? `+${country.phone_code}` : '';
  }

  // Get currency info for pricing
  getCurrencyInfo(countryCode: string) {
    const country = this.countries.find(c => c.iso2 === countryCode);
    return country ? {
      currency: country.currency,
      symbol: country.currency_symbol,
      name: country.currency_name
    } : null;
  }
}

// Usage example
const addressForm = new AddressForm();
const countryDropdown = addressForm.createCountryDropdown((countryCode) => {
  const stateDropdown = addressForm.createStateDropdown(countryCode);
  document.getElementById('state-container')?.appendChild(stateDropdown);
  
  // Update phone format
  const phoneInput = document.getElementById('phone') as HTMLInputElement;
  phoneInput.placeholder = addressForm.getPhoneFormat(countryCode) + ' XXX XXXX';
  
  // Update currency display
  const currency = addressForm.getCurrencyInfo(countryCode);
  const priceDisplay = document.getElementById('price');
  if (priceDisplay && currency) {
    priceDisplay.textContent = `Price: ${currency.symbol}99.99 ${currency.currency}`;
  }
});

Search and Filter Functionality

import { Country, State, Language } from 'country-state-data/types';
import countries from 'country-state-data/countries';
import states from 'country-state-data/states';
import languages from 'country-state-data/languages';

class LocationSearchService {
  // Search countries by name or native name
  searchCountries(query: string): Country[] {
    const lowercaseQuery = query.toLowerCase();
    return countries.filter(country => 
      country.name.toLowerCase().includes(lowercaseQuery) ||
      country.native.toLowerCase().includes(lowercaseQuery) ||
      country.iso2.toLowerCase() === lowercaseQuery ||
      country.iso3.toLowerCase() === lowercaseQuery
    );
  }

  // Get countries by region
  getCountriesByRegion(region: string): Country[] {
    return countries.filter(country => country.region === region);
  }

  // Get countries by currency
  getCountriesByCurrency(currencyCode: string): Country[] {
    return countries.filter(country => country.currency === currencyCode);
  }

  // Get states by country
  getStatesByCountry(countryCode: string): State[] {
    const country = countries.find(c => c.iso2 === countryCode);
    if (!country) return [];
    return states.filter(state => state.country_id === country.id);
  }

  // Search languages
  searchLanguages(query: string): Language[] {
    const lowercaseQuery = query.toLowerCase();
    return languages.filter(lang =>
      lang.name.toLowerCase().includes(lowercaseQuery) ||
      lang.native.toLowerCase().includes(lowercaseQuery) ||
      lang.code.toLowerCase() === lowercaseQuery
    );
  }

  // Get unique regions
  getRegions(): string[] {
    return [...new Set(countries.map(country => country.region))];
  }

  // Get unique currencies
  getCurrencies(): Array<{code: string, name: string, symbol: string}> {
    const currencies = new Map();
    countries.forEach(country => {
      if (!currencies.has(country.currency)) {
        currencies.set(country.currency, {
          code: country.currency,
          name: country.currency_name,
          symbol: country.currency_symbol
        });
      }
    });
    return Array.from(currencies.values());
  }
}

// Usage examples
const searchService = new LocationSearchService();

// Search for countries
const usaResults = searchService.searchCountries('united');
const japanResults = searchService.searchCountries('JP');

// Filter by region
const europeanCountries = searchService.getCountriesByRegion('Europe');

// Get USD countries
const usdCountries = searchService.getCountriesByCurrency('USD');

// Get all regions for a dropdown
const regions = searchService.getRegions();

// Get all currencies
const currencies = searchService.getCurrencies();

Use Cases

• E-commerce: Country/state selection for shipping addresses
• Forms: Address validation and auto-completion
• Analytics: Geographical data analysis and reporting
• Internationalization: Multi-language country names
• Travel Apps: Location-based services and booking
• Educational: Geography learning applications
• Government: Administrative division management
• Real Estate: Location-based property listings

File Size Considerations

• Use minified versions for production to reduce bundle size
• Consider loading data dynamically based on user interaction
• Implement lazy loading for large datasets like cities
• Use compression (gzip) when serving files

TypeScript Support

This package includes comprehensive TypeScript definitions. All imports are automatically typed:

import { Country, State, Language } from 'country-state-data/types';
import countries from 'country-state-data/countries'; // Country[]
import states from 'country-state-data/states';       // State[]
import languages from 'country-state-data/languages'; // Language[]

// Full type safety
const usa: Country = countries.find(c => c.iso2 === 'US')!;
const californiaStates: State[] = states.filter(s => s.country_code === 'US');

Available Types

• Country - Complete country information with ISO codes, currency, timezone, etc.
• State - State/province information with coordinates
• City - City data organized by country and state
• Region - World regions
• Language - Language codes with native names
• Timezone - Timezone information with GMT offsets
• Translations - Country name translations

Contributing

Contributions to keep the data accurate and up-to-date are welcome. Please submit a pull request with any corrections or updates.

Data Sources

• ISO country codes
• Official government sources
• United Nations data
• Currency and timezone databases

License

This project is open source and available under the MIT License.