Overview

A simple yet powerful module to get country, state and city with their interrelated data. Use this tool to create awesome dropdowns for selecting country state sities, or any other purposes you have...

Features

• Beautiful API with Inter-related (Relational) data access
• Highly optimised and faster data reads
• Total 249 Countries, 4,928 States, 1,48,873 Cities
• Geo Locations
• Region and Languages
• Dialcodes
• Lite version API

Getting Started

npm install country-state-city-js@latest

API Methods

• Country()
• State()
• City()
• CountryLite()
• StateLite()
• CityLite()

Usage

Country() and CountryLite()

//ES6
import { Country, CountryLite } from 'country-state-city-js'

//Legacy
const { Country, CountryLite } = require('country-state-city-js')

//1. Get all countries

const countries = Country() or CountryLite()

//Both country and country light methods share same parameters and options

//2. Get all countries with states

const countries = Country({ states:true })

//3. Get all countries with states and cities

const countries = Country({ states:true, cities:true })

//4. Get a country record with ISO2 code

const india = Country('IN')
const unitedStates = Country('US')
const australia = Country('AU')

//5. Get a country record with states

const india = Country('IN', { states:true })

//6. Get a country record with states and cities

const india = Country('IN', { states:true, cities:true })

State() or StateLite()

Note: Country iso2 parameter is mandatory

//ES6
import { State, StateLite } from 'country-state-city-js'

//Legacy
const { State, StateLite } = require('country-state-city-js')

//1. Get all states of a country

const states = State('IN') or StateLite('IN')

//2. Get all states with cities

const states = State('IN', { cities:true })

//3. Get a state of a country

const state = State('IN', 'DL') //Delhi state of India
const state = State('US', 'NY') //New York state of USA

//4. Get a state with cities

const state = Country('IN', 'DL', { cities:true })

City() or CityLite()

Note: Country iso2 and State iso parameter is mandatory

//ES6
import { City, CityLite } from 'country-state-city-js'

//Legacy
const { City, CityLite } = require('country-state-city-js')

//1. Get all cities of a state of country

const cities = City('IN', 'UP') or CityLite('IN', 'UP')
const cities = City('US', 'NY') or CityLite('US', 'NY')

Country Object

{
    "name": "India",
    "native": "भारत",
    "code": "IN",
    "iso": {
    "alpha2": "IN",
    "alpha3": "IND",
    "numeric": "356"
},
"region": {
    "main": "Asia",
    "sub": "Southern Asia",
    "code": "142"
},
"geo": {
    "latitude": "28.6353",
    "longitude": "77.225"
},
    "dialcode": "+91",
    "capital": {
    "name": "New Delhi",
    "latitude": "28.6",
    "longitude": "77.200000"
},
    "currency": {
    "code": "INR",
    "name": "Indian Rupee",
    "symbol": "Rs",
    "native": "₹"
},
"flag": {
    "emoji": "🇮🇳"
},
"tld": ".in",
"languages": [
        "Hindi",
        "Gujarati",
        "Kashmiri",
        "Kannada",
        "Malayalam",
        "Marathi",
        "Nepali",
        "Oriya",
        "Panjabi / Punjabi",
        "Tamil",
        "Telugu",
        "Sindhi",
        "Urdu",
        "Bengali",
        "Sanskrit",
        "Assamese",
        "Maithili",
        "Dogri",
        "Boro",
        "Meitei",
        "Santali",
        "Konkani"
    ]
}

Country Lite Object

{
    "name": "India",
    "code": "IN",
    "dialcode": "+91",
    "currency": "INR",
    "flag": "🇮🇳"
}

State Object

{
    "name": "New York",
    "countryCode": "US",
    "fipsCode": "36",
    "iso": "NY",
    "latitude": "40.71277530",
    "longitude": "-74.00597280"
}

State Lite Object

{
    "name": "New York",
    "iso": "NY"
}

City Object

{
    "name": "Karol Bagh",
    "latitude": "28.65136000",
    "longitude": "77.19072000"
}

Cities Lite Array

[
    "Alipur",
    "Bawana",
    "Central Delhi",
    "Delhi",
    "Deoli",
    "East Delhi",
    "Karol Bagh",
    "Najafgarh",
    "Narela",
    "New Delhi",
    "North Delhi",
    "North East Delhi",
    "North West Delhi",
    "Nangloi Jat",
    "Pitampura",
    "Rohini",
    "South Delhi",
    "South West Delhi",
    "West Delhi"
]

License

MIT

Data Sources

1. Multiple sources from internet

Show your Support

If you like my work, please support and share it to your fellow people.

• Star this repository
• Share my work
• Feel free to fork and experiment, if found any bug or have any suggestion, do let me know.
• Any data related issue? Open an issue

Changelog

Any further major changes will be updated here with version code.

Thank you and have a great time ahead!