digipinjs

DigiPIN.js - Indian Postal Code to Coordinates Converter

A comprehensive TypeScript library for encoding and decoding Indian geographic coordinates into DIGIPIN format (Indian Postal Digital PIN system). Features CLI tools, caching, batch processing, and Express middleware for seamless integration.

🚀 Quick Start

# Install the package
npm install digipinjs

# Use the CLI tool
npx digipin-cli encode --lat 28.6139 --lng 77.2090
# Output: 39J-438-TJC7

# Use in your code
import { getDigiPin } from 'digipinjs';
const pin = getDigiPin(28.6139, 77.2090); // Delhi coordinates

📍 What is DIGIPIN?

DIGIPIN (Digital PIN) is India's official postal coordinate encoding system developed by the Department of Posts, Government of India. It converts geographic coordinates (latitude/longitude) into a compact 10-character alphanumeric code, making it easier to identify and locate addresses across the Indian subcontinent.

Key Benefits:

• Compact: 10-character codes instead of long coordinates
• Human-readable: Easy to remember and share
• Official: Government-approved system
• Accurate: High precision for Indian subcontinent
• Standardized: Consistent format across India

🌟 Features

Core DIGIPIN Functions

• ✅ Coordinate to DIGIPIN: Convert lat/lng to 10-character code
• ✅ DIGIPIN to Coordinates: Reverse lookup with high precision
• ✅ Indian Subcontinent Support: Optimized for India (2.5°N-38.5°N, 63.5°E-99.5°E)
• ✅ Validation: Built-in coordinate bounds checking
• ✅ Error Handling: Comprehensive error messages

Enhanced Features

• 🚀 CLI Tool: Command-line interface for quick conversions
• ⚡ Batch Processing: Handle multiple coordinates efficiently
• 💾 Caching: LRU cache for improved performance
• 🌐 Express Middleware: Easy integration with web applications
• 📊 Grid Generation: Create offline coordinate grids
• 🔄 Reverse Geocoding: Convert DIGIPIN back to coordinates
• 📐 Geospatial Utilities: Distance and nearest-point helpers
• 📝 TypeScript Support: Full type definitions included

📦 Installation

# Using npm
npm install digipinjs

# Using yarn
yarn add digipinjs

# Using pnpm
pnpm add digipinjs

🌐 Browser Compatibility

This package is fully compatible with browser environments (React, Vue, Angular, etc.) and Node.js environments.

Browser Usage (React, Vue, Angular, etc.)

// ✅ Works in browsers - no Node.js dependencies
import { getDigiPin, getLatLngFromDigiPin, batchEncode } from 'digipinjs';

const pin = getDigiPin(28.6139, 77.2090); // Delhi coordinates
console.log(pin); // "39J-438-TJC7"

Node.js Usage (Server-side)

// ✅ Full Node.js features including CLI, middleware, and file operations
import { getDigiPin } from 'digipinjs';
import { generateGrid, digiPinMiddleware } from 'digipinjs/node';

// Core functionality
const pin = getDigiPin(28.6139, 77.2090);

// Node.js specific features
generateGrid(20, 70, 30, 80, 0.1, 'grid.json');

Available Exports by Environment

Feature	Browser	Node.js	CLI
Core encoding/decoding	✅	✅	✅
Batch processing	✅	✅	✅
Caching	✅	✅	✅
Express middleware	❌	✅	❌
Grid generation	❌	✅	❌
CLI tools	❌	❌	✅

🛠️ Usage Examples

1. Command Line Interface (CLI)

# Basic encoding (Delhi coordinates)
digipin-cli encode --lat 28.6139 --lng 77.2090
# Output: 39J-438-TJC7

# Basic decoding
digipin-cli decode --pin 39J-438-TJC7
# Output: Latitude: 28.613901°, Longitude: 77.208998°

# Verbose mode with detailed information
digipin-cli encode --lat 28.6139 --lng 77.2090 --verbose

# DMS (Degrees, Minutes, Seconds) format
digipin-cli encode --lat 28.6139 --lng 77.2090 --verbose --format dms

2. Programmatic Usage

Browser Usage (React, Vue, Angular, etc.)

import { 
  getDigiPin, 
  getLatLngFromDigiPin,
  batchEncode,
  batchDecode,
  getCached,
  setCached,
  reverseGeocode 
} from 'digipinjs';

// Basic encoding/decoding
const pin = getDigiPin(28.6139, 77.2090);  // Delhi
console.log(pin); // "39J-438-TJC7"

const coords = getLatLngFromDigiPin(pin);
console.log(coords); // { latitude: 28.6139, longitude: 77.2090 }

// Batch processing for multiple locations
const locations = [
  { lat: 28.6139, lng: 77.2090 },  // Delhi
  { lat: 19.0760, lng: 72.8777 },  // Mumbai
  { lat: 12.9716, lng: 77.5946 }   // Bangalore
];

const pins = batchEncode(locations);
console.log(pins); // ["39J-438-TJC7", "4FK-595-8823", "2L7-3K9-8P2F"]

// Caching for performance
const cachedPin = getCached(28.6139, 77.2090);
if (!cachedPin) {
  const pin = getDigiPin(28.6139, 77.2090);
  setCached(28.6139, 77.2090, pin);
}

Node.js Usage (Server-side)

import { 
  getDigiPin, 
  getLatLngFromDigiPin,
  batchEncode,
  batchDecode,
  getCached,
  setCached,
  reverseGeocode 
} from 'digipinjs';

// Import Node.js specific features
import { digiPinMiddleware, generateGrid } from 'digipinjs/node';

// Basic encoding/decoding (same as browser)
const pin = getDigiPin(28.6139, 77.2090);  // Delhi
console.log(pin); // "39J-438-TJC7"

// Express.js middleware integration
import express from 'express';
const app = express();
app.use(digiPinMiddleware()); // Automatically adds X-DIGIPIN header

// Grid generation for offline use
generateGrid(20, 70, 30, 80, 0.1, 'grid.json');

Reverse Geocoding

import { reverseGeocode } from 'digipinjs';

const location = reverseGeocode('39J-438-TJC7');
console.log(location); // { latitude: 28.6139, longitude: 77.2090 }

Geo Utilities

import {
  getDistance,
  getPreciseDistance,
  orderByDistance,
  findNearest
} from 'digipinjs';

const delhi = '39J-438-TJC7';
const mumbai = '4FK-595-8823';

console.log(getDistance(delhi, mumbai));        // distance in meters
console.log(getPreciseDistance(delhi, mumbai)); // precise distance

const pins = [mumbai, '2L7-3K9-8P2F']; // Mumbai, Bangalore
console.log(orderByDistance(delhi, pins)); // sorted by proximity
console.log(findNearest(delhi, pins));    // nearest pin

3. Common Use Cases

E-commerce & Delivery

// Convert customer address to DIGIPIN for delivery tracking
const customerLocation = getDigiPin(19.0760, 72.8777); // Mumbai
console.log(`Delivery DIGIPIN: ${customerLocation}`);

Real Estate Applications

// Property location encoding
const propertyPin = getDigiPin(12.9716, 77.5946); // Bangalore
console.log(`Property DIGIPIN: ${propertyPin}`);

Emergency Services

// Quick location identification
const emergencyLocation = getDigiPin(28.6139, 77.2090); // Delhi
console.log(`Emergency DIGIPIN: ${emergencyLocation}`);

🗺️ Supported Geographic Region

The library supports the Indian subcontinent with the following coordinate bounds:

• Latitude: 2.5°N to 38.5°N (covers all of India)
• Longitude: 63.5°E to 99.5°E (covers all of India)

This includes:

• 🇮🇳 India (all states and union territories)

📋 DIGIPIN Format Specification

Format: XXX-XXX-XXXX

• Total Length: 10 characters (excluding hyphens)
• Valid Characters: F, C, 9, 8, J, 3, 2, 7, K, 4, 5, 6, L, M, P, T
• Hyphen Positions: After 3rd and 6th characters
• Example: FC9-8J3-27K4

Character Set

The DIGIPIN system uses a 16-character alphabet optimized for Indian postal operations:

• Letters: F, J, K, L, M, P, T
• Numbers: 2, 3, 4, 5, 6, 7, 8, 9
• Special: C

⚠️ Error Handling

The library provides comprehensive error handling with clear messages:

try {
  getDigiPin(100, 200); // Out of bounds
} catch (error) {
  console.error(error.message); // "Latitude out of range"
}

try {
  getLatLngFromDigiPin("INVALID"); // Invalid format
} catch (error) {
  console.error(error.message); // "Invalid DIGIPIN"
}

🔧 Development

# Clone the repository
git clone https://github.com/rajatguptaa/digipinjs.git
cd digipinjs

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Run linter
npm run lint

# Run the example
node examples/full-usage-npm.js
# Geocoding & geo utilities example
node examples/geocode-example.js

📊 Performance

• Encoding Speed: ~10,000 operations/second
• Decoding Speed: ~15,000 operations/second
• Cache Hit Rate: 95%+ for repeated coordinates
• Memory Usage: Minimal with LRU cache (max 10,000 entries)

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

npm install
npm run build
npm test

📄 License

This project is dual-licensed:

• Wrapper Implementation: MIT License (new code)
• Original DIGIPIN: Apache License 2.0 (core algorithm)

See LICENSE file for full details.

🙏 Attribution

This package is based on the original DIGIPIN project developed by:

• Department of Posts, Government of India
• Indian Institute of Technology, Hyderabad
• National Remote Sensing Centre, ISRO

🔗 Related Projects

• DIGIPIN Original - Original implementation
• India Post API - Official postal services
• OpenStreetMap India - Open mapping data

📞 Support

• 🐛 Issues: GitHub Issues
• 📖 Documentation: Full Documentation
• 💬 Discussions: GitHub Discussions

🌟 Star History

---

Made with ❤️ for the Indian developer community

This package helps developers integrate India's official postal coordinate system into their applications with ease and reliability.