india-location-data

A lightweight, offline, zero-dependency Node.js package for Indian States, Districts, and Cities.

Built for developers who need fast and reliable location data without external APIs.

Features

• Complete India States dataset
• Complete India Districts dataset
• Complete India Cities dataset
• Offline JSON data
• Zero dependencies
• Fast in-memory search
• TypeScript support
• ES Modules (ESM)
• Tree-shakeable exports
• Production-ready

Installation

npm install india-location-data

Quick Start

import {
  getStates,
  getDistricts,
  search
} from "india-location-data";

const states = getStates();

const districts = getDistricts("UP");


const results = search("noida");

API Reference

getStates()

Returns all Indian States and Union Territories.

Example

import { getStates } from "india-location-data";

const states = getStates();

Response

[
  {
    code: "UP",
    name: "Uttar Pradesh",
    type: "STATE"
  }
]

getStateByCode(code)

Returns a state by its code.

Example

import { getStateByCode } from "india-location-data";

const state = getStateByCode("UP");

Response

{
  code: "UP",
  name: "Uttar Pradesh",
  type: "STATE"
}

getDistricts(stateCode)

Returns all districts belonging to a state.

Example

import { getDistricts } from "india-location-data";

const districts = getDistricts("UP");

Response

[
  {
    code: "GBN",
    stateCode: "UP",
    name: "Gautam Buddha Nagar"
  }
]

getDistrictByCode(code)

Returns a district by district code.

Example

import { getDistrictByCode } from "india-location-data";

const district = getDistrictByCode("GBN");

search(keyword)

Search across States, Districts.

Example

import { search } from "india-location-data";

const results = search("noida");

Response

[
  {
    type: "city",
    code: "NOIDA",
    name: "Noida",
    state: "Uttar Pradesh",
    district: "Gautam Buddha Nagar"
  }
]

search(keyword, options)

Example

search("uttar", {
  type: "state"
});

search("gautam", {
  type: "district"
});

search("noida", {
  type: "city"
});

Options

| Property | Type | Default | | -------- | ------ | ------- | | limit | number | 20 | | type | string | null |

TypeScript Support

Fully supported.

Example

import {
  getStates,
  State
} from "india-location-data";

const states: State[] = getStates();

Available Types

State
District
City
SearchResult
SearchOptions

Data Structure

State

{
  code: string;
  name: string;
  type: "STATE" | "UT";
}

District

{
  code: string;
  stateCode: string;
  name: string;
}

City

{
  code: string;
  districtCode: string;
  stateCode: string;
  name: string;
}

Performance

The package uses in-memory indexes for fast lookups.

Features include:

• O(1) code-based lookups
• Indexed district retrieval
• Indexed city retrieval
• Optimized search ordering
• No database required
• No network calls

Use Cases

• HRMS Systems
• ERP Platforms
• E-Commerce Applications
• Government Portals
• Logistics Applications
• CRM Systems
• School Management Systems
• Form Builders
• SaaS Platforms

Browser Support

Supported in:

• Node.js 18+
• Node.js 20+
• Node.js 22+
• Modern Browsers
• Vite
• Next.js
• React
• Vue
• Angular

Contributing

Contributions are welcome.

If you find incorrect location data or want to improve the package:

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Open a Pull Request

Roadmap

Version 1.0

• States
• Districts
• Cities
• Search
• TypeScript Support

Version 1.1

• State Search
• District Search
• City Search Enhancements

Version 1.2

• Pincode Lookup
• Reverse Lookup

Version 2.0

• Talukas
• Villages
• Constituencies

License

MIT License

Made with ❤️ for the Indian developer community.