postalcodes-india

A lightweight and efficient Indian postal code lookup library with no external dependencies. Compatible with both Node.js and browser/React environments.

I try my best to monitor the required dependencies daily and publish updates to the npm package whenever changes are detected.

🔄 Data Last Checked/Updated: 30th April 2025

Features

• Fast in-memory postal code lookups
• Multiple lookup methods for different use cases
• Find postal codes by place, state, and district
• Find postal codes within a radius of coordinates
• Returns complete information including state, district, sub-district, and coordinates
• TypeScript support with full type definitions
• Zero runtime dependencies
• Universal compatibility: Works in Node.js, browsers, and React applications
• Tree-shakable: Import only what you need

Installation

1npm install postalcodes-india

Usage

In Node.js (ESM)

1import postalcodes from "postalcodes-india"
2
3// Complete lookup with validity check
4const info = postalcodes.find("560029")
5console.log(info)

In Node.js (CommonJS)

1const postalcodes = require("postalcodes-india")
2
3// Complete lookup with validity check
4const info = postalcodes.find("560029")
5console.log(info)

In React

1import React, { useState } from "react"
2import postalcodes from "postalcodes-india"
3
4function PostalCodeLookup() {
5  const [code, setCode] = useState("")
6  const [result, setResult] = useState(null)
7
8  const handleLookup = () => {
9    const info = postalcodes.find(code)
10    setResult(info)
11  }
12
13  return (
14    <div>
15      <h2>Postal Code Lookup</h2>
16      <input type="text" value={code} onChange={(e) => setCode(e.target.value)} placeholder="Enter postal code" />
17      <button onClick={handleLookup}>Lookup</button>
18
19      {result && (
20        <div>
21          <h3>Results:</h3>
22          {result.isValid ? (
23            <ul>
24              <li>State: {result.state}</li>
25              <li>District: {result.district}</li>
26              <li>Sub-District: {result.subDistrict}</li>
27              <li>Place: {result.place}</li>
28              <li>
29                Coordinates: {result.latitude}, {result.longitude}
30              </li>
31            </ul>
32          ) : (
33            <p>Invalid postal code</p>
34          )}
35        </div>
36      )}
37    </div>
38  )
39}
40
41export default PostalCodeLookup

In Browser (via CDN)

1<script src="https://cdn.jsdelivr.net/npm/postalcodes-india/dist/index.umd.js"></script>
2<script>
3  // The library is available as a global variable 'postalcodes'
4  const info = postalcodes.find("110001")
5  console.log(info)
6</script>

Tree-shaking (Import only what you need)

1import { find, findByRadius } from "postalcodes-india"
2
3// Use specific functions without importing the entire library
4const info = find("400001")
5const nearby = findByRadius(19.076, 72.8777, 5) // 5km radius around Mumbai

Examples

1import postalcodes from "postalcodes-india"
2
3// Complete lookup with validity check
4const info = postalcodes.find("744301")
5console.log(info)
6/* Output:
7{
8  state: 'Andaman & Nicobar Islands',
9  stateCode: '01',
10  district: 'Nicobar',
11  subDistrict: 'Carnicobar',
12  place: 'Sawai',
13  latitude: 7.5166,
14  longitude: 93.6031,
15  isValid: true
16}
17*/
18
19// For invalid postal codes, returns empty values with isValid: false
20const invalid = postalcodes.find("000000")
21console.log(invalid)
22/* Output:
23{
24  state: '',
25  stateCode: '',
26  district: '',
27  subDistrict: '',
28  place: '',
29  latitude: 0,
30  longitude: 0,
31  isValid: false
32}
33*/
34
35// Get just the state information
36const stateInfo = postalcodes.findState("744301")
37console.log(stateInfo) // { state: 'Andaman & Nicobar Islands', stateCode: '01', isValid: true }
38
39// Get just the district information
40const districtInfo = postalcodes.findDistrict("744301")
41console.log(districtInfo) // { district: 'Nicobar', districtCode: '638', state: 'Andaman & Nicobar Islands', stateCode: '01', isValid: true }
42
43// Get just the place
44const placeInfo = postalcodes.findPlace("744301")
45console.log(placeInfo) // { place: 'Sawai', isValid: true }
46
47// Get just the coordinates
48const coords = postalcodes.findCoordinates("744301")
49console.log(coords) // { latitude: 7.5166, longitude: 93.6031, isValid: true }
50
51// Get complete location hierarchy
52const hierarchy = postalcodes.findHierarchy("744301")
53console.log(hierarchy)
54/* Output:
55{
56  state: 'Andaman & Nicobar Islands',
57  stateCode: '01',
58  district: 'Nicobar',
59  districtCode: '638',
60  subDistrict: 'Carnicobar',
61  place: 'Sawai',
62  isValid: true
63}
64*/
65
66// Find postal codes for a place and state
67const placePostals = postalcodes.findByPlace("Sawai", "01")
68console.log(`Found ${placePostals.length} postal codes`)
69
70// Find postal codes in a district
71const districtPostals = postalcodes.findByDistrict("Nicobar", "01")
72console.log(`Nicobar district has ${districtPostals.length} postal codes`)
73
74// Find postal codes within 10 kilometers of coordinates
75const nearby = postalcodes.findByRadius(7.5166, 93.6031, 10)
76console.log(`Found ${nearby.length} postal codes within 10km radius`)
77
78// Get all states
79const states = postalcodes.getStates()
80console.log(`India has ${states.length} states and union territories with postal codes`)

API

find(postalCode: string): PostalLookupResult

Returns complete information for a postal code with an isValid flag. Always returns an object, even for invalid postal codes.

1interface PostalLookupResult {
2  state: string // Full state/UT name
3  stateCode: string // State code
4  district: string // District name
5  subDistrict: string // Sub-district/tehsil name
6  place: string // Place name
7  latitude: number // Decimal latitude
8  longitude: number // Decimal longitude
9  isValid: boolean // Whether the postal code exists
10}
11
12// Internal PostalCodeInfo interface used by findByPlace, findByDistrict, and findByRadius methods
13interface PostalCodeInfo {
14  postalCode: string // 6-digit postal code
15  placeName: string // Place name
16  stateName: string // Full state/UT name
17  stateCode: string // State code
18  districtName: string // District name
19  districtCode: string // District code
20  subDistrictName: string // Sub-district name
21  latitude: number // Latitude in decimal degrees
22  longitude: number // Longitude in decimal degrees
23}

findState(postalCode: string): StateResult

Returns state information for a postal code with validity check.

1interface StateResult {
2  state: string // Full state/UT name
3  stateCode: string // State code
4  isValid: boolean // Whether the postal code exists
5}

findDistrict(postalCode: string): DistrictResult

Returns district information for a postal code with validity check.

1interface DistrictResult {
2  district: string // District name
3  districtCode: string // District code
4  state: string // State name
5  stateCode: string // State code
6  isValid: boolean // Whether the postal code exists
7}

findPlace(postalCode: string): { place: string; isValid: boolean }

Returns place name for a postal code with validity check.

findCoordinates(postalCode: string): Coordinates

Returns latitude and longitude for a postal code with validity check.

1interface Coordinates {
2  latitude: number // Decimal latitude
3  longitude: number // Decimal longitude
4  isValid: boolean // Whether the postal code exists
5}

findHierarchy(postalCode: string): LocationHierarchy

Returns complete location hierarchy for a postal code.

1interface LocationHierarchy {
2  state: string // State name
3  stateCode: string // State code
4  district: string // District name
5  districtCode: string // District code
6  subDistrict: string // Sub-district name
7  place: string // Place name
8  isValid: boolean // Whether the postal code exists
9}

findByPlace(place: string, stateCode: string): PostalCodeInfo[]

Finds all postal codes for a given place and state. Returns an array of PostalCodeInfo objects.

findByDistrict(districtName: string, stateCode: string): PostalCodeInfo[]

Finds all postal codes in a given district. Returns an array of PostalCodeInfo objects.

findByRadius(latitude: number, longitude: number, radiusKm: number): PostalCodeInfo[]

Finds postal codes within a radius of coordinates, sorted by distance. Returns an array of PostalCodeInfo objects.

getStates(): Array<{ code: string, name: string }>

Returns all states and union territories with their codes and names.

Data Source

This package uses GeoNames postal code data (under Creative Commons Attribution 4.0 License).

License

MIT