India States and Districts

A lightweight npm package to retrieve all Indian states and their districts.

Installation

npm install india-states-districts

Features

• ✅ Get all 28 Indian states
• ✅ Get districts for any state or union territory
• ✅ Case-insensitive state name search
• ✅ Support for both CommonJS and ESM
• ✅ TypeScript definitions included
• ✅ Zero dependencies

Usage

CommonJS (require)

const { getAllStates, getDistrictsByState, getAllStatesWithDistricts, stateExists } = require('india-states-districts');

// Get all states
const allStates = getAllStates();
console.log(allStates);
// ['Andhra Pradesh', 'Arunachal Pradesh', 'Assam', ...]

// Get districts for a specific state
const districts = getDistrictsByState('Kerala');
console.log(districts);
// ['Alappuzha', 'Ernakulam', 'Idukki', ...]

// Get all states with their districts
const allData = getAllStatesWithDistricts();
console.log(allData);
// [{ name: 'Andhra Pradesh', districts: [...] }, ...]

// Check if a state exists
const exists = stateExists('Tamil Nadu');
console.log(exists);
// true

ESM (import)

import { getAllStates, getDistrictsByState, getAllStatesWithDistricts, stateExists } from 'india-states-districts';

// Get all states
const allStates = getAllStates();
console.log(allStates);

// Get districts for a specific state (case-insensitive)
const districts = getDistrictsByState('karnataka');
console.log(districts);

// Get all states with their districts
const allData = getAllStatesWithDistricts();
console.log(allData);

// Check if a state exists
const exists = stateExists('Kerala');
console.log(exists);

TypeScript

import { getAllStates, getDistrictsByState, stateExists } from 'india-states-districts';

const states: string[] = getAllStates();
const districts: string[] | null = getDistrictsByState('Maharashtra');
const exists: boolean = stateExists('Goa');

API Reference

getAllStates()

Returns an array of all Indian states.

• Returns: string[] - Array of state names

Example:

const states = getAllStates();
// ['Andhra Pradesh', 'Arunachal Pradesh', ..., 'West Bengal']

getDistrictsByState(stateName)

Returns an array of districts for a given state.

• Parameters:
  • stateName (string) - The name of the state
• Returns: string[] | null - Array of district names or null if state not found

Example:

const districts = getDistrictsByState('Kerala');
// ['Alappuzha', 'Ernakulam', 'Idukki', ...]

const notFound = getDistrictsByState('Invalid State');
// null

getAllStatesWithDistricts()

Returns an array of all states with their districts.

• Returns: Array<{name: string, districts: string[]}> - Array of objects containing state name and districts

Example:

const allData = getAllStatesWithDistricts();
// [
//   { name: 'Andhra Pradesh', districts: ['Anantapur', ...] },
//   { name: 'Arunachal Pradesh', districts: ['Anjaw', ...] },
//   ...
// ]

stateExists(stateName)

Checks if a state exists.

• Parameters:
  • stateName (string) - The name of the state
• Returns: boolean - true if state exists, false otherwise

Example:

const exists = stateExists('Tamil Nadu');
// true

const notExists = stateExists('Invalid State');
// false

Notes

• State name searches are case-insensitive
• The package includes all 28 states of India
• All data is loaded once at module initialization for optimal performance
• Invalid inputs (null, undefined, empty string) return appropriate default values

Data Source

The package uses a comprehensive JSON file containing all Indian states and union territories with their respective districts.

License

ISC

Contributing

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