Indian Pincode - Node.js Library

High-performance, offline-first Indian Pincode library for Node.js with zero external dependencies.

🚀 Why Use This Library?

Most developers rely on external APIs for pincode lookups, which are slow, unreliable, and subject to rate limits. Indian Pincode embeds the entire dataset directly into your application with highly optimized indexing.

| Feature | External API | Indian Pincode Library | | :--- | :--- | :--- | | Latency | 200ms - 1000ms (Network dependent) | < 1ms (In-memory) | | Reliability | Can go down, rate limits | 100% Uptime (It's in your code) | | Privacy | Sends user data to 3rd party | Zero Data Leakage (All local) | | Cost | Often paid or freemium | Free & Open Source | | Offline | No | Yes |

📦 Package Size Notice: This library is ~41MB due to the embedded comprehensive database of 19,000+ pincodes and 154,000+ post offices with geospatial data. This library is designed for backend/server-side applications that prioritize 100% uptime, offline capability, and don't want to rely on external APIs. If package size is a critical constraint for your use case, consider using an API-based solution instead.

📦 Installation

npm install @devzoy/indian-pincode

Or with yarn:

yarn add @devzoy/indian-pincode

🔧 Usage

Basic Examples

const pincode = require('@devzoy/indian-pincode');

// 1. Validate a Pincode
console.log(pincode.validate("110001")); 
// Output: true

console.log(pincode.validate("999999")); 
// Output: false

// 2. Lookup Pincode Details
pincode.lookup("110001").then(details => {
    console.log(details[0].office);      // "Connaught Place SO"
    console.log(details[0].district);    // "NEW DELHI"
    console.log(details[0].state);       // "DELHI"
    console.log(details[0].latitude);    // 28.63
    console.log(details[0].longitude);   // 77.21
});

// 3. Find Nearby Post Offices (Geospatial Search)
// Find offices within 5km of coordinates (28.63, 77.21)
pincode.findNearby(28.63, 77.21, 5).then(results => {
    results.forEach(office => {
        console.log(`${office.pincode} - ${office.office} (${office.distance.toFixed(2)}km)`);
    });
});

// 4. Search by District
pincode.searchByDistrict("BANGALORE").then(results => {
    console.log(`Found ${results.length} pincodes in Bangalore`);
    console.log(results[0].pincode);  // "560001"
});

Async/Await Style

const pincode = require('@devzoy/indian-pincode');

async function getPincodeInfo(code) {
    try {
        const details = await pincode.lookup(code);
        if (details.length > 0) {
            console.log(`District: ${details[0].district}`);
            console.log(`State: ${details[0].state}`);
            console.log(`Offices: ${details.map(d => d.office).join(', ')}`);
        }
    } catch (error) {
        console.error('Error:', error);
    }
}

getPincodeInfo("560095");

📚 API Reference

validate(pincode)

Validates if a pincode exists in the database.

Parameters:

• pincode (string): The 6-digit pincode to validate

Returns: boolean

Example:

pincode.validate("110001");  // true
pincode.validate("000000");  // false

lookup(pincode)

Retrieves detailed information for a given pincode.

Parameters:

• pincode (string): The 6-digit pincode to lookup

Returns: Promise<Array> - Array of office objects with the following properties:

• pincode (string): The pincode
• office (string): Post office name
• district (string): District name
• state (string): State name
• latitude (number): Latitude coordinate
• longitude (number): Longitude coordinate

Example:

const details = await pincode.lookup("110001");
console.log(details[0].office);  // "Connaught Place SO"

findNearby(latitude, longitude, radiusKm = 10)

Finds post offices within a specified radius of given coordinates.

Parameters:

• latitude (number): Latitude coordinate
• longitude (number): Longitude coordinate
• radiusKm (number, optional): Search radius in kilometers (default: 10)

Returns: Promise<Array> - Array of nearby offices sorted by distance, each with:

• All properties from lookup()
• distance (number): Distance in kilometers from the search point

Example:

const nearby = await pincode.findNearby(28.63, 77.21, 5);
console.log(`${nearby[0].office} is ${nearby[0].distance.toFixed(2)}km away`);

searchByDistrict(districtName)

Searches for all pincodes in a given district.

Parameters:

• districtName (string): District name (case-insensitive)

Returns: Promise<Array> - Array of all pincodes in the district

Example:

const results = await pincode.searchByDistrict("BANGALORE");
console.log(results.length);  // Number of pincodes in Bangalore

🎯 Use Cases

• E-commerce: Auto-fill address forms, validate delivery locations
• Logistics: Calculate delivery zones, find nearest distribution centers
• Real Estate: Search properties by pincode, show nearby amenities
• Government Apps: Citizen services, location-based schemes
• Analytics: Geographic data analysis, demographic studies

🔍 Data Accuracy

Data is sourced and processed from official India Post records, covering:

• 19,000+ pincodes
• 154,000+ post offices
• All 28 states and 8 union territories
• Accurate latitude/longitude coordinates

⚡ Performance

• Validation: < 0.1ms (instant hash lookup)
• Lookup: < 1ms (lazy-loaded JSON chunks)
• Geospatial Search: < 10ms (optimized distance calculations)
• Memory: ~2MB (compressed data, loaded on-demand)

🛠 Technical Details

Architecture

• Pure JavaScript: Zero external dependencies
• Lazy Loading: Data chunks loaded only when needed
• Optimized Storage: Compressed JSON with prefix-based chunking
• Haversine Formula: Accurate geospatial distance calculations

Data Structure

data/
├── pincodes.compressed.json  # Main index (prefix → chunk mapping)
└── details/                  # Lazy-loaded detail chunks
    ├── 11.json              # All pincodes starting with "11"
    ├── 56.json              # All pincodes starting with "56"
    └── ...

🤝 Contributing

Contributions are welcome! Please see the main repository for contribution guidelines.

📄 License

MIT License - see LICENSE file for details.

🔗 Related Packages

• Python: pip install indian-pincode
• Repository: github.com/devzoy/indian-pincode

📞 Support

• Issues: GitHub Issues
• Email: [email protected]

Made with ❤️ by DevZoy