pak-geodata

Comprehensive, typed, offline geographic data for all areas and cities in Pakistan.

pak-geodata is an open-source, production-grade Python client library providing offline access to verified geographic data for Pakistan.

It covers all administrative provinces, 79 major and secondary cities, and foundational flagship metropolitan areas (sectors, housing schemes, neighborhoods, and commercial centers).

Designed with zero runtime dependencies (pure Python standard library), strict geofencing, and sub-millisecond lookups.

Features

• Zero Runtime Dependencies: Powered entirely by the Python standard library (dataclasses, json, math, re, pathlib).
• Offline & Self-Contained: All verified golden datasets are bundled with the library: no remote API calls or internet access required.
• Strict Geofencing & Validation: Every coordinate is rigorously validated within Pakistan territorial boundaries (23.5 <= lat <= 37.1, 60.8 <= lng <= 77.8) and city district bounding boxes.
• Canonical Slugs: Standardized <city-slug>-<area-slug> identifiers across all datasets (e.g. lahore-dha-phase-5).
• Multi-Script & Alias Search: Full support for English queries, colloquial aliases (e.g. "dha 5"), Urdu script queries (e.g. "کلفٹن"), and fuzzy typo tolerance.
• Spatial Nearest Neighbor: Instant reverse geocoding via spherical Haversine distance calculations.
• Postal Code Resolution: 5-digit Pakistan Post postal code lookup and reverse mapping.
• Fully Typed & PEP 561 Compliant: Includes py.typed marker and immutable frozen dataclasses for full IDE auto-completion.

Dataset Statistics

Installation

pip install pak-geodata

Quick Start

1. Provinces & Cities

from pak_geodata import (
    get_all_provinces,
    get_province_by_id,
    get_all_cities,
    get_cities_by_province,
    get_city_by_id,
)

# List all 7 provinces and federal territories
provinces = get_all_provinces()
for p in provinces:
    print(f"{p.name} ({p.urdu_name}) - Capital: {p.capital_city_id}")

# Find a province by ID
punjab = get_province_by_id("punjab")
print(punjab.name)  # "Punjab"

# Retrieve all cities in a province
punjab_cities = get_cities_by_province("punjab")
print(f"Found {len(punjab_cities)} cities in Punjab")

# Get specific city details
lahore = get_city_by_id("lahore")
print(f"{lahore.name} coordinates: {lahore.coordinates.lat}, {lahore.coordinates.lng}")
print(f"Verified areas count: {lahore.total_areas_count}")

2. Areas by City

from pak_geodata import get_areas_by_city

# Retrieve all verified areas for a city
lahore_areas = get_areas_by_city("lahore")
for area in lahore_areas[:5]:
    print(f"{area.name} [{area.id}] - Postal Code: {area.postal_code}")

3. Intelligent Search

The search engine ranks results across multiple matching tiers:

1. Exact match on name, id, Urdu name, or alias
2. Prefix match
3. Substring / multi-word token match
4. Fuzzy edit-distance fallback for typos

from pak_geodata import search_areas

# Search by colloquial alias scoped to a city
results = search_areas("dha 5", city_id="lahore")
print(results[0].id)    # "lahore-dha-phase-5"
print(results[0].name)  # "DHA Phase 5"

# Search using Urdu script
results = search_areas("کلفٹن")
for r in results:
    print(f"{r.name} ({r.urdu_name}) in {r.city_id}")

# Scoped city search with limit
results = search_areas("phase", city_id="islamabad", limit=3)

4. Reverse Geocoding & Spatial Nearest Neighbor

Find the closest verified neighborhood or society to given GPS coordinates:

from pak_geodata import Coordinates, get_nearest_area, haversine_distance_km

# Distance calculation
lahore_lat, lahore_lng = 31.5204, 74.3587
rawalpindi_lat, rawalpindi_lng = 33.5651, 73.0169
distance_km = haversine_distance_km(lahore_lat, lahore_lng, rawalpindi_lat, rawalpindi_lng)
print(f"Distance: {distance_km:.2f} km")

# Nearest area from coordinates (or Coordinates object)
coords = Coordinates(lat=31.4581, lng=74.4121)
nearest = get_nearest_area(coords)
print(f"Nearest area: {nearest.name} ({nearest.id})")

# Filtered nearest search with maximum distance threshold
area_within_5km = get_nearest_area(
    lat=33.5651,
    lng=73.0169,
    city_id="rawalpindi",
    max_distance_km=5.0
)

5. Postal Code Resolution

from pak_geodata import find_area_by_postal_code, find_areas_by_postal_code

# Find primary area by 5-digit postal code
area = find_area_by_postal_code("54792")
print(area.name)  # "DHA Phase 1"

# Find all areas sharing a postal code
all_dha = find_areas_by_postal_code("54792")
print(f"{len(all_dha)} areas share postal code 54792")

📖 Implementation Recipes: For real-world architectural recipes, localized reporting workflows, and offline database synchronization patterns, see the Recipes Directory.

Data Models

All models are immutable frozen dataclasses (@dataclass(frozen=True)):

Coordinates

PakistanProvince

PakistanCity

PakistanArea

API Reference

About The Mohsin Project

Free software for those who do good.

pak-geodata is an open-source public good engineered and maintained by The Mohsin Project.

The Mohsin Project exists because purpose-driven organizations and emergency teams lose momentum to outdated systems, expensive proprietary APIs, and scarce technical resources. We design, engineer, and deploy centralized digital solutions entirely free of cost so that nonprofits, humanitarian initiatives, and civic developers can focus on their mission.

• 💬 Get in Touch: hello@themohsinproject.org

License

This project is open-source software licensed under the MIT License.

Copyright (c) 2026 The Mohsin Project Global