What is DIGIPIN?

DIGIPIN (Digital Postal Index Number) is India's national geocoding system developed by the Department of Posts, Ministry of Communications, Government of India. It divides the entire country into a hierarchical grid, assigning a unique code to every ~4m × 4m location.

digipinpy is a high-performance, zero-dependency Python library implementing the official specification with 100% compliance.

Key Features

• 🎯 Pinpoint Accuracy - ~3.8m precision at level 10
• 🗺️ Hierarchical Grid - Variable precision from 1000km down to 4m
• 📦 Zero Dependencies - Pure Python core, optional framework integrations
• ⚡ High Performance - ~50,000 encodes/second, optimized quadtree polyfill (10x faster for corridors)
• 🔌 Framework Ready - Native Pandas, Django, FastAPI & geospatial support
• 📊 CSV Batch Processing - CLI tool for processing thousands of addresses
• 🗺️ Interactive Visualization - Beautiful maps with Folium integration

Installation

pip install digipinpy

Optional integrations:

pip install digipinpy[pandas]    # Data science & CSV processing
pip install digipinpy[django]    # Django database field
pip install digipinpy[fastapi]   # FastAPI microservices
pip install digipinpy[geo]       # Geospatial polyfill
pip install digipinpy[viz]       # Interactive map visualization

Quick Start

Basic Usage

from digipin import encode, decode

# Encode coordinates to DIGIPIN
code = encode(28.622788, 77.213033)  # Dak Bhawan, New Delhi
print(code)  # '39J49LL8T4'

# Decode back to coordinates
lat, lon = decode('39J49LL8T4')
print(f"{lat:.6f}, {lon:.6f}")  # 28.622788, 77.213033

Variable Precision

# Encode with different precision levels
code_full = encode(28.622788, 77.213033, precision=10)  # ~3.8m
code_city = encode(28.622788, 77.213033, precision=5)   # ~1km
code_region = encode(28.622788, 77.213033, precision=3) # ~16km

Proximity Search

from digipin import get_neighbors, get_disk

# Get 8 immediate neighbors
neighbors = get_neighbors('39J49LL8T4')

# Get all cells within radius 3
search_area = get_disk('39J49LL8T4', radius=3)

Polygon Coverage (NEW in v1.6.1)

from digipin import polyfill

# Convert polygon to DIGIPIN codes
polygon = [(28.63, 77.22), (28.62, 77.21), (28.62, 77.23)]
codes = polyfill(polygon, precision=8)

# Choose algorithm (quadtree is default)
codes = polyfill(polygon, precision=8, algorithm="quadtree")  # Fast for sparse/large areas
codes = polyfill(polygon, precision=8, algorithm="grid")      # Fast for small dense zones

⚡ Performance

v1.6.1 introduces optimized quadtree algorithm achieving O(Perimeter) complexity instead of O(Area):

Key Findings:

• ✅ Quadtree excels at sparse polygons (highways, rivers, corridors) - up to 10x faster
• ✅ Grid scan wins for small dense areas (typical delivery zones)
• ✅ Both complete in < 50ms for 80% of use cases
• ✅ Algorithm selection is automatic (configurable via algorithm parameter)

Documentation

📚 User Guides

• Getting Started - Installation and first steps
• API Reference - Complete function reference
• Use Cases - Real-world examples

🔌 Integrations

• Pandas Integration - DataFrame operations
• Django Integration - Database field with validation
• FastAPI Integration - REST API microservices
• Geospatial Polyfill - Polygon-to-codes conversion

🛠️ Development

• Contributing Guide - How to contribute
• Changelog - Version history
• Technical Specification - Official DIGIPIN spec

Features at a Glance

Project Status

• ✅ Production Ready - Version 1.6.1
• ✅ 100% Spec Compliant - Official DoP specification
• ✅ 178 Tests Passing - Comprehensive test coverage
• ✅ Type Hints - Full type annotation support
• ✅ Multi-Platform - Windows, macOS, Linux
• ✅ Python 3.7-3.14 - Wide version support

Contributing

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

Quick setup:

git clone https://github.com/DEADSERPENT/digipin.git
cd digipin
pip install -e ".[dev]"
pytest tests/ -v

License

MIT License - see LICENSE file for details.

Community & Support

Maintained by: SAMARTHA H V • MR SHIVAKUMAR 📧 samarthsmg14@gmail.com • hmrshivu@gmail.com

📦 PyPI • 🐛 Issues • 💬 Discussions • 📖 Changelog

This implementation is based on the official DIGIPIN specification published by the Department of Posts, Ministry of Communications, Government of India (March 2025).