India Pincode Finder

A Node.js module that helps you find detailed Indian address information by using a valid 6-digit PIN code. It's ideal for use in logistics, address validation, fintech onboarding (KYC), e-commerce, and mapping services.

Installation

npm install india-pincode-finder

Usage

// CommonJS
const { 
  pinToAddress, 
  pinToState, 
  pinToDistrict, 
  pinToTaluka,
  searchPincodes
} = require('india-pincode-finder');

// ES Modules
import { 
  pinToAddress, 
  pinToState, 
  pinToDistrict, 
  pinToTaluka,
  searchPincodes
} from 'india-pincode-finder';

// Get the full address details for a pincode
console.log(pinToAddress(411001));
// Output: { district: 'Pune', block: 'Pune City', state: 'Maharashtra' }

// Get the state for a pincode
console.log(pinToState(411001));
// Output: 'Maharashtra'

// Get the district for a pincode
console.log(pinToDistrict(411001));
// Output: 'Pune'

// Get the taluka/block for a pincode
console.log(pinToTaluka(411001));
// Output: 'Pune City'

// Search pincodes by district, block, or office name (case-insensitive substring match)
console.log(searchPincodes('pune'));
// [{ pincode: 410301, state: '...', district: '...', ... }, ...]

console.log(searchPincodes('pune h.o'));
// includes full address object for 411001

API

pinToAddress(pincode: number): object | null

Get full address details for a pincode.

• pincode: 6-digit PIN code (number)
• Throws: Error if the pincode is not a valid 6-digit number.
• Returns:
  • object: An object like { district: string; block: string; state: string; } if found.
  • null: If no data is found for the given pincode.

pinToState(pincode: number): string | null

Get state for a pincode.

• pincode: 6-digit PIN code (number)
• Throws: Error if the pincode is not a valid 6-digit number.
• Returns:
  • string: The name of the state if found.
  • null: If no data is found for the given pincode.

pinToDistrict(pincode: number): string | null

Get district for a pincode.

• pincode: 6-digit PIN code (number)
• Throws: Error if the pincode is not a valid 6-digit number.
• Returns:
  • string: The name of the district if found.
  • null: If no data is found for the given pincode.

pinToTaluka(pincode: number): string | null

Get taluka/block for a pincode.

• pincode: 6-digit PIN code (number)
• Throws: Error if the pincode is not a valid 6-digit number.
• Returns:
  • string: The name of the taluka/block if found.
  • null: If no data is found for the given pincode.

searchPincodes(name: string): PincodeSearchResult[]

Search district, block, and officename for a case-insensitive substring match.

• name: Search query string
• Returns:
  • PincodeSearchResult[]: Full address objects with pincode included, sorted ascending by pincode
  • []: If the query is empty/whitespace or no matches are found

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

For commercial use without GPL compliance, please contact the authors for licensing options.