Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/d3oxy/country-state-data

A comprehensive JSON dataset containing countries, states, cities, regions, and languages with TypeScript support. Perfect for building location-based dropdowns, address forms, and geographical applications.
https://github.com/d3oxy/country-state-data

address cities countries currency data dropdown geographical iso json languages location regions states typescript

Last synced: 5 months ago
JSON representation

A comprehensive JSON dataset containing countries, states, cities, regions, and languages with TypeScript support. Perfect for building location-based dropdowns, address forms, and geographical applications.

Awesome Lists containing this project

README 

          
# 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)

```bash

pnpm add country-state-data

```



### NPM

```bash

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)

```javascript

// 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)

```javascript

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`)

```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`)

```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`)

```json

{

  "id": 1,

  "states": [

    {

      "id": 3901,

      "cities": [

        {

          "id": 52,

          "name": "Ashkāsham",

          "latitude": "36.68333000",

          "longitude": "71.53333000"

        }

      ]

    }

  ]

}

```



### Regions (`regions.json`)

```json

{

  "id": "111",

  "name": "Asia",

  "hasCountries": true

}

```



### Languages (`languages.json`)

```json

{

  "code": "en",

  "name": "English",

  "native": "English"

}

```



## API Documentation



### Main API Methods



The package provides a comprehensive API through the main export:



```javascript

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)

```javascript

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)

```javascript

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)

```javascript

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

```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 = ({ onSelect }) => {

  return (

     {

      const country = getCountryByCode(e.target.value);

      if (country) onSelect(country);

    }}>

      Select a country

      {countries.map((country: Country) => (

        

          {country.emoji} {country.name}

        

      ))}

    

  );

};



// Language selector component

const LanguageSelector: React.FC = () => {

  return (

    

      {languages.map((language: Language) => (

        

          {language.native} ({language.name})

        

      ))}

    

  );

};

```



### Advanced Usage Examples



#### Real-World Example: E-commerce Address Form

```typescript

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 = 'Select Country';

    

    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 = 'Select State';

    

    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

```typescript

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:



```typescript

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.