pak-geodata 0.8.1 → 0.9.1

package/README.md

@@ -1,10 +1,16 @@
 # pak-geodata
 
+[![NPM Version](https://img.shields.io/npm/v/pak-geodata?color=blue)](https://www.npmjs.com/package/pak-geodata)
+<a href="https://geodata.themohsinproject.org/" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/badge/Live%20Demo-Interactive%20Studio-blue?logo=leaflet&color=10B981" alt="Live Interactive Demo" /></a>
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 > Comprehensive, typed, offline geographic data for all areas and cities in Pakistan.
 
+Explore the [Live Interactive Demo](https://geodata.themohsinproject.org/) to test multi-script search, interactive map exploration, and reverse geocoding in real-time.
+
 `pak-geodata` is an open-source, production-grade TypeScript and JavaScript client library providing offline access to verified geographic data for Pakistan.
 
-It covers all administrative provinces, all 79 major and secondary cities (100% national urban coverage), and 1,279 foundational metropolitan and regional areas across all 79 cities.
+It covers all administrative provinces, all 79 major and secondary cities (100% national urban coverage), and 3,953 foundational metropolitan and regional areas across all 79 cities.
 
 Designed with **zero runtime dependencies**, strict geofencing, sub-millisecond lookups, and modular tree-shakeable subpath exports.
 
@@ -91,7 +97,7 @@ for (const area of lahoreAreas.slice(0, 5)) {
 
 // Total verified areas in Pakistan
 const allAreas = getAllAreas();
-console.log(`Total verified areas: ${allAreas.length}`); // 1279
+console.log(`Total verified areas: ${allAreas.length}`); // 3953
 ```
 
 ### 3. Modular Subpath Imports (Tree-Shaking)
@@ -278,10 +284,17 @@ interface PakistanArea {
     lat: number;                 // Latitude (WGS 84)
     lng: number;                 // Longitude (WGS 84)
   };
+  bounds?: {
+    minLat: number;
+    maxLat: number;
+    minLng: number;
+    maxLng: number;
+  };
+  radiusKm?: number;             // Approximate radial span from centroid in km
   postalCode?: string;           // 5-digit Pakistan Post postal code
   type?: 'neighborhood' | 'sector' | 'commercial' | 'housing_scheme' | 'suburb' | 'industrial' | 'administrative';
   verified: boolean;             // True if verified via triangulation pipeline
-  sources: string[];             // Verification sources (e.g. "survey", "curated", "osm")
+  sources?: (string | ProvenanceSource)[]; // Structured or string provenance sources
 }
 ```
 
@@ -322,6 +335,28 @@ interface PakistanProvince {
 
 ---
 
+## Data Sources & Upstream Attribution
+
+`pak-geodata` integrates cross-verified GIS records from:
+- **National Geospatial-Intelligence Agency (NGA) & GeoNames**: Populated places and urban quarters (`PPLX`) ([CC-BY 4.0](https://creativecommons.org/licenses/by/4.0/)).
+- **OpenStreetMap Contributors**: Verified metropolitan neighborhood and arterial coordinates ([ODbL 1.0](https://opendatacommons.org/licenses/odbl/1.0/)).
+- **UN OCHA / HDX COD**: Administrative Common Operational Datasets for Pakistan boundaries ([CC-BY-IGO](https://creativecommons.org/licenses/by/3.0/igo/)).
+- **Pakistan Post & PBS**: Postal codes and administrative hierarchies.
+
+See [ATTRIBUTION.md](ATTRIBUTION.md) for full attribution notices.
+
+---
+
+## Licensing & Commercial Use FAQ
+
+- **Library & Code**: [MIT License](LICENSE)
+- **Geographic Datasets**: [ODbL 1.0](LICENSE-DATA) & [CC-BY 4.0](LICENSE-DATA)
+
+### Commercial Use in Web & Mobile Apps
+Under **Section 4.3 of the Open Database License (ODbL)**, displaying Pakistani cities, autocomplete menus, checkout address pickers, or geocoding outputs within your application constitutes a **"Produced Work"**. Using `pak-geodata` in your website or mobile app does **NOT** require you to open-source your proprietary code, backend services, or customer database. Simply include an attribution notice in your application's credits.
+
+---
+
 ## About The Mohsin Project
 
 > **Free software for those who do good.**
@@ -336,6 +371,6 @@ The Mohsin Project exists because purpose-driven organizations and emergency tea
 
 ## License
 
-This project is open-source software licensed under the [MIT License](LICENSE).
+- **Code**: [MIT License](LICENSE) © 2026 [The Mohsin Project Global](https://themohsinproject.org)
+- **Data**: [ODbL 1.0](LICENSE-DATA) & [CC-BY 4.0](LICENSE-DATA) © OpenStreetMap contributors & NGA/GeoNames
 
-Copyright (c) 2026 [The Mohsin Project Global](https://themohsinproject.org)

package/dist/areas/attock.cjs

@@ -113,7 +113,13 @@ var attockAreas = [
     "verified": true,
     "sources": [
       "survey",
-      "curated"
+      "curated",
+      {
+        "provider": "nga_geonames",
+        "id": 1184249,
+        "featureCode": "PPLA2",
+        "datasetVersion": "2026-11"
+      }
     ]
   },
   {
@@ -203,6 +209,27 @@ var attockAreas = [
       "survey",
       "curated"
     ]
+  },
+  {
+    "id": "attock-mahalla-karbia",
+    "cityId": "attock",
+    "provinceId": "punjab",
+    "name": "Mahalla Karbia",
+    "aliases": [],
+    "coordinates": {
+      "lat": 33.76489,
+      "lng": 72.35606
+    },
+    "type": "neighborhood",
+    "verified": true,
+    "sources": [
+      {
+        "provider": "nga_geonames",
+        "id": 11412139,
+        "featureCode": "PPLX",
+        "datasetVersion": "2026-11"
+      }
+    ]
   }
 ];
 // Annotate the CommonJS export names for ESM import in node:

package/dist/areas/bahawalnagar.cjs

@@ -41,7 +41,13 @@ var bahawalnagarAreas = [
     "cityId": "bahawalnagar",
     "sources": [
       "survey",
-      "curated"
+      "curated",
+      {
+        "provider": "nga_geonames",
+        "id": 1183883,
+        "featureCode": "PPLA2",
+        "datasetVersion": "2026-11"
+      }
     ],
     "verified": true,
     "provinceId": "punjab",
@@ -194,6 +200,27 @@ var bahawalnagarAreas = [
     "provinceId": "punjab",
     "urduName": "\u063A\u0644\u06C1 \u0645\u0646\u0688\u06CC",
     "type": "commercial"
+  },
+  {
+    "id": "bahawalnagar-bihari-colony",
+    "cityId": "bahawalnagar",
+    "provinceId": "punjab",
+    "name": "Bihari Colony",
+    "aliases": [],
+    "coordinates": {
+      "lat": 29.97753,
+      "lng": 73.2584
+    },
+    "type": "neighborhood",
+    "verified": true,
+    "sources": [
+      {
+        "provider": "nga_geonames",
+        "id": 11972101,
+        "featureCode": "PPLX",
+        "datasetVersion": "2026-11"
+      }
+    ]
   }
 ];
 // Annotate the CommonJS export names for ESM import in node:

package/dist/areas/bahawalpur.cjs

@@ -409,6 +409,164 @@ var bahawalpurAreas = [
       "survey",
       "curated"
     ]
+  },
+  {
+    "id": "bahawalpur-hamaitian",
+    "cityId": "bahawalpur",
+    "provinceId": "punjab",
+    "name": "Hamaitian",
+    "aliases": [
+      "Basti Hamatian",
+      "Basti Ham\u0101ti\u0101n",
+      "Hamaitjan",
+      "H\u0101maitj\u0101n"
+    ],
+    "coordinates": {
+      "lat": 29.3832,
+      "lng": 71.72227
+    },
+    "type": "neighborhood",
+    "verified": true,
+    "sources": [
+      {
+        "provider": "nga_geonames",
+        "id": 1381874,
+        "featureCode": "PPLX",
+        "datasetVersion": "2026-11"
+      }
+    ],
+    "postalCode": "63100"
+  },
+  {
+    "id": "bahawalpur-sadiq-colony",
+    "cityId": "bahawalpur",
+    "provinceId": "punjab",
+    "name": "Sadiq Colony",
+    "aliases": [],
+    "coordinates": {
+      "lat": 29.38153,
+      "lng": 71.66127
+    },
+    "type": "neighborhood",
+    "verified": true,
+    "sources": [
+      {
+        "provider": "nga_geonames",
+        "id": 7391887,
+        "featureCode": "PPLX",
+        "datasetVersion": "2026-11"
+      }
+    ],
+    "postalCode": "63100"
+  },
+  {
+    "id": "bahawalpur-gulzar-mahal",
+    "cityId": "bahawalpur",
+    "provinceId": "punjab",
+    "name": "Gulzar Mahal",
+    "aliases": [],
+    "coordinates": {
+      "lat": 29.39745,
+      "lng": 71.69788
+    },
+    "type": "neighborhood",
+    "verified": true,
+    "sources": [
+      {
+        "provider": "nga_geonames",
+        "id": 7391964,
+        "featureCode": "PPLX",
+        "datasetVersion": "2026-11"
+      }
+    ],
+    "postalCode": "63100"
+  },
+  {
+    "id": "bahawalpur-islamia-colony",
+    "cityId": "bahawalpur",
+    "provinceId": "punjab",
+    "name": "Islamia Colony",
+    "aliases": [],
+    "coordinates": {
+      "lat": 29.37168,
+      "lng": 71.69607
+    },
+    "type": "neighborhood",
+    "verified": true,
+    "sources": [
+      {
+        "provider": "nga_geonames",
+        "id": 7391965,
+        "featureCode": "PPLX",
+        "datasetVersion": "2026-11"
+      }
+    ],
+    "postalCode": "63100"
+  },
+  {
+    "id": "bahawalpur-godri",
+    "cityId": "bahawalpur",
+    "provinceId": "punjab",
+    "name": "Godri",
+    "aliases": [],
+    "coordinates": {
+      "lat": 29.418,
+      "lng": 71.67465
+    },
+    "type": "neighborhood",
+    "verified": true,
+    "sources": [
+      {
+        "provider": "nga_geonames",
+        "id": 8300633,
+        "featureCode": "PPLX",
+        "datasetVersion": "2026-11"
+      }
+    ],
+    "postalCode": "63100"
+  },
+  {
+    "id": "bahawalpur-badara",
+    "cityId": "bahawalpur",
+    "provinceId": "punjab",
+    "name": "Badara",
+    "aliases": [],
+    "coordinates": {
+      "lat": 29.41451,
+      "lng": 71.67371
+    },
+    "type": "neighborhood",
+    "verified": true,
+    "sources": [
+      {
+        "provider": "nga_geonames",
+        "id": 11769696,
+        "featureCode": "PPLX",
+        "datasetVersion": "2026-11"
+      }
+    ],
+    "postalCode": "63100"
+  },
+  {
+    "id": "bahawalpur-bhutta-colony",
+    "cityId": "bahawalpur",
+    "provinceId": "punjab",
+    "name": "Bhutta Colony",
+    "aliases": [],
+    "coordinates": {
+      "lat": 29.38065,
+      "lng": 71.65246
+    },
+    "type": "neighborhood",
+    "verified": true,
+    "sources": [
+      {
+        "provider": "nga_geonames",
+        "id": 11769701,
+        "featureCode": "PPLX",
+        "datasetVersion": "2026-11"
+      }
+    ]
   }
 ];
 // Annotate the CommonJS export names for ESM import in node:

package/dist/areas/bhimber.cjs

@@ -46,7 +46,13 @@ var bhimberAreas = [
     "verified": true,
     "sources": [
       "survey",
-      "curated"
+      "curated",
+      {
+        "provider": "nga_geonames",
+        "id": 1182637,
+        "featureCode": "PPLA2",
+        "datasetVersion": "2026-11"
+      }
     ]
   },
   {

package/dist/areas/chakwal.cjs

@@ -203,6 +203,141 @@ var chakwalAreas = [
       "survey",
       "curated"
     ]
+  },
+  {
+    "id": "chakwal-mahalla-sargujran",
+    "cityId": "chakwal",
+    "provinceId": "punjab",
+    "name": "Mahalla Sargujran",
+    "aliases": [
+      "Mohallah Sargujran",
+      "Mohallah Sargujr\u0101n"
+    ],
+    "coordinates": {
+      "lat": 32.93151,
+      "lng": 72.83331
+    },
+    "type": "neighborhood",
+    "verified": true,
+    "sources": [
+      {
+        "provider": "nga_geonames",
+        "id": 7108620,
+        "featureCode": "PPLX",
+        "datasetVersion": "2026-11"
+      }
+    ],
+    "postalCode": "48810"
+  },
+  {
+    "id": "chakwal-anwarabad",
+    "cityId": "chakwal",
+    "provinceId": "punjab",
+    "name": "Anwarabad",
+    "aliases": [],
+    "coordinates": {
+      "lat": 32.92454,
+      "lng": 72.84353
+    },
+    "type": "neighborhood",
+    "verified": true,
+    "sources": [
+      {
+        "provider": "nga_geonames",
+        "id": 7108621,
+        "featureCode": "PPLX",
+        "datasetVersion": "2026-11"
+      }
+    ],
+    "postalCode": "48810"
+  },
+  {
+    "id": "chakwal-ashraf-town",
+    "cityId": "chakwal",
+    "provinceId": "punjab",
+    "name": "Ashraf Town",
+    "aliases": [],
+    "coordinates": {
+      "lat": 32.94817,
+      "lng": 72.85551
+    },
+    "type": "neighborhood",
+    "verified": true,
+    "sources": [
+      {
+        "provider": "nga_geonames",
+        "id": 11633995,
+        "featureCode": "PPLX",
+        "datasetVersion": "2026-11"
+      }
+    ],
+    "postalCode": "48810"
+  },
+  {
+    "id": "chakwal-chaishtian",
+    "cityId": "chakwal",
+    "provinceId": "punjab",
+    "name": "Chaishtian",
+    "aliases": [],
+    "coordinates": {
+      "lat": 32.93564,
+      "lng": 72.83861
+    },
+    "type": "neighborhood",
+    "verified": true,
+    "sources": [
+      {
+        "provider": "nga_geonames",
+        "id": 11633997,
+        "featureCode": "PPLX",
+        "datasetVersion": "2026-11"
+      }
+    ],
+    "postalCode": "48810"
+  },
+  {
+    "id": "chakwal-gulshan-iqbal-town",
+    "cityId": "chakwal",
+    "provinceId": "punjab",
+    "name": "Gulshan Iqbal Town",
+    "aliases": [],
+    "coordinates": {
+      "lat": 32.92791,
+      "lng": 72.83748
+    },
+    "type": "neighborhood",
+    "verified": true,
+    "sources": [
+      {
+        "provider": "nga_geonames",
+        "id": 11633998,
+        "featureCode": "PPLX",
+        "datasetVersion": "2026-11"
+      }
+    ],
+    "postalCode": "48810"
+  },
+  {
+    "id": "chakwal-jhangir-town",
+    "cityId": "chakwal",
+    "provinceId": "punjab",
+    "name": "Jhangir Town",
+    "aliases": [],
+    "coordinates": {
+      "lat": 32.92286,
+      "lng": 72.85625
+    },
+    "type": "neighborhood",
+    "verified": true,
+    "sources": [
+      {
+        "provider": "nga_geonames",
+        "id": 11634001,
+        "featureCode": "PPLX",
+        "datasetVersion": "2026-11"
+      }
+    ],
+    "postalCode": "48810"
   }
 ];
 // Annotate the CommonJS export names for ESM import in node:

package/dist/areas/chaman.cjs

@@ -90,7 +90,13 @@ var chamanAreas = [
     "verified": true,
     "sources": [
       "survey",
-      "curated"
+      "curated",
+      {
+        "provider": "nga_geonames",
+        "id": 1181611,
+        "featureCode": "PPL",
+        "datasetVersion": "2026-11"
+      }
     ]
   },
   {
@@ -205,6 +211,134 @@ var chamanAreas = [
       "survey",
       "curated"
     ]
+  },
+  {
+    "id": "chaman-muhammad-hasan-kili",
+    "cityId": "chaman",
+    "provinceId": "balochistan",
+    "name": "Muhammad Hasan Kili",
+    "aliases": [
+      "Muhammad Hassan Kili"
+    ],
+    "coordinates": {
+      "lat": 30.90609,
+      "lng": 66.45192
+    },
+    "type": "neighborhood",
+    "verified": true,
+    "sources": [
+      {
+        "provider": "nga_geonames",
+        "id": 1350707,
+        "featureCode": "PPLX",
+        "datasetVersion": "2026-11"
+      }
+    ]
+  },
+  {
+    "id": "chaman-muslimabad",
+    "cityId": "chaman",
+    "provinceId": "balochistan",
+    "name": "Muslimabad",
+    "aliases": [],
+    "coordinates": {
+      "lat": 30.92247,
+      "lng": 66.46422
+    },
+    "type": "neighborhood",
+    "verified": true,
+    "sources": [
+      {
+        "provider": "nga_geonames",
+        "id": 6367105,
+        "featureCode": "PPLX",
+        "datasetVersion": "2026-11"
+      }
+    ]
+  },
+  {
+    "id": "chaman-kajar-kili",
+    "cityId": "chaman",
+    "provinceId": "balochistan",
+    "name": "Kajar Kili",
+    "aliases": [],
+    "coordinates": {
+      "lat": 30.9325,
+      "lng": 66.4773
+    },
+    "type": "neighborhood",
+    "verified": true,
+    "sources": [
+      {
+        "provider": "nga_geonames",
+        "id": 6367106,
+        "featureCode": "PPLX",
+        "datasetVersion": "2026-11"
+      }
+    ]
+  },
+  {
+    "id": "chaman-daulatabad",
+    "cityId": "chaman",
+    "provinceId": "balochistan",
+    "name": "Daulatabad",
+    "aliases": [],
+    "coordinates": {
+      "lat": 30.92801,
+      "lng": 66.4691
+    },
+    "type": "neighborhood",
+    "verified": true,
+    "sources": [
+      {
+        "provider": "nga_geonames",
+        "id": 6367107,
+        "featureCode": "PPLX",
+        "datasetVersion": "2026-11"
+      }
+    ]
+  },
+  {
+    "id": "chaman-aduzai-kili",
+    "cityId": "chaman",
+    "provinceId": "balochistan",
+    "name": "Aduzai Kili",
+    "aliases": [],
+    "coordinates": {
+      "lat": 30.90972,
+      "lng": 66.43732
+    },
+    "type": "neighborhood",
+    "verified": true,
+    "sources": [
+      {
+        "provider": "nga_geonames",
+        "id": 6367110,
+        "featureCode": "PPLX",
+        "datasetVersion": "2026-11"
+      }
+    ]
+  },
+  {
+    "id": "chaman-ali-khan-kili",
+    "cityId": "chaman",
+    "provinceId": "balochistan",
+    "name": "Ali Khan Kili",
+    "aliases": [],
+    "coordinates": {
+      "lat": 30.91274,
+      "lng": 66.42485
+    },
+    "type": "neighborhood",
+    "verified": true,
+    "sources": [
+      {
+        "provider": "nga_geonames",
+        "id": 6367111,
+        "featureCode": "PPLX",
+        "datasetVersion": "2026-11"
+      }
+    ]
   }
 ];
 // Annotate the CommonJS export names for ESM import in node:

package/dist/areas/chilas.cjs

@@ -205,6 +205,27 @@ var chilasAreas = [
       "survey",
       "curated"
     ]
+  },
+  {
+    "id": "chilas-thakuri",
+    "cityId": "chilas",
+    "provinceId": "gilgit-baltistan",
+    "name": "Thakuri",
+    "aliases": [],
+    "coordinates": {
+      "lat": 35.41098,
+      "lng": 74.09787
+    },
+    "type": "neighborhood",
+    "verified": true,
+    "sources": [
+      {
+        "provider": "nga_geonames",
+        "id": 11069239,
+        "featureCode": "PPLX",
+        "datasetVersion": "2026-11"
+      }
+    ]
   }
 ];
 // Annotate the CommonJS export names for ESM import in node: