digipinpy 1.7.0

Official Python implementation of DIGIPIN - India's national geocoding standard by Department of Posts

🇮🇳 DIGIPIN-Py

Official Python implementation of India's national geocoding standard

Documentation • API Reference • Getting Started • Contributing • Changelog

---

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):

Use Case	Grid Scan	Quadtree	Speedup
Sparse corridor (highway)	2.32s	0.21s	10.86x faster ⚡
Small delivery zones (< 10 km²)	0.002s	0.006s	0.3x
Large areas (> 100 km²)	0.86s	1.00s	0.95x

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

Feature	Description
Encoding/Decoding	Coordinates ↔ DIGIPIN codes
Validation	Check code validity with is_valid()
Batch Operations	Process arrays efficiently
Proximity Search	Find neighbors, rings, disks
Hierarchical Ops	Parent/child relationships
CSV Batch Processing	digipin convert CLI for CSV/Excel files
Interactive Visualization	plot_pins(), plot_coverage() with Folium
Pandas Integration	.digipin accessor for DataFrames
Django Integration	DigipinField() with auto-validation
FastAPI Integration	Pre-built REST API router
Geospatial Polyfill	Convert polygons to code sets

---

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 📧 [e-mail] • [e-mail]

📦 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).

---

Government of India | Department of Posts | National Addressing Initiative