countries-states-cities-db

A lightweight TypeScript/JavaScript library providing a comprehensive database of Countries, States, and Cities — with coordinates, phone codes, currencies, flags, and timezones.

Installation

npm install countries-states-cities-db

Usage

ES Module (recommended)

import { Country, State, City } from 'countries-states-cities-db';

CommonJS

const { Country, State, City } = require('countries-states-cities-db');

TypeScript Interfaces

import { ICountry, IState, ICity } from 'countries-states-cities-db';

API Reference

Country

Country.getAllCountries()

Returns all countries.

Country.getAllCountries(): ICountry[]

[
  {
    "isoCode": "IN",
    "name": "India",
    "phonecode": "91",
    "flag": "🇮🇳",
    "currency": "INR",
    "latitude": "20.00000000",
    "longitude": "77.00000000",
    "timezones": [
      {
        "zoneName": "Asia/Kolkata",
        "gmtOffset": 19800,
        "gmtOffsetName": "UTC+05:30",
        "abbreviation": "IST",
        "tzName": "Indian Standard Time"
      }
    ]
  }
]

Country.getCountryByCode(isoCode)

Returns a single country matching the given ISO code.

Country.getCountryByCode(isoCode: string): ICountry | undefined

Country.getCountryByCode('IN')
// { isoCode: 'IN', name: 'India', phonecode: '91', flag: '🇮🇳', ... }

State

State.getAllStates()

Returns all states across all countries.

State.getAllStates(): IState[]

State.getStatesOfCountry(countryCode)

Returns all states belonging to a country.

State.getStatesOfCountry(countryCode: string): IState[]

State.getStatesOfCountry('IN')

[
  {
    "name": "Delhi",
    "isoCode": "DL",
    "countryCode": "IN",
    "latitude": "28.70405920",
    "longitude": "77.10249020"
  }
]

State.getStateByCodeAndCountry(stateCode, countryCode)

Returns a single state matching both the state ISO code and country code.

State.getStateByCodeAndCountry(stateCode: string, countryCode: string): IState | undefined

State.getStateByCodeAndCountry('TG', 'IN')

{
  "name": "Telangana",
  "isoCode": "TG",
  "countryCode": "IN",
  "latitude": "18.11243720",
  "longitude": "79.01929970"
}

City

City.getAllCities()

Returns all cities across all countries.

City.getAllCities(): ICity[]

City.getCitiesOfState(countryCode, stateCode)

Returns all cities belonging to a specific state within a country.

City.getCitiesOfState(countryCode: string, stateCode: string): ICity[]

City.getCitiesOfState('IN', 'DL')

[
  {
    "name": "New Delhi",
    "countryCode": "IN",
    "stateCode": "DL",
    "latitude": "28.63576000",
    "longitude": "77.22445000"
  }
]

City.getCitiesOfCountry(countryCode)

Returns all cities belonging to a country.

City.getCitiesOfCountry(countryCode: string): ICity[] | undefined

City.getCitiesOfCountry('IN')

Interfaces

interface ICountry {
  name: string;
  isoCode: string;
  phonecode: string;
  flag: string;
  currency: string;
  latitude: string;
  longitude: string;
  timezones?: {
    zoneName: string;
    gmtOffset: number;
    gmtOffsetName: string;
    abbreviation: string;
    tzName: string;
  }[];
}

interface IState {
  name: string;
  isoCode: string;
  countryCode: string;
  latitude?: string | null;
  longitude?: string | null;
}

interface ICity {
  name: string;
  countryCode: string;
  stateCode: string;
  latitude?: string | null;
  longitude?: string | null;
}

Data Structure

The data/ folder in the root contains all raw data split into per-country and per-state files for easy review and contribution:

data/
└── India-IN/
    ├── allStates.lite.json
    ├── allStates.geo.json
    └── Delhi-DL/
        ├── allCities.lite.json
        └── allCities.geo.json

• Each country folder contains state info split into lite and geo variants.
• Each state sub-folder contains city info split into lite and geo variants.
• This structure makes it easy to review, debug, and submit data changes.

The src/assets/ folder holds the combined, minified JSON files consumed by the library:

| File | Description | |------|-------------| | country.json | All countries with metadata | | state.json | All states with country codes | | city.json | All cities (array-of-arrays format, ~8MB minified) |

city.json uses an array-of-arrays format instead of array-of-objects to reduce file size from ~25MB to ~8MB.

Contributing

Code changes

Make your change and raise a PR.

Data changes

The database lives in the data/ folder. Follow the data update guide before submitting.

• Update — edit the relevant file(s) with proper structure and raise a PR.
• Add — follow the folder structure and raise a PR, or share the JSON in an issue.
• Delete — remove the relevant files/folders, update dependent files, and raise a PR.
• Wrong data — queries must include a reference source.
• Geo-political disputes — updated only when multiple valid references are provided.

License

GPL-3.0