pak-geodata 0.5.0 → 0.9.0

package/README.md

@@ -4,7 +4,7 @@
 
 `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, 79 major and secondary cities, and 812 foundational metropolitan and regional areas across 42 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 +91,7 @@ for (const area of lahoreAreas.slice(0, 5)) {
 
 // Total verified areas in Pakistan
 const allAreas = getAllAreas();
-console.log(`Total verified areas: ${allAreas.length}`); // 812
+console.log(`Total verified areas: ${allAreas.length}`); // 3953
 ```
 
 ### 3. Modular Subpath Imports (Tree-Shaking)
@@ -278,10 +278,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 +329,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 +365,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/abbottabad.cjs

@@ -282,6 +282,72 @@ var abbottabadAreas = [
       "survey",
       "curated"
     ]
+  },
+  {
+    "id": "abbottabad-jinnahabad",
+    "cityId": "abbottabad",
+    "provinceId": "kpk",
+    "name": "Jinnahabad",
+    "urduName": "\u062C\u0646\u0627\u062D \u0622\u0628\u0627\u062F",
+    "aliases": [
+      "Jinnah Abad Abbottabad",
+      "Jinnahabad Colony"
+    ],
+    "postalCode": "22010",
+    "coordinates": {
+      "lat": 34.161,
+      "lng": 73.238
+    },
+    "type": "neighborhood",
+    "verified": true,
+    "sources": [
+      "survey",
+      "curated"
+    ]
+  },
+  {
+    "id": "abbottabad-fawwara-chowk",
+    "cityId": "abbottabad",
+    "provinceId": "kpk",
+    "name": "Fawwara Chowk",
+    "urduName": "\u0641\u0648\u0627\u0631\u06C1 \u0686\u0648\u06A9",
+    "aliases": [
+      "Main Bazaar Fawwara Chowk",
+      "Fawara Chowk Abbottabad"
+    ],
+    "postalCode": "22010",
+    "coordinates": {
+      "lat": 34.148,
+      "lng": 73.215
+    },
+    "type": "commercial",
+    "verified": true,
+    "sources": [
+      "survey",
+      "curated"
+    ]
+  },
+  {
+    "id": "abbottabad-general-bus-stand",
+    "cityId": "abbottabad",
+    "provinceId": "kpk",
+    "name": "General Bus Stand Salhad",
+    "urduName": "\u062C\u0646\u0631\u0644 \u0628\u0633 \u0627\u0633\u0679\u06CC\u0646\u0688 \u0633\u0644\u062D\u062F",
+    "aliases": [
+      "Salhad Bus Adda",
+      "Karakoram Highway Bus Stand"
+    ],
+    "postalCode": "22010",
+    "coordinates": {
+      "lat": 34.135,
+      "lng": 73.208
+    },
+    "type": "commercial",
+    "verified": true,
+    "sources": [
+      "survey",
+      "curated"
+    ]
   }
 ];
 // Annotate the CommonJS export names for ESM import in node:

package/dist/areas/attock.cjs

@@ -0,0 +1,238 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/areas/attock.ts
+var attock_exports = {};
+__export(attock_exports, {
+  attockAreas: () => attockAreas
+});
+module.exports = __toCommonJS(attock_exports);
+
+// src/data/areas/attock.ts
+var attockAreas = [
+  {
+    "id": "attock-cantt",
+    "cityId": "attock",
+    "provinceId": "punjab",
+    "name": "Attock Cantonment",
+    "urduName": "\u0627\u0679\u06A9 \u06A9\u06CC\u0646\u0679",
+    "aliases": [
+      "Attock Cantt",
+      "Cantonment Board Attock"
+    ],
+    "postalCode": "43600",
+    "coordinates": {
+      "lat": 33.768,
+      "lng": 72.365
+    },
+    "type": "administrative",
+    "verified": true,
+    "sources": [
+      "survey",
+      "curated"
+    ]
+  },
+  {
+    "id": "attock-kamra-road",
+    "cityId": "attock",
+    "provinceId": "punjab",
+    "name": "Kamra Road",
+    "urduName": "\u06A9\u0627\u0645\u0631\u06C1 \u0631\u0648\u0688 \u0627\u0679\u06A9",
+    "aliases": [
+      "Kamra Highway Attock",
+      "PAC Kamra Link Road"
+    ],
+    "postalCode": "43600",
+    "coordinates": {
+      "lat": 33.772,
+      "lng": 72.372
+    },
+    "type": "commercial",
+    "verified": true,
+    "sources": [
+      "survey",
+      "curated"
+    ]
+  },
+  {
+    "id": "attock-kachehri-chowk",
+    "cityId": "attock",
+    "provinceId": "punjab",
+    "name": "Kachehri Chowk & District Complex",
+    "urduName": "\u06A9\u0686\u06C1\u0631\u06CC \u0686\u0648\u06A9 \u0627\u0679\u06A9",
+    "aliases": [
+      "District Courts Attock",
+      "DC Office Attock",
+      "Katchery Chowk Attock"
+    ],
+    "postalCode": "43600",
+    "coordinates": {
+      "lat": 33.764,
+      "lng": 72.358
+    },
+    "type": "administrative",
+    "verified": true,
+    "sources": [
+      "survey",
+      "curated"
+    ]
+  },
+  {
+    "id": "attock-meena-bazaar",
+    "cityId": "attock",
+    "provinceId": "punjab",
+    "name": "Meena Bazaar Attock",
+    "urduName": "\u0645\u06CC\u0646\u0627 \u0628\u0627\u0632\u0627\u0631 \u0627\u0679\u06A9",
+    "aliases": [
+      "Main Bazaar Attock",
+      "City Center Attock",
+      "Saddar Attock"
+    ],
+    "postalCode": "43600",
+    "coordinates": {
+      "lat": 33.765,
+      "lng": 72.361
+    },
+    "type": "commercial",
+    "verified": true,
+    "sources": [
+      "survey",
+      "curated",
+      {
+        "provider": "nga_geonames",
+        "id": 1184249,
+        "featureCode": "PPLA2",
+        "datasetVersion": "2026-11"
+      }
+    ]
+  },
+  {
+    "id": "attock-railway-colony",
+    "cityId": "attock",
+    "provinceId": "punjab",
+    "name": "Attock City Railway Station & Colony",
+    "urduName": "\u0627\u0679\u06A9 \u0633\u0679\u06CC \u0631\u06CC\u0644\u0648\u06D2 \u0627\u0633\u0679\u06CC\u0634\u0646",
+    "aliases": [
+      "Railway Station Attock",
+      "Railway Colony Attock"
+    ],
+    "postalCode": "43600",
+    "coordinates": {
+      "lat": 33.759,
+      "lng": 72.354
+    },
+    "type": "neighborhood",
+    "verified": true,
+    "sources": [
+      "survey",
+      "curated"
+    ]
+  },
+  {
+    "id": "attock-peoples-colony",
+    "cityId": "attock",
+    "provinceId": "punjab",
+    "name": "Peoples Colony",
+    "urduName": "\u067E\u06CC\u067E\u0644\u0632 \u06A9\u0627\u0644\u0648\u0646\u06CC \u0627\u0679\u06A9",
+    "aliases": [
+      "Peoples Colony Attock",
+      "People Colony"
+    ],
+    "postalCode": "43600",
+    "coordinates": {
+      "lat": 33.752,
+      "lng": 72.348
+    },
+    "type": "housing_society",
+    "verified": true,
+    "sources": [
+      "survey",
+      "curated"
+    ]
+  },
+  {
+    "id": "attock-madni-chowk",
+    "cityId": "attock",
+    "provinceId": "punjab",
+    "name": "Madni Chowk",
+    "urduName": "\u0645\u062F\u0646\u06CC \u0686\u0648\u06A9 \u0627\u0679\u06A9",
+    "aliases": [
+      "Madni Chowk Attock",
+      "Madni Market"
+    ],
+    "postalCode": "43600",
+    "coordinates": {
+      "lat": 33.769,
+      "lng": 72.368
+    },
+    "type": "commercial",
+    "verified": true,
+    "sources": [
+      "survey",
+      "curated"
+    ]
+  },
+  {
+    "id": "attock-sanjwal-road",
+    "cityId": "attock",
+    "provinceId": "punjab",
+    "name": "Sanjwal Road",
+    "urduName": "\u0633\u0646\u062C\u0648\u0627\u0644 \u0631\u0648\u0688 \u0627\u0679\u06A9",
+    "aliases": [
+      "Sanjwal Cantt Link",
+      "Sanjwal Chowk Attock"
+    ],
+    "postalCode": "43610",
+    "coordinates": {
+      "lat": 33.745,
+      "lng": 72.338
+    },
+    "type": "commercial",
+    "verified": true,
+    "sources": [
+      "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:
+0 && (module.exports = {
+  attockAreas
+});

package/dist/areas/attock.d.ts

@@ -0,0 +1,3 @@
+export { attockAreas } from "../data/areas/attock.js";
+export type { PakistanArea } from "../types.js";
+//# sourceMappingURL=attock.d.ts.map

package/dist/areas/attock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attock.d.ts","sourceRoot":"","sources":["../../src/areas/attock.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}

package/dist/areas/attock.js

@@ -0,0 +1,2 @@
+export { attockAreas } from "../data/areas/attock.js";
+//# sourceMappingURL=attock.js.map

package/dist/areas/attock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attock.js","sourceRoot":"","sources":["../../src/areas/attock.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/areas/bagh.cjs

@@ -0,0 +1,212 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/areas/bagh.ts
+var bagh_exports = {};
+__export(bagh_exports, {
+  baghAreas: () => baghAreas
+});
+module.exports = __toCommonJS(bagh_exports);
+
+// src/data/areas/bagh.ts
+var baghAreas = [
+  {
+    "id": "bagh-main-bazaar",
+    "cityId": "bagh",
+    "provinceId": "ajk",
+    "name": "Main Bazaar Bagh",
+    "urduName": "\u0645\u0631\u06A9\u0632\u06CC \u0628\u0627\u0632\u0627\u0631 \u0628\u0627\u063A",
+    "aliases": [
+      "Bagh Bazaar",
+      "Saddar Bazaar Bagh",
+      "Bagh City Center"
+    ],
+    "postalCode": "12500",
+    "coordinates": {
+      "lat": 33.9805,
+      "lng": 73.7895
+    },
+    "type": "commercial",
+    "verified": true,
+    "sources": [
+      "survey",
+      "curated"
+    ]
+  },
+  {
+    "id": "bagh-district-complex",
+    "cityId": "bagh",
+    "provinceId": "ajk",
+    "name": "District Complex & Kachehri",
+    "urduName": "\u0636\u0644\u0639\u06CC \u06A9\u0645\u067E\u0644\u06CC\u06A9\u0633 \u0628\u0627\u063A",
+    "aliases": [
+      "Kachehri Bagh",
+      "District Courts Bagh",
+      "DC Office Bagh"
+    ],
+    "postalCode": "12500",
+    "coordinates": {
+      "lat": 33.983,
+      "lng": 73.792
+    },
+    "type": "administrative",
+    "verified": true,
+    "sources": [
+      "survey",
+      "curated"
+    ]
+  },
+  {
+    "id": "bagh-zaman-chowk",
+    "cityId": "bagh",
+    "provinceId": "ajk",
+    "name": "Zaman Chowk",
+    "urduName": "\u0632\u0645\u0627\u0646 \u0686\u0648\u06A9 \u0628\u0627\u063A",
+    "aliases": [
+      "Zaman Chowk Bagh City",
+      "Chowk Zaman Bagh"
+    ],
+    "postalCode": "12500",
+    "coordinates": {
+      "lat": 33.978,
+      "lng": 73.787
+    },
+    "type": "commercial",
+    "verified": true,
+    "sources": [
+      "survey",
+      "curated"
+    ]
+  },
+  {
+    "id": "bagh-huda-bari",
+    "cityId": "bagh",
+    "provinceId": "ajk",
+    "name": "Huda Bari",
+    "urduName": "\u06C1\u064F\u062F\u0627 \u0628\u0627\u0631\u06CC \u0628\u0627\u063A",
+    "aliases": [
+      "Hudabari Bagh",
+      "Huda Bari Mohallah"
+    ],
+    "postalCode": "12500",
+    "coordinates": {
+      "lat": 33.975,
+      "lng": 73.782
+    },
+    "type": "neighborhood",
+    "verified": true,
+    "sources": [
+      "survey",
+      "curated"
+    ]
+  },
+  {
+    "id": "bagh-banni-pasari",
+    "cityId": "bagh",
+    "provinceId": "ajk",
+    "name": "Banni Pasari",
+    "urduName": "\u0628\u0646\u06CC \u067E\u0633\u0627\u0631\u06CC \u0628\u0627\u063A",
+    "aliases": [
+      "Bani Pasari Bagh",
+      "Banni Pasari Mohallah"
+    ],
+    "postalCode": "12500",
+    "coordinates": {
+      "lat": 33.988,
+      "lng": 73.795
+    },
+    "type": "neighborhood",
+    "verified": true,
+    "sources": [
+      "survey",
+      "curated"
+    ]
+  },
+  {
+    "id": "bagh-sudhan-galli-road",
+    "cityId": "bagh",
+    "provinceId": "ajk",
+    "name": "Sudhan Galli Road",
+    "urduName": "\u0633\u062F\u06BE\u0646 \u06AF\u0644\u06CC \u0631\u0648\u0688 \u0628\u0627\u063A",
+    "aliases": [
+      "Sudhangali Road Bagh",
+      "Sudhan Gali Bypass"
+    ],
+    "postalCode": "12510",
+    "coordinates": {
+      "lat": 33.992,
+      "lng": 73.801
+    },
+    "type": "commercial",
+    "verified": true,
+    "sources": [
+      "survey",
+      "curated"
+    ]
+  },
+  {
+    "id": "bagh-chhatra",
+    "cityId": "bagh",
+    "provinceId": "ajk",
+    "name": "Chhatra",
+    "urduName": "\u0686\u06BE\u062A\u0631\u0627 \u0628\u0627\u063A",
+    "aliases": [
+      "Chhatra Bagh",
+      "Chhatra No 1",
+      "Chhatra No 2"
+    ],
+    "postalCode": "12520",
+    "coordinates": {
+      "lat": 33.968,
+      "lng": 73.778
+    },
+    "type": "neighborhood",
+    "verified": true,
+    "sources": [
+      "survey",
+      "curated"
+    ]
+  },
+  {
+    "id": "bagh-dhulli",
+    "cityId": "bagh",
+    "provinceId": "ajk",
+    "name": "Dhulli",
+    "urduName": "\u062F\u06BE\u0644\u06CC \u0628\u0627\u063A",
+    "aliases": [
+      "Dhulli Bagh",
+      "Dhulli Valley Link"
+    ],
+    "postalCode": "12530",
+    "coordinates": {
+      "lat": 33.955,
+      "lng": 73.765
+    },
+    "type": "neighborhood",
+    "verified": true,
+    "sources": [
+      "survey",
+      "curated"
+    ]
+  }
+];
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  baghAreas
+});

package/dist/areas/bagh.d.ts

@@ -0,0 +1,3 @@
+export { baghAreas } from "../data/areas/bagh.js";
+export type { PakistanArea } from "../types.js";
+//# sourceMappingURL=bagh.d.ts.map

package/dist/areas/bagh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bagh.d.ts","sourceRoot":"","sources":["../../src/areas/bagh.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}

package/dist/areas/bagh.js

@@ -0,0 +1,2 @@
+export { baghAreas } from "../data/areas/bagh.js";
+//# sourceMappingURL=bagh.js.map

package/dist/areas/bagh.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bagh.js","sourceRoot":"","sources":["../../src/areas/bagh.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC"}