pakdatakit 2.2.1 → 2.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/DATA.md +512 -34
- package/LICENSE +1 -1
- package/NOTICE +14 -0
- package/README.md +472 -28
- package/dist/address.cjs +6 -5
- package/dist/address.js +4 -3
- package/dist/bills.cjs +19 -0
- package/dist/bills.d.cts +63 -0
- package/dist/bills.d.ts +63 -0
- package/dist/bills.js +2 -0
- package/dist/{chunk-4VSGCQ6K.cjs → chunk-2OBKPYJZ.cjs} +3 -3
- package/dist/chunk-33GOK7EE.cjs +5312 -0
- package/dist/chunk-33QMFE2Z.js +21244 -0
- package/dist/chunk-34U2ZMHR.js +194 -0
- package/dist/chunk-4GSBHJX6.js +165 -0
- package/dist/chunk-5DDHO5Z7.cjs +565 -0
- package/dist/chunk-5EY5DQS7.js +51 -0
- package/dist/chunk-5RGX4DWF.js +559 -0
- package/dist/chunk-5UCRHVI4.cjs +302 -0
- package/dist/{chunk-TTARJWGT.js → chunk-7DY26QPN.js} +2 -2
- package/dist/chunk-7E7L3NYS.cjs +11 -0
- package/dist/{chunk-3ZA265SK.cjs → chunk-AUQFA7EE.cjs} +172 -4
- package/dist/{chunk-QKH7W2CC.js → chunk-B7DOQ5QF.js} +6 -5
- package/dist/{chunk-HBOZIITD.js → chunk-CADQM4ZN.js} +14 -14
- package/dist/chunk-CF6AMRBU.cjs +198 -0
- package/dist/chunk-CZOZB4K3.js +61 -0
- package/dist/{chunk-3IARSCO6.cjs → chunk-DHOP7LQX.cjs} +25 -14
- package/dist/chunk-E2XU6NOW.js +909 -0
- package/dist/chunk-E6GWBOKV.cjs +911 -0
- package/dist/chunk-E6HSKRAE.js +9 -0
- package/dist/chunk-EA3SIHYT.js +313 -0
- package/dist/{chunk-33FXHM2E.cjs → chunk-ESKXG7Y6.cjs} +5 -5
- package/dist/chunk-I7UUPD3G.cjs +21252 -0
- package/dist/{chunk-YPPKY5XZ.js → chunk-IBZPJS4H.js} +26 -15
- package/dist/chunk-IDTRFOQW.js +35 -0
- package/dist/{chunk-XCXFGTHW.cjs → chunk-J5ZF46NZ.cjs} +14 -14
- package/dist/{chunk-NZQ47NWD.js → chunk-KRYHLYN2.js} +1 -1
- package/dist/{chunk-RXNYY5K5.js → chunk-LQHM3ADX.js} +172 -4
- package/dist/{chunk-HTERSQGF.cjs → chunk-MTS6SVNP.cjs} +4 -4
- package/dist/chunk-OTI7HY55.js +297 -0
- package/dist/{chunk-6IPPANNX.js → chunk-P7LVE2TF.js} +2 -2
- package/dist/{chunk-47P7HILD.cjs → chunk-QFPEFD67.cjs} +9 -8
- package/dist/chunk-RZQJAZKC.js +22 -0
- package/dist/{chunk-PLDVGOKZ.js → chunk-S274QFFB.js} +2 -2
- package/dist/chunk-SF4ECUZ6.cjs +56 -0
- package/dist/chunk-SQIHFEXI.cjs +25 -0
- package/dist/{chunk-NAJGGUAM.cjs → chunk-TC3VRWZV.cjs} +2 -2
- package/dist/{chunk-U7MWHXMF.cjs → chunk-TVL6RDAU.cjs} +4 -4
- package/dist/chunk-UYFTXD4P.js +168 -0
- package/dist/{chunk-AZV45DMG.js → chunk-V2XE3NCG.js} +2 -2
- package/dist/chunk-XCFZKCV2.cjs +37 -0
- package/dist/chunk-XOTCIXY6.js +5301 -0
- package/dist/chunk-XVEG53NN.cjs +322 -0
- package/dist/chunk-YDUXIENX.cjs +172 -0
- package/dist/chunk-YPAWNWFD.cjs +168 -0
- package/dist/chunk-YQFI7W3I.cjs +65 -0
- package/dist/{chunk-NTD4JLDW.cjs → chunk-YTLE5K7G.cjs} +1 -1
- package/dist/{chunk-EMH4IP2U.js → chunk-ZRONAQBV.js} +1 -1
- package/dist/class-validator.cjs +65 -0
- package/dist/class-validator.d.cts +63 -0
- package/dist/class-validator.d.ts +63 -0
- package/dist/class-validator.js +54 -0
- package/dist/cli.js +1 -1
- package/dist/courier.cjs +16 -0
- package/dist/courier.d.cts +51 -0
- package/dist/courier.d.ts +51 -0
- package/dist/courier.js +3 -0
- package/dist/fbr-invoice.cjs +25 -0
- package/dist/fbr-invoice.d.cts +170 -0
- package/dist/fbr-invoice.d.ts +170 -0
- package/dist/fbr-invoice.js +4 -0
- package/dist/geo.cjs +23 -6
- package/dist/geo.d.cts +56 -1
- package/dist/geo.d.ts +56 -1
- package/dist/geo.js +2 -1
- package/dist/holidays.cjs +4 -4
- package/dist/holidays.js +1 -1
- package/dist/iban.cjs +5 -5
- package/dist/iban.d.cts +8 -6
- package/dist/iban.d.ts +8 -6
- package/dist/iban.js +1 -1
- package/dist/incometax.cjs +27 -0
- package/dist/incometax.d.cts +91 -0
- package/dist/incometax.d.ts +91 -0
- package/dist/incometax.js +2 -0
- package/dist/index.cjs +253 -111
- package/dist/index.d.cts +12 -4
- package/dist/index.d.ts +12 -4
- package/dist/index.js +25 -15
- package/dist/input.cjs +9 -9
- package/dist/input.js +3 -3
- package/dist/joi.cjs +43 -0
- package/dist/joi.d.cts +25 -0
- package/dist/joi.d.ts +25 -0
- package/dist/joi.js +37 -0
- package/dist/networks.cjs +3 -3
- package/dist/networks.js +2 -2
- package/dist/numbers.cjs +6 -6
- package/dist/numbers.js +2 -2
- package/dist/passport.cjs +11 -0
- package/dist/passport.d.cts +27 -0
- package/dist/passport.d.ts +27 -0
- package/dist/passport.js +2 -0
- package/dist/phone.cjs +8 -8
- package/dist/phone.js +3 -3
- package/dist/postal.cjs +14 -6
- package/dist/postal.d.cts +54 -2
- package/dist/postal.d.ts +54 -2
- package/dist/postal.js +1 -1
- package/dist/quality.cjs +25 -0
- package/dist/quality.d.cts +62 -0
- package/dist/quality.d.ts +62 -0
- package/dist/quality.js +8 -0
- package/dist/raast.cjs +6 -6
- package/dist/raast.js +2 -2
- package/dist/salestax.cjs +20 -0
- package/dist/salestax.d.cts +106 -0
- package/dist/salestax.d.ts +106 -0
- package/dist/salestax.js +3 -0
- package/dist/superstruct.cjs +41 -0
- package/dist/superstruct.d.cts +25 -0
- package/dist/superstruct.d.ts +25 -0
- package/dist/superstruct.js +39 -0
- package/dist/text.cjs +21 -5
- package/dist/text.d.cts +90 -1
- package/dist/text.d.ts +90 -1
- package/dist/text.js +1 -1
- package/dist/valibot.cjs +18 -8
- package/dist/valibot.d.cts +3 -0
- package/dist/valibot.d.ts +3 -0
- package/dist/valibot.js +17 -7
- package/dist/vehicle.cjs +15 -0
- package/dist/vehicle.d.cts +43 -0
- package/dist/vehicle.d.ts +43 -0
- package/dist/vehicle.js +2 -0
- package/dist/whatsapp.cjs +3 -3
- package/dist/whatsapp.js +2 -2
- package/dist/yup.cjs +18 -8
- package/dist/yup.d.cts +3 -0
- package/dist/yup.d.ts +3 -0
- package/dist/yup.js +17 -7
- package/dist/zod.cjs +18 -8
- package/dist/zod.d.cts +3 -0
- package/dist/zod.d.ts +3 -0
- package/dist/zod.js +17 -7
- package/package.json +167 -6
- package/dist/chunk-34CJGJ67.cjs +0 -1697
- package/dist/chunk-4VVFS6FN.cjs +0 -715
- package/dist/chunk-E6DT2DWQ.js +0 -1689
- package/dist/chunk-GJENL6VK.cjs +0 -22
- package/dist/chunk-HUQY2WR5.js +0 -20
- package/dist/chunk-JKE4AMSZ.js +0 -47
- package/dist/chunk-KEHCTYLO.cjs +0 -52
- package/dist/chunk-LIYNKIKS.js +0 -709
package/DATA.md
CHANGED
|
@@ -1,11 +1,16 @@
|
|
|
1
1
|
# Data sources
|
|
2
2
|
|
|
3
3
|
PakDataKit's datasets live in `data/` and are generated by
|
|
4
|
-
`scripts/generate-data.mjs` (except `networks.json`, `area-codes.json
|
|
5
|
-
`holidays.json`, which are edited directly).
|
|
4
|
+
`scripts/generate-data.mjs` (except `networks.json`, `area-codes.json`,
|
|
5
|
+
`holidays.json` and `sales-tax-rates.json`, which are edited directly). Two official lists are kept as
|
|
6
|
+
extracted CSV files in `data/sources/` and read by the generator: Pakistan
|
|
7
|
+
Post's post code directory and the 2023 census's administrative units. The exported `dataVersion` is the
|
|
6
8
|
date the data was last checked.
|
|
7
9
|
|
|
8
|
-
**Data version: 2026-11-
|
|
10
|
+
**Data version: 2026-11-18**
|
|
11
|
+
|
|
12
|
+
The datasets were audited against official sources on 16 November 2026;
|
|
13
|
+
[AUDIT.md](AUDIT.md) has the findings, the fixes made and what is still open.
|
|
9
14
|
|
|
10
15
|
Official bodies (PTA, NADRA, SBP, Pakistan Post) publish few machine-readable
|
|
11
16
|
lists, so some entries rest on secondary sources. Each section says how sure we
|
|
@@ -15,53 +20,139 @@ are. To correct an entry, open an issue or pull request with a source.
|
|
|
15
20
|
|
|
16
21
|
SBP does not publish a list of IBAN bank codes, and IBAN codes do not always
|
|
17
22
|
match SWIFT BIC prefixes (e.g. Silkbank is `SAUD`). Codes are therefore checked
|
|
18
|
-
against real IBANs.
|
|
19
|
-
|
|
20
|
-
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
`
|
|
23
|
+
against real IBANs. Names follow SBP's lists of regulated institutions
|
|
24
|
+
(https://www.sbp.org.pk/sbp-regulated-institutions/commercial-banks and
|
|
25
|
+
.../microfinance-banks, retrieved 2026-11-16), with a former name kept in
|
|
26
|
+
brackets where people still search for it.
|
|
27
|
+
|
|
28
|
+
- **Confirmed from IBANs printed by SBP:** 35 codes, from SBP's list of dam
|
|
29
|
+
fund accounts at every bank
|
|
30
|
+
(https://archive.sbp.org.pk/notifications/FD/DamFund/Detail-1.pdf, undated,
|
|
31
|
+
about 2018, retrieved 2026-11-16): `AIIN`, `ABPA`, `ASCM`, `ALFH`, `BAHL`,
|
|
32
|
+
`BKIP`, `KHYB`, `BPUN`, `BKCH`, `CITI`, `DEUT`, `DUIB`, `FAYS`, `FWOM`,
|
|
33
|
+
`HABB`, `MPBL`, `ICBK`, `JSBL`, `MUCB`, `MCIB`, `MEZN`, `NBPA`, `SAMB`,
|
|
34
|
+
`SAUD`, `SIND`, `SMES`, `SONE`, `SCBL`, `SUMB`, `UNIL`, `ZTBL` (Zarai
|
|
35
|
+
Taraqiati Bank), `TMFB`, `WMBL`, `FMFB` and `SMFB` (Sindh Microfinance
|
|
36
|
+
Bank). The same list shows an `SBPP` IBAN in use. `ZTBL` and `SMFB` were
|
|
37
|
+
added on 2026-11-16 from this list. (It prints ICBC's IBAN with a digit `1`
|
|
38
|
+
for the `I`; the checksum is only valid with `ICBK`.)
|
|
39
|
+
- **Also confirmed from IBANs printed by SBP:** `KHBL` (Khushhali), `JCMA`
|
|
40
|
+
(Mobilink Microfinance Bank), `FINC` (ABHI, as FINCA), `UMBL`, `NRSP` and
|
|
41
|
+
`APNA`, from SBP's account lists for the Prime Minister's Flood Relief Fund
|
|
42
|
+
2022 (https://archive.sbp.org.pk/IBANs-of-PM-Flood-Relief-Fund.pdf) and the
|
|
43
|
+
2023 relief fund for Türkiye and Syria
|
|
44
|
+
(https://archive.sbp.org.pk/ReliefFund-Turkiye.pdf), both retrieved
|
|
45
|
+
2026-11-16. That makes 41 codes confirmed by SBP documents.
|
|
27
46
|
- **Confirmed from published IBANs on smaller sites:** `SADA` (SadaPay), `NAYA`
|
|
28
47
|
(NayaPay).
|
|
29
48
|
- **Confirmed from real account IBANs shared by a maintainer:** `RQMI` (Raqami
|
|
30
49
|
Islamic Digital Bank) and `MSHQ` (Mashreq Bank Pakistan), both digital banks.
|
|
31
|
-
- **
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
50
|
+
- **Legacy codes with no official source:** `MCBL`, `NBPB`, `TAMW` and `NIBP`.
|
|
51
|
+
- **Not included, because no code could be confirmed:** Punjab Provincial
|
|
52
|
+
Cooperative Bank, LOLC Microfinance Bank (formerly Pak Oman), Halan
|
|
53
|
+
Microfinance Bank (formerly Advans), ASA Microfinance Bank, the EMIs Finja,
|
|
54
|
+
Akhtar Fuiou Technologies, E-Processing Systems, Wemsol and YAP Pakistan,
|
|
55
|
+
HugoBank, KT Bank and Bank of AJK. A second search on 2026-11-16 (SBP's
|
|
56
|
+
relief-fund lists and each institution's own website) found no printed IBAN
|
|
57
|
+
for any of them.
|
|
58
|
+
- **Types** follow SBP's groups on its list of regulated institutions:
|
|
59
|
+
"Public Sector Commercial Banks" are `public-sector` (National Bank of
|
|
60
|
+
Pakistan, Sindh Bank, The Bank of Khyber, The Bank of Punjab), "Local
|
|
61
|
+
Private Banks" are `commercial`, and "Islamic", "Foreign", "Specialized"
|
|
62
|
+
and "Digital" banks have the type of the same name.
|
|
63
|
+
- **Spelling.** Names use each bank's own styling ("Bank Alfalah Limited",
|
|
64
|
+
"Bank Al Habib Limited", "BankIslami Pakistan Limited", "Citibank N.A.
|
|
65
|
+
Pakistan"). SBP's list spells some differently, and not consistently
|
|
66
|
+
("Bank Al-Falah Limited", "Bank Al-Habib Limited", "Al-Baraka Bank
|
|
67
|
+
(Pakistan) Limited", "Bank Islami Pakistan Limited", "Citi Bank N.A",
|
|
68
|
+
"Industrial & Commercial Bank of China", "Allied Bank limited"), so it is
|
|
69
|
+
recorded here and not copied.
|
|
70
|
+
- **Closed:** `SMES` → "SME Bank Limited (in liquidation)", `active: false`.
|
|
71
|
+
SBP cancelled its licence and de-scheduled it on 17 March 2025
|
|
72
|
+
(https://archive.sbp.org.pk/notifications/bprd/2025/ntf6.htm). `NIBP` was
|
|
73
|
+
de-scheduled on 7 July 2017 on its merger into MCB Bank
|
|
74
|
+
(https://archive.sbp.org.pk/notifications/bprd/2017/ntf2.htm).
|
|
36
75
|
- **Merged or renamed** banks keep their code with the current name, e.g.
|
|
37
|
-
`SAUD` → "Silkbank Limited (merged into United Bank Limited)"
|
|
76
|
+
`SAUD` → "Silkbank Limited (merged into United Bank Limited)" (de-scheduled
|
|
77
|
+
by SBP on 10 March 2025,
|
|
78
|
+
https://archive.sbp.org.pk/notifications/bprd/2025/ntf4.htm) and `TMFB` →
|
|
79
|
+
"Easypaisa Bank Limited" (a scheduled bank from 23 January 2025,
|
|
80
|
+
https://archive.sbp.org.pk/notifications/bprd/2025/ntf1.htm).
|
|
38
81
|
|
|
39
82
|
## Mobile networks (`networks.json`)
|
|
40
83
|
|
|
41
|
-
`03XX` prefixes and the operator each was originally allocated to. PTA
|
|
42
|
-
|
|
84
|
+
`03XX` prefixes and the operator each was originally allocated to. PTA has no
|
|
85
|
+
current operator-by-prefix table. Its National Numbering Plan 2008 paper
|
|
86
|
+
(https://www.pta.gov.pk/assets/media/nnp_08_final.pdf, retrieved 2026-11-16)
|
|
87
|
+
gives the two-digit allocations: 30 Mobilink (Jazz), 31 Paktel (now Zong), 32
|
|
88
|
+
Warid (now Jazz), 33 Ufone, 34 Telenor, 35 SCO, 36 Instaphone, and 37 to 39
|
|
89
|
+
"for future use". Individual prefixes are cross-checked with Google
|
|
43
90
|
libphonenumber and operator announcements.
|
|
44
91
|
|
|
45
92
|
- `0329` (Jazz) and `0355` (SCO) included.
|
|
46
|
-
- `0370`–`0371` (Zong) included
|
|
47
|
-
|
|
93
|
+
- `0370`–`0371` (Zong) included, from libphonenumber only. **Unverified:**
|
|
94
|
+
two searches in November 2026 (PTA's annual reports for 2021 to 2024, its
|
|
95
|
+
numbering documents and licensee list, the ITU page for Pakistan and
|
|
96
|
+
zong.com.pk) found no official document that gives 037x to an operator. `0372`–`0379` are **not**
|
|
97
|
+
included, as no allocation or use was found.
|
|
48
98
|
- `0364` (Instaphone, licence cancelled in 2008) is not included.
|
|
49
|
-
- `034x` is labelled Telenor, the original allocation
|
|
50
|
-
into PTML (Ufone) in 2026
|
|
51
|
-
|
|
99
|
+
- `034x` is labelled Telenor, the original allocation. Telenor Pakistan was
|
|
100
|
+
merged into PTML (Ufone) in July 2026: PTCL announced the "successful
|
|
101
|
+
completion of the amalgamation" on 2 July 2026
|
|
102
|
+
(https://ptcl.com.pk/Home/PressReleaseDetail/?ItemId=934&linkId=130,
|
|
103
|
+
retrieved 2026-11-16). The label is kept because the dataset records the
|
|
104
|
+
operator a prefix was allocated to, no new brand has been announced
|
|
105
|
+
officially (PTCL still writes "Ufone 5G"), and PTA's own pages still list
|
|
106
|
+
Telenor Pakistan. With number portability, the current operator can differ
|
|
107
|
+
for any prefix.
|
|
52
108
|
|
|
53
109
|
## Landline area codes (`area-codes.json`)
|
|
54
110
|
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
111
|
+
114 codes, from the numbering plan PTA sent to the ITU on 9 November 2021
|
|
112
|
+
(https://www.itu.int/dms_pub/itu-t/oth/02/02/T02020000A10002PDFE.pdf,
|
|
113
|
+
retrieved 2026-11-16), which lists every code with its district. The 73 codes
|
|
114
|
+
held before November 2026 came from PTCL's national dialling-code list
|
|
115
|
+
(https://ptcl.com.pk/Info/National-Dialing-Codes) and all appear in the ITU
|
|
116
|
+
plan with the same districts.
|
|
117
|
+
|
|
118
|
+
- **Added 2026-11-16 from the ITU plan:** 18 codes in Balochistan (`822`
|
|
119
|
+
Zhob to `856` Awaran), 8 in Khyber Pakhtunkhwa (`924` Khyber and Mohmand,
|
|
120
|
+
`932` Malakand, `939` Buner, `942` Bajaur, `944` Upper Dir, `945` Lower
|
|
121
|
+
Dir, `965` South Waziristan, `996` Shangla), 7 in Gilgit-Baltistan (`5811`
|
|
122
|
+
Gilgit to `5817` Astore) and 8 in Azad Jammu and Kashmir (`5821` Neelum to
|
|
123
|
+
`5828` Bhimber).
|
|
124
|
+
- Names are the districts the plan gives, spelt as in `districts.json` so
|
|
125
|
+
that `getAreaCode` finds them: the plan writes "Neelum", "Sudonthi",
|
|
126
|
+
"Bhimer" and "K.Abdullah / Pishin" for Neelam, Sudhnuti, Bhimber and Killa
|
|
127
|
+
Abdullah and Pishin. `832` is listed there as Bolan, the former name of
|
|
128
|
+
Kachhi district; both names find it. For the two districts split since
|
|
129
|
+
2021, the successors are listed with the plan's name: `835` Dera Bugti,
|
|
130
|
+
North Dera Bugti and South Dera Bugti; `965` South Waziristan, Lower South
|
|
131
|
+
Waziristan and Upper South Waziristan.
|
|
132
|
+
- PTCL's own list differs for Azad Jammu and Kashmir (Muzaffarabad "58",
|
|
133
|
+
Kotli "574") and has no Mirpur or Gilgit entry. The ITU plan is the newer
|
|
134
|
+
list from PTA, so it is followed.
|
|
135
|
+
- **Number lengths** are not taken from the ITU plan (its length table could
|
|
136
|
+
not be read reliably). The patterns in `numbers.ts` come from
|
|
137
|
+
libphonenumber's PK metadata (v9.0.41), which already accepted numbers in
|
|
138
|
+
all 41 added codes: ten digits in all for the `58xx` codes, so a four-digit
|
|
139
|
+
code is followed by six digits.
|
|
59
140
|
|
|
60
141
|
## Districts (`districts.json`)
|
|
61
142
|
|
|
62
143
|
177 districts as of October 2026: Punjab 41, Sindh 30, Khyber Pakhtunkhwa 40,
|
|
63
144
|
Balochistan 41, Gilgit-Baltistan 14, Azad Jammu and Kashmir 10, Islamabad 1.
|
|
64
145
|
|
|
146
|
+
> **Unverified: Central Dir, Allai and Paharpur** (Khyber Pakhtunkhwa). They
|
|
147
|
+
> rest on a news report of January 2026, not on a notification. Official
|
|
148
|
+
> pages updated in November 2026 do not show them: Malakand Division lists
|
|
149
|
+
> 10 districts without Central Dir (cmd.kp.gov.pk), Hazara Division lists 8
|
|
150
|
+
> without Allai (chd.kp.gov.pk), and the KP Bureau of Statistics'
|
|
151
|
+
> Development Statistics 2026 has Allai as a tehsil of Batagram and Paharpur
|
|
152
|
+
> as a tehsil of Dera Ismail Khan (all retrieved 2026-11-16). They are kept
|
|
153
|
+
> until a notification settles it either way. Nine more districts are also
|
|
154
|
+
> not confirmed on an official page; see the end of this section.
|
|
155
|
+
|
|
65
156
|
- **Khyber Pakhtunkhwa** (APP, January 2026: "increased to 40"): Lower and Upper
|
|
66
157
|
South Waziristan (2022), Central Dir and Allai (January 2023), Paharpur
|
|
67
158
|
(November 2025), Bar Swat (January 2026; reported as "Upper Swat" before
|
|
@@ -78,28 +169,415 @@ Balochistan 41, Gilgit-Baltistan 14, Azad Jammu and Kashmir 10, Islamabad 1.
|
|
|
78
169
|
so current names are kept.
|
|
79
170
|
- Former names (Quetta, Dera Bugti, Upper Dera Bugti, South Waziristan, Upper
|
|
80
171
|
Swat) still resolve in `getDistrictProvince`.
|
|
172
|
+
- **Official confirmation, checked 2026-11-16** (details in AUDIT.md,
|
|
173
|
+
section 9). Confirmed on official pages: Murree, Talagang, Wazirabad, Kot
|
|
174
|
+
Addu and Taunsa (Punjab Board of Revenue list); Lower and Upper South
|
|
175
|
+
Waziristan and Hub (Election Commission delimitation report, 2023); Bar
|
|
176
|
+
Swat (Malakand Division's website); Usta Muhammad, Barshore and Tump
|
|
177
|
+
(Balochistan budget documents, June 2026). **Not confirmed on any official
|
|
178
|
+
page that could be read:** Central Dir, Allai and Paharpur (Khyber
|
|
179
|
+
Pakhtunkhwa's divisional websites and its Development Statistics 2026
|
|
180
|
+
still show Allai and Paharpur as tehsils and list no Central Dir); Quetta
|
|
181
|
+
East and West, North and South Dera Bugti and Wadh (Balochistan); and
|
|
182
|
+
Darel, Tangir, Gupis-Yasin and Roundu (Gilgit-Baltistan's 2024-25
|
|
183
|
+
development programme treats them as sub-divisions). These stay in the
|
|
184
|
+
dataset on the strength of the notifications and reports cited above, and
|
|
185
|
+
are the entries most likely to need correcting.
|
|
81
186
|
|
|
82
187
|
## Cities (`cities.json`)
|
|
83
188
|
|
|
84
189
|
District headquarters and major towns, plus every city that has a postal code
|
|
85
190
|
in `postal-codes.json`, each mapped to its province.
|
|
86
191
|
|
|
87
|
-
## Postal codes (`postal-codes.json`)
|
|
192
|
+
## Postal codes (`postal-codes.json`, `post-offices.json`)
|
|
193
|
+
|
|
194
|
+
Both files come from Pakistan Post's "Post Code Directory of Delivery Post
|
|
195
|
+
Offices" (Part I), a 45-page PDF dated February 2021
|
|
196
|
+
(https://www.pakpost.gov.pk/images/national%20post%20code%20directory.pdf,
|
|
197
|
+
retrieved 2026-11-16). Its office name, code, account office and province
|
|
198
|
+
columns are extracted to `data/sources/pakpost-delivery-post-offices.csv`
|
|
199
|
+
(2,564 rows), and `scripts/generate-data.mjs` builds both files from it.
|
|
200
|
+
|
|
201
|
+
- **`post-offices.json`** (2,560 entries, for `getPostOffice` and
|
|
202
|
+
`searchPostOffices`): every office, as `code`, `office` (the directory's
|
|
203
|
+
name in title case), `town`, `district` and `province`. The directory
|
|
204
|
+
lists four codes twice, for the same place under two spellings (`22190`,
|
|
205
|
+
`40520`, `56320`, `63050`); the first row is kept.
|
|
206
|
+
- **`postal-codes.json`** (457 entries, for `getCityByPostalCode`,
|
|
207
|
+
`getPostalCode`, `getPostalCodes`, `getPostalAreas` and
|
|
208
|
+
`searchPostalCodes`): only the offices that belong to a city in
|
|
209
|
+
`cities.json`, as `city`, `postalCode`, `area` (the office name),
|
|
210
|
+
`province`, and `district` and `primary` where they apply.
|
|
211
|
+
- **Which city an office belongs to.** The directory has no city column, so
|
|
212
|
+
this is worked out:
|
|
213
|
+
1. the 110 entries checked by hand before the import keep their city
|
|
214
|
+
(including the eight codes corrected in November 2026);
|
|
215
|
+
2. an office named after a city in `cities.json`, in the same province,
|
|
216
|
+
belongs to that city ("ABBOTTABAD GPO" → Abbottabad);
|
|
217
|
+
3. every office under the Karachi, Lahore and Islamabad account offices
|
|
218
|
+
belongs to that city;
|
|
219
|
+
4. an office whose name starts or ends with the city of its own account
|
|
220
|
+
office belongs to that city ("GULISTAN COLONY, FAISALABAD").
|
|
221
|
+
|
|
222
|
+
Any other office is in a town or village that is not on the city list. It
|
|
223
|
+
is only in `post-offices.json`, where `town` is the office's own name
|
|
224
|
+
("Dulmial"); `getCityByPostalCode` returns `null` for it.
|
|
225
|
+
|
|
226
|
+
- **District** is given only where the town is the headquarters a district
|
|
227
|
+
is named after (349 offices). An account office can serve several
|
|
228
|
+
districts, so it is not used to guess one.
|
|
229
|
+
- **Province** is the directory's, with its spelling normalised ("Azad
|
|
230
|
+
Kashmir" → Azad Jammu and Kashmir, "Federal Capital" → Islamabad Capital
|
|
231
|
+
Territory, and the misprints "Punjba" and "SIndh").
|
|
232
|
+
- **Primary.** `getPostalCode(city)` returns the hand-checked code for the 95
|
|
233
|
+
cities that had one. For 63 more cities it returns the code of the office
|
|
234
|
+
named "<city> GPO", or else the office named after the city.
|
|
235
|
+
- **Names** are converted from the directory's capitals to title case; its
|
|
236
|
+
spellings are kept, including misprints ("Islamabad Primr Minister
|
|
237
|
+
Sectt.").
|
|
238
|
+
- **Not included:** the 740 or so non-delivery post offices of Part II
|
|
239
|
+
(https://www.pakpost.gov.pk/images/LIST%20OF%20NON%20DELIVERY%20POs.pdf).
|
|
240
|
+
- The directory is dated 2021. Pakistan Post's web table
|
|
241
|
+
(https://www.pakpost.gov.pk/postcodes.php) is missing many offices, so it
|
|
242
|
+
is not the source; it was used for the spot-check below.
|
|
243
|
+
|
|
244
|
+
## Divisions and tehsils (`divisions.json`, `tehsils.json`)
|
|
245
|
+
|
|
246
|
+
From Table 1 of the 2023 census (Pakistan Bureau of Statistics), which lists
|
|
247
|
+
every administrative unit with its area and population. Retrieved 2026-11-16:
|
|
248
|
+
|
|
249
|
+
- tehsils by district:
|
|
250
|
+
https://www.pbs.gov.pk/wp-content/uploads/census_tables/tables/table_1_punjab_districts.pdf
|
|
251
|
+
and the same file name for `sindh`, `kp` and `balochistan`, plus
|
|
252
|
+
`table_1_islamabad.pdf`;
|
|
253
|
+
- districts by division: `table_1_punjab_province.pdf` and the same for the
|
|
254
|
+
other three provinces.
|
|
255
|
+
|
|
256
|
+
The rows are extracted to `data/sources/census-2023-admin-units.csv`. The
|
|
257
|
+
totals match the census report's Table 1.1: **30 divisions, 136 districts and
|
|
258
|
+
591 tehsil-level units** (Punjab 146, Sindh 138, Khyber Pakhtunkhwa 148,
|
|
259
|
+
Balochistan 158, Islamabad 1).
|
|
88
260
|
|
|
89
|
-
|
|
90
|
-
|
|
261
|
+
- **Tehsil-level units** are what the census counts: 306 tehsils, 107
|
|
262
|
+
talukas (Sindh), 134 sub-divisions (Karachi, the merged districts of Khyber
|
|
263
|
+
Pakhtunkhwa and much of Balochistan), 43 sub-tehsils (Balochistan) and one
|
|
264
|
+
de-excluded area (Rajanpur). Each entry has a `type`.
|
|
265
|
+
- **Census district.** Every tehsil has a `censusDistrict`: the district it
|
|
266
|
+
was in at the census. The census had 136 districts; `districts.json` has
|
|
267
|
+
the 177 of today. Three census districts have since been split and are no
|
|
268
|
+
longer district names: Quetta, Dera Bugti and South Waziristan.
|
|
269
|
+
- **Current district.** `currentDistrict` is the same as `censusDistrict`
|
|
270
|
+
for the 119 census districts that have not lost territory to a new
|
|
271
|
+
district. For tehsils of the 17 that have (Rawalpindi, Chakwal,
|
|
272
|
+
Gujranwala, Muzaffargarh, Dera Ghazi Khan, South Waziristan, Upper Dir,
|
|
273
|
+
Batagram, Dera Ismail Khan, Swat, Lasbela, Jaffarabad, Quetta, Dera Bugti,
|
|
274
|
+
Pishin, Kech and Khuzdar) it is set only where an official
|
|
275
|
+
source confirms where the tehsil is now, and is `null` otherwise.
|
|
276
|
+
- **Confirmed (Punjab, all 25 tehsils of the five parent districts):**
|
|
277
|
+
Murree and Kotli Sattian are in Murree district; Talagang and Lawa in
|
|
278
|
+
Talagang; Wazirabad in Wazirabad; Kot Addu and Chowk Sarwar Shaheed in
|
|
279
|
+
Kot Addu; Taunsa and Koh-e-Suleman in Taunsa; the others stay in
|
|
280
|
+
Rawalpindi, Chakwal, Gujranwala, Muzaffargarh and Dera Ghazi Khan.
|
|
281
|
+
Source: the Board of Revenue's list of tehsils by district as on 31
|
|
282
|
+
December 2023, in the Punjab Bureau of Statistics' Statistical Pocket
|
|
283
|
+
Book 2025
|
|
284
|
+
(https://bos.punjab.gov.pk/system/files/Statistical%20Pocket%20Book%202025%20Final.pdf,
|
|
285
|
+
retrieved 2026-11-16). That list also has tehsils created since the
|
|
286
|
+
census (Vehova, Alipur Chatha and others), which are not in this data.
|
|
287
|
+
- **Not confirmed, so `null` (78 tehsils):** the tehsils of Swat, Upper
|
|
288
|
+
Dir, Batagram, Dera Ismail Khan and South Waziristan (Khyber
|
|
289
|
+
Pakhtunkhwa) and of Quetta, Dera Bugti, Pishin, Kech, Khuzdar, Lasbela
|
|
290
|
+
and Jaffarabad (Balochistan). No official list of tehsils by district
|
|
291
|
+
for today's districts could be read for either province.
|
|
292
|
+
- **Divisions** are the census's 30. Divisions created since (Gujrat in
|
|
293
|
+
Punjab, listed on punjab.gov.pk) are not included, and districts created
|
|
294
|
+
since the census have no division here.
|
|
295
|
+
- **Not covered:** Azad Jammu and Kashmir (3 divisions, 10 districts, 32
|
|
296
|
+
tehsils per "AJK at a Glance 2023") and Gilgit-Baltistan. The census tables
|
|
297
|
+
have no rows for them, and no official list of their tehsils was found.
|
|
298
|
+
- **Spelling** is the census's, in title case, with district names changed
|
|
299
|
+
to ours ("UMER KOT" → Umerkot, "KAMBAR SHAHDAD KOT" → Qambar Shahdadkot,
|
|
300
|
+
"TORGHAR" → Tor Ghar).
|
|
301
|
+
- **Repaired by hand.** The letters "LLA" are missing from four names in the
|
|
302
|
+
district tables' text (the PDF prints them, but they do not come out of
|
|
303
|
+
it). They are restored in `data/sources/census-2023-admin-units.csv`:
|
|
304
|
+
|
|
305
|
+
| Census text | Restored to | Evidence |
|
|
306
|
+
| -------------- | --------------- | -------------------------------------------------------- |
|
|
307
|
+
| `AI` | Allai | Allai tehsil of Batagram; KP Development Statistics 2026 |
|
|
308
|
+
| `KAR KAHAR` | Kallar Kahar | Punjab Board of Revenue tehsil list ("Kalar Kahar") |
|
|
309
|
+
| `KAR SAYADDAN` | Kallar Sayaddan | Punjab Board of Revenue tehsil list ("Kallar Syedan") |
|
|
310
|
+
| `TANDO AHYAR` | Tando Allahyar | The census's own province table prints "TANDO ALLAHYAR" |
|
|
91
311
|
|
|
92
312
|
## Public holidays (`holidays.json`)
|
|
93
313
|
|
|
94
314
|
Eid ul Fitr, Eid ul Adha, Ashura and Eid Milad un Nabi dates actually observed
|
|
95
|
-
in 2020–2026
|
|
96
|
-
|
|
315
|
+
in 2020–2026; each entry has a `source` URL, and every source is a Cabinet
|
|
316
|
+
Division notification or an SBP circular letter (checked 2026-11-16; the last
|
|
317
|
+
seven news links, for 2020–2023, were replaced that day with the SBP circular
|
|
318
|
+
that states the same dates). Later years are estimated from the tabular Hijri calendar
|
|
97
319
|
and marked `estimated: true`. Fixed-date holidays follow the years they applied
|
|
98
320
|
in (e.g. Iqbal Day restored in 2022, Youm-e-Takbeer from 2024).
|
|
99
321
|
|
|
322
|
+
## Sales tax rates (`sales-tax-rates.json`)
|
|
323
|
+
|
|
324
|
+
Standard rates only, from 1 July 2019, each with the period it applied, the
|
|
325
|
+
law that sets it and an official document. Edited directly. Reduced, higher
|
|
326
|
+
and sector rates (telecom at 19.5%, restaurants paid by card, Third Schedule
|
|
327
|
+
goods, further tax and so on) are not included. All documents retrieved
|
|
328
|
+
2026-11-18.
|
|
329
|
+
|
|
330
|
+
| Tax | Rate | Applied | Source |
|
|
331
|
+
| ------------------------------------------- | ---- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
332
|
+
| Goods, federal (FBR) | 17% | to 22 February 2023 | Sales Tax Act 1990, s. 3(1); the Finance (Supplementary) Act 2023 replaces "seventeen" with "eighteen" (https://download1.fbr.gov.pk/Docs/20232231921422957Finance(Supplementary)Act,2023.pdf) |
|
|
333
|
+
| Goods, federal (FBR) | 18% | from 23 February 2023 | The same Act, in force at once on 23 February 2023; FBR Circular 01/2023; still 18% in FBR's Sales Tax Act "updated up to 30.06.2026" (https://download1.fbr.gov.pk/Docs/20267171373418951SalesTaxAct1990updatedupto30.06.2026.pdf) |
|
|
334
|
+
| Services, Punjab (PRA) | 16% | whole period | Punjab Sales Tax on Services Act 2012, s. 2(41A) ("Standard Rate" means sixteen percent) and Second Schedule, 17th edition 2026-27 (https://pra.punjab.gov.pk/Downloads/THE-PUNJAB-SALES-TAX-ON-SERVICES-ACT-2012-17th-Edition-2026-2027.pdf) |
|
|
335
|
+
| Services, Sindh (SRB) | 13% | to 30 June 2024 | The Sindh Finance Act 2024 (Sindh Act II of 2024) replaces "13%" with "15%" (https://www.pas.gov.pk/uploads/acts/Sindh%20Act%20No.II%20of%202024.pdf) |
|
|
336
|
+
| Services, Sindh (SRB) | 15% | from 1 July 2024 | The same Act, from 1 July 2024; s. 8(1) of the Sindh Sales Tax on Services Act 2011 as consolidated for 2025-26 (https://www.srb.gos.pk/srb/wp-content/uploads/2026/01/Sindh-Sales-Tax-Act-2011-25-26-2.pdf) |
|
|
337
|
+
| Services, Khyber Pakhtunkhwa (KPRA) | 15% | whole period | KP Finance Act 2019, Second Schedule, from 1 July 2019 (https://kpcode.kp.gov.pk/uploads/The_Khyber_Pakhtunkhwa_Finance_Act_2019.pdf); KP Sales Tax on Services Act 2022, s. 9(1), updated to the Finance Act 2026 (https://kpra.gov.pk/wp-content/uploads/2026/09/KPSTSA-2022-Updated-Finance-act-2026.pdf) |
|
|
338
|
+
| Services, Balochistan (BRA) | 15% | whole period | Balochistan Sales Tax on Services Act 2015, s. 10(1) and Second Schedule, consolidated to the Finance Act 2024 (https://bra.gob.pk/NewsDirectory/2015_BSTS_Act_Ver01.pdf); BRA's FAQ (https://bra.gob.pk/FAQs.aspx) |
|
|
339
|
+
| Services, Islamabad Capital Territory (FBR) | 16% | to 30 June 2022 | ICT (Tax on Services) Ordinance 2001, Schedule, Table 1; the Finance Act 2022 replaces "Sixteen" with "Fifteen" (https://fbr.gov.pk/Budget2022-23/FinanceAct/Finance-Act-2022.pdf) |
|
|
340
|
+
| Services, Islamabad Capital Territory (FBR) | 15% | from 1 July 2022 | The same Act, from 1 July 2022; FBR's ICT Ordinance "updated up to 30.06.2025" (https://download1.fbr.gov.pk/Docs/2025711172945966ICTOUpdatedupto30.06.2025.pdf) |
|
|
341
|
+
|
|
342
|
+
How sure we are:
|
|
343
|
+
|
|
344
|
+
- **Verified** from the Act or Finance Act itself: every change of rate and
|
|
345
|
+
every current rate.
|
|
346
|
+
- **The earlier rates (federal 17%, Sindh 13%, ICT 16%)** are confirmed as the
|
|
347
|
+
rate the amending Act replaced. That they applied all the way back to
|
|
348
|
+
1 July 2019 rests on finding no amendment in between, not on a 2019
|
|
349
|
+
consolidation.
|
|
350
|
+
- **The federal rise to 18%** was first notified by S.R.O. 179(I)/2023 of
|
|
351
|
+
14 February 2023, which is not on FBR's website; the dataset uses
|
|
352
|
+
23 February 2023, when the Finance (Supplementary) Act 2023 took effect.
|
|
353
|
+
- **Balochistan for 2025-26 and 2026-27**: BRA's consolidated Act goes up to
|
|
354
|
+
the Finance Act 2024, and BRA's own FAQ, which is undated, still gives 15%.
|
|
355
|
+
The Balochistan Finance Acts 2025 and 2026 were not found online.
|
|
356
|
+
- **Islamabad Capital Territory after 30 June 2025**: FBR has not published a
|
|
357
|
+
2026 consolidation; the Finance Act 2026 does not amend the ICT Ordinance.
|
|
358
|
+
- In Balochistan, ICT and (before 2022) Khyber Pakhtunkhwa the law has no
|
|
359
|
+
single "standard rate": it is the rate on almost every line of the
|
|
360
|
+
Schedule, which BRA's FAQ and FBR's circular call the standard rate.
|
|
361
|
+
|
|
362
|
+
## Income tax on salary (`income-tax-slabs.json`)
|
|
363
|
+
|
|
364
|
+
The salaried rate table for each tax year: Division I of Part I of the First
|
|
365
|
+
Schedule to the Income Tax Ordinance 2001, clause (2), which applies where
|
|
366
|
+
salary is more than 75% of taxable income. Edited directly. Each year was
|
|
367
|
+
read from FBR's own consolidated Ordinance for that year, and checked against
|
|
368
|
+
the next year's consolidation, whose footnote quotes the table it replaced.
|
|
369
|
+
Every band's fixed amount equals the previous band's fixed amount plus its
|
|
370
|
+
rate on its width (the tests check this). All documents retrieved 2026-11-18.
|
|
371
|
+
|
|
372
|
+
| Tax year | Law | Source |
|
|
373
|
+
| -------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
|
|
374
|
+
| 2020 (2019-20) | Finance Act 2019 | https://download1.fbr.gov.pk/Docs/20199191692232848IncomeTaxOrdinance,2001amendedupto30-06-2019.pdf |
|
|
375
|
+
| 2021 (2020-21) | Finance Act 2019, unchanged by Finance Act 2020 | https://download1.fbr.gov.pk/Docs/202011414113915861I.T.OrdinanceAmendedupto(30-06-2020).pdf |
|
|
376
|
+
| 2022 (2021-22) | Finance Act 2019, unchanged by Finance Act 2021 | https://download1.fbr.gov.pk/Docs/20217141672549772IncomeTaxOrdinanceAmendedupto30.06.2021.pdf |
|
|
377
|
+
| 2023 (2022-23) | Finance Act 2022 | https://download1.fbr.gov.pk/Docs/202412215123222278IncomeTaxOrdinanceAmendedupto30.06.2022.pdf |
|
|
378
|
+
| 2024 (2023-24) | Finance Act 2023 | https://download1.fbr.gov.pk/Docs/202412215122448762IncomeTaxOrdinance,2001Amendedupto30.06.2023.pdf |
|
|
379
|
+
| 2025 (2024-25) | Finance Act 2024 | https://download1.fbr.gov.pk/Docs/2024751675120641IncomeTaxOrdinance,2001-amended-upto30.06.2024.pdf |
|
|
380
|
+
| 2026 (2025-26) | Finance Act 2025 | https://download1.fbr.gov.pk/Docs/2025881983148210Income-Tax-Ordinance,-2001-Amended-upto-31.07.2025.pdf |
|
|
381
|
+
| 2027 (2026-27) | Finance Act 2026 | Finance Act 2026 (primary) and two further sources, listed below |
|
|
382
|
+
|
|
383
|
+
Tax year 2027 has three sources, all retrieved 2026-11-18:
|
|
384
|
+
|
|
385
|
+
1. **Primary: the Finance Act, 2026**, Gazette of Pakistan (Extraordinary),
|
|
386
|
+
Part I, 26 June 2026
|
|
387
|
+
(https://download1.fbr.gov.pk/Docs/20266291261044366FinanceAct2026.pdf).
|
|
388
|
+
- Section 5(44)(a)(i) substitutes the table in clause (2) of Division I,
|
|
389
|
+
Part I, First Schedule (Gazette page 580). Its eight bands, fixed
|
|
390
|
+
amounts and rates match `income-tax-slabs.json` exactly.
|
|
391
|
+
- Section 1(2) brings the Act into force on 1 July 2026, the first day of
|
|
392
|
+
tax year 2027.
|
|
393
|
+
- Section 5(2)(b) replaces the 9% salaried surcharge in the proviso to
|
|
394
|
+
section 4AB with "no surcharge shall be payable".
|
|
395
|
+
- This is the URL in the dataset's `source` field for 2027.
|
|
396
|
+
2. **FBR's explanation: Circular No. 02 of 2026-27 (Income Tax)**, C. No.
|
|
397
|
+
1(50)S(ITP)/2026, 8 September 2026
|
|
398
|
+
(https://download1.fbr.gov.pk/Docs/202698139527880CircularNo.2of2026-27.pdf).
|
|
399
|
+
- Paragraph 7 restates the same table.
|
|
400
|
+
- Paragraph 8 confirms that the 9% surcharge on salaried individuals is
|
|
401
|
+
withdrawn, while the 10% surcharge on other individuals and associations
|
|
402
|
+
of persons continues.
|
|
403
|
+
- The circular does not name a tax year, which is why the commencement
|
|
404
|
+
comes from the Act.
|
|
405
|
+
3. **FBR's consolidated Ordinance**
|
|
406
|
+
(https://download1.fbr.gov.pk/Docs/2026724177725705IncomeTaxOrdinanace2001.pdf).
|
|
407
|
+
It prints the same table, with a footnote quoting the 2026 table it
|
|
408
|
+
replaced.
|
|
409
|
+
|
|
410
|
+
How sure we are, and what is left out:
|
|
411
|
+
|
|
412
|
+
- **Verified** from FBR's consolidated Ordinance for each year. For 2027 the
|
|
413
|
+
table was also checked against the Finance Act, 2026 as gazetted and FBR
|
|
414
|
+
Circular No. 02 of 2026-27. For earlier years the Finance Act texts
|
|
415
|
+
(Gazette) were not read; FBR's consolidations are the source.
|
|
416
|
+
- **Not applied** (out of scope): the surcharge under section 4AB (from tax
|
|
417
|
+
year 2025: 10% of the tax over Rs 10 million of taxable income; 9% for
|
|
418
|
+
salaried individuals in 2026; none for salaried individuals in 2027), tax
|
|
419
|
+
credits, exemptions, the separate rate for pension from a former employer
|
|
420
|
+
(2026 onwards: 0% up to Rs 10 million, 5% above), and withholding
|
|
421
|
+
adjustments.
|
|
422
|
+
- Tax is rounded half up to the paisa; the Ordinance's own rounding to whole
|
|
423
|
+
rupees is left to the caller.
|
|
424
|
+
|
|
425
|
+
## Urdu alphabetical order (no dataset)
|
|
426
|
+
|
|
427
|
+
`compareUrdu` follows the Unicode CLDR collation tailoring for Urdu
|
|
428
|
+
(`common/collation/ur.xml`, "standard", CLDR release 49, unchanged since
|
|
429
|
+
2015), https://github.com/unicode-org/cldr/blob/release-49/common/collation/ur.xml,
|
|
430
|
+
retrieved 2026-11-18. Its own reference is the CRULP/PAN Localization paper
|
|
431
|
+
"Urdu Encoding and Collation Sequence". The government's National Language
|
|
432
|
+
Promotion Department (https://nlpd.gov.pk) does not publish a sort order
|
|
433
|
+
online, so CLDR is the order cited. The implementation was checked against
|
|
434
|
+
ICU's `ur` collator (Node.js, CLDR 48, identical rules) on 200,000 random
|
|
435
|
+
pairs of Urdu words.
|
|
436
|
+
|
|
437
|
+
## Electricity and gas bill numbers
|
|
438
|
+
|
|
439
|
+
No dataset: `parseElectricityRef` and `validateGasConsumerNumber` check the
|
|
440
|
+
formats that the utilities' own bill pages ask for. All pages were retrieved
|
|
441
|
+
on 2026-11-18.
|
|
442
|
+
|
|
443
|
+
- **DISCO reference number**: 14 digits, with urban or rural chosen
|
|
444
|
+
separately (`U`/`R`), on PITC's bill pages for all 11 companies
|
|
445
|
+
(https://bill.pitc.com.pk/lescobill and the same for gepco, fesco, iesco,
|
|
446
|
+
mepco, pesco, hazeco, hesco, sepco, qesco and tesco). PITC's illustration
|
|
447
|
+
groups it as 2 + 5 + 7 digits, which is how `formatted` shows it.
|
|
448
|
+
- **DISCO customer ID**: 10 digits, or 11 for LESCO (the same PITC pages).
|
|
449
|
+
- **K-Electric account number**: "13 digits KE Account Number starting from
|
|
450
|
+
04000" (https://beta.ke.com.pk/know-your-area-status/ and
|
|
451
|
+
https://ke.com.pk/bills-e-payments/). K-Electric says its contract and
|
|
452
|
+
consumer numbers are for its internal use, so they are not accepted.
|
|
453
|
+
- **SNGPL consumer number**: 11 digits
|
|
454
|
+
(https://www.sngpl.com.pk/login.jsp?mdids=85).
|
|
455
|
+
- **SSGC customer number**: "10-digit Customer Number"
|
|
456
|
+
(https://viewbill.ssgc.com.pk/web/).
|
|
457
|
+
- **Not published**: what the reference number's digit groups mean, which
|
|
458
|
+
digits belong to which DISCO, and any check digit. So `disco` is `null`
|
|
459
|
+
except for K-Electric, and only the format is checked. IESCO also notes
|
|
460
|
+
that reference numbers can change
|
|
461
|
+
(https://www.iesco.com.pk/search-reference-number).
|
|
462
|
+
|
|
463
|
+
## Couriers
|
|
464
|
+
|
|
465
|
+
No dataset: `mapCourierStatus` maps only the statuses a courier documents
|
|
466
|
+
publicly. All pages were retrieved on 2026-11-18.
|
|
467
|
+
|
|
468
|
+
- **PostEx**: "Merchant API Integration Guide", version M- v4.1.9 (undated):
|
|
469
|
+
order status IDs 1 to 9 and 15 to 18 (§3.15) and tracking history codes
|
|
470
|
+
0001 to 0008 and 0013 (§3.8). The guide is PostEx's own, but it is hosted
|
|
471
|
+
on Amazon S3
|
|
472
|
+
(https://merchant-api-guide.s3.ap-south-1.amazonaws.com/PostEx-COD_API_Integration_Guide_V4.1.9.pdf)
|
|
473
|
+
and not linked from postex.pk. Its history codes 0002, 0006 and 0007 all
|
|
474
|
+
read "Returned"; "Package on Root" is mapped as written and also as "on
|
|
475
|
+
route".
|
|
476
|
+
- **Leopards**: only "Returned to Shipper", defined in its e-commerce FAQ
|
|
477
|
+
(https://ecom.leopardscourier.com/faqs). Its API documentation site
|
|
478
|
+
(https://merchantapi.leopardscourier.com) has no content.
|
|
479
|
+
- **TCS, M&P, Trax and BlueEx**: no public status list. Their API documents
|
|
480
|
+
are behind merchant or developer logins, so nothing is mapped. Copies on
|
|
481
|
+
third-party sites were not used.
|
|
482
|
+
- **Tracking numbers**: no courier documents a format, so there is no
|
|
483
|
+
tracking-number detection. PostEx's guide only uses the placeholder
|
|
484
|
+
`CX-XXXXXXXXXXX`.
|
|
485
|
+
|
|
486
|
+
`normalizeCityForCourier`'s short forms (`LHR`, `Khi`, `Pindi`, `ISB`, `FSD`,
|
|
487
|
+
the former name Lyallpur, Urdu names and so on) are common usage, not an
|
|
488
|
+
official list. Each maps to a city in `cities.json`.
|
|
489
|
+
|
|
490
|
+
## FBR Digital Invoicing
|
|
491
|
+
|
|
492
|
+
No dataset: `buildFbrInvoice` and `validateFbrInvoice` follow these
|
|
493
|
+
documents, retrieved on 2026-11-18:
|
|
494
|
+
|
|
495
|
+
- **PRAL, "Technical Specification for DI API", version 1.12** (issued
|
|
496
|
+
7 April 2025, last updated 24 July 2025):
|
|
497
|
+
https://download1.fbr.gov.pk/Docs/20257301172130815TechnicalDocumentationforDIAPIV1.12.pdf,
|
|
498
|
+
linked from https://www.fbr.gov.pk/di-technical-assistance/173967/173970.
|
|
499
|
+
PRAL's download index (https://dicrm.pral.com.pk/assets/docs/documents.json)
|
|
500
|
+
lists it as the current version. It gives the fields, the sale types and
|
|
501
|
+
the error codes.
|
|
502
|
+
- **PRAL, "Error Message Guide (Sales)"**:
|
|
503
|
+
https://dicrm.pral.com.pk/assets/docs/Manuals/Error%20Message%20Guide%20-%20(Sales).pdf.
|
|
504
|
+
This is the source of the rules on numbers (0300: not negative or empty;
|
|
505
|
+
0302: at most 2 decimals, 4 for quantity), on SROs (0077, 0078) and on
|
|
506
|
+
reduced-rate goods (0091).
|
|
507
|
+
- **PRAL, "DI Scenarios Description for Sandbox Testing"** (v1.11): the sample
|
|
508
|
+
invoices, used for the arithmetic examples (1000 × 18% = 180; Rs.3 × 12 =
|
|
509
|
+
36; retail price 100 × 18% = 18 for Third Schedule goods).
|
|
510
|
+
- **Legal basis**: S.R.O. 69(I)/2025, Sales Tax Rules chapter XIV
|
|
511
|
+
(https://download1.fbr.gov.pk/SROs/2025129141598258SRO69(I)2025.pdf).
|
|
512
|
+
|
|
513
|
+
Where the documents disagree or are silent, the code does this:
|
|
514
|
+
|
|
515
|
+
- **Key names** are those of the specification's sample JSON
|
|
516
|
+
(`invoiceType`, `buyerRegistrationType`), not the misspellings in its field
|
|
517
|
+
table, and `invoiceType` is `Sale Invoice` (the table says "Sales
|
|
518
|
+
Invoice", but the samples and the document type API say "Sale Invoice").
|
|
519
|
+
- **NTN length** is 7 (error 0002's text also mentions 9, but 0401, 0402 and
|
|
520
|
+
the guide say 7 or 13).
|
|
521
|
+
- **Rounding**: none is documented. Sales tax is rounded half up to the
|
|
522
|
+
paisa, and a declared tax within one paisa of it is accepted. This is the
|
|
523
|
+
library's choice.
|
|
524
|
+
- **Sale types** are compared ignoring case and spaces, because the
|
|
525
|
+
specification's table and its samples differ in capitals.
|
|
526
|
+
- **Not checked**: anything that needs FBR's reference APIs or records
|
|
527
|
+
(registration, provinces, HS codes, units, rates, sale types, SRO lists,
|
|
528
|
+
the original invoice of a debit note). There are no string length limits
|
|
529
|
+
in the specification, so none are checked.
|
|
530
|
+
|
|
100
531
|
## CNIC
|
|
101
532
|
|
|
102
533
|
First digit = province of registration, per FBR's tax-ID description filed with
|
|
103
534
|
the OECD (1 Khyber Pakhtunkhwa, 2 former FATA, 3 Punjab, 4 Sindh, 5
|
|
104
535
|
Balochistan, 6 Islamabad, 7 Gilgit-Baltistan). `8` for Azad Jammu and Kashmir
|
|
105
536
|
comes from secondary sources only. Last digit odd = male, even = female.
|
|
537
|
+
|
|
538
|
+
## Passport numbers
|
|
539
|
+
|
|
540
|
+
`validatePassport` accepts two letters followed by seven digits (`AB1234567`).
|
|
541
|
+
DGIP does not publish the format, and its forms only ask for "Passport Number".
|
|
542
|
+
|
|
543
|
+
- **Source:** the EU Council's PRADO register gives this pattern for the 2013
|
|
544
|
+
ordinary passport
|
|
545
|
+
(https://www.consilium.europa.eu/prado/en/PAK-AO-02003/index.html). The page
|
|
546
|
+
sits behind a bot check, so it was confirmed through search-result text, not
|
|
547
|
+
the page itself.
|
|
548
|
+
- **Observed on real passports:** the maintainer checked real ordinary
|
|
549
|
+
(green) and official (blue) Pakistani passports in November 2026; their
|
|
550
|
+
numbers have this shape. No numbers are recorded here.
|
|
551
|
+
- **Fits ICAO Doc 9303:** the document-number field is 9 characters, with the
|
|
552
|
+
check digit stored separately in the machine-readable zone
|
|
553
|
+
(https://www.icao.int/publications/Documents/9303_p4_cons_en.pdf).
|
|
554
|
+
- **Still unconfirmed:** diplomatic (red) passports and the e-passport
|
|
555
|
+
variants (2022 onwards), and what the letters mean. A real number in another
|
|
556
|
+
shape will be rejected; treat `false` as unusual, not fake.
|
|
557
|
+
|
|
558
|
+
## Vehicle registration plates
|
|
559
|
+
|
|
560
|
+
`parseVehiclePlate` accepts 1–4 letters, then 1–4 digits, optionally followed
|
|
561
|
+
by a two-digit year after a separator (`LEA-1234-19`). There is no national
|
|
562
|
+
format: each province's excise department sets its own.
|
|
563
|
+
|
|
564
|
+
- **Reported formats** (Wikipedia, partly inconsistent,
|
|
565
|
+
https://en.wikipedia.org/wiki/Vehicle_registration_plates_of_Pakistan):
|
|
566
|
+
Sindh cars 3 letters + 3 digits; Islamabad and Balochistan 2 letters + 3
|
|
567
|
+
digits; Khyber Pakhtunkhwa 2 letters + 4 digits; Gilgit-Baltistan 3 letters +
|
|
568
|
+
2 digits; AJK motorcycles and public transport 4 letters + 3 digits; older
|
|
569
|
+
Punjab plates 4 digits plus a two-digit year.
|
|
570
|
+
- **Number length:** Punjab's excise department auctions registration marks of
|
|
571
|
+
1 to 4 digits (https://excise.punjab.gov.pk/auctions).
|
|
572
|
+
- **Recent changes:** numbers now stay with the owner in Islamabad
|
|
573
|
+
(https://profit.pakistantoday.com.pk/2025/07/20/ict-excise-deptt-introduces-personalized-number-plates-digital-cards-online-tax-payment/),
|
|
574
|
+
Khyber Pakhtunkhwa
|
|
575
|
+
(https://arynews.tv/kp-new-vehicle-registration-number-plate-system-sep-17-2025)
|
|
576
|
+
and Sindh, from 16 February 2026
|
|
577
|
+
(https://profit.pakistantoday.com.pk/2026/02/16/sindh-enforces-cnic-based-number-plates-owners-can-retain-registration-marks/).
|
|
578
|
+
Punjab announced new series from May 2026
|
|
579
|
+
(https://propakistani.pk/2026/04/29/punjab-to-launch-five-new-vehicle-number-series/)
|
|
580
|
+
without publishing their layout.
|
|
581
|
+
- **Not checked:** series letters against districts (no official list, e.g. for
|
|
582
|
+
`LEA`/`LEB` = Lahore), and labels printed on the plate such as "ICT" or
|
|
583
|
+
"PUNJAB", which are not part of the number.
|
package/LICENSE
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
MIT License
|
|
2
2
|
|
|
3
|
-
Copyright (c) 2026 PakDataKit Contributors
|
|
3
|
+
Copyright (c) 2026 Muzamil Chaudhery and PakDataKit Contributors
|
|
4
4
|
|
|
5
5
|
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
6
|
of this software and associated documentation files (the "Software"), to deal
|
package/NOTICE
ADDED
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
PakDataKit
|
|
2
|
+
https://github.com/chmuzamil/pakdatakit
|
|
3
|
+
|
|
4
|
+
Origin
|
|
5
|
+
- First commit: 29 May 2026, commit bdc426a (git history).
|
|
6
|
+
- First npm release: pakdatakit 1.0.0, 29 May 2026 (npm registry).
|
|
7
|
+
|
|
8
|
+
Licence and reuse
|
|
9
|
+
PakDataKit is released under the MIT licence (see LICENSE). This covers the
|
|
10
|
+
code of every port, the datasets in data/ and the shared test vectors in
|
|
11
|
+
test-vectors/. Anyone who copies or adapts any substantial part of it, in
|
|
12
|
+
any language, must keep this copyright notice and the licence text:
|
|
13
|
+
|
|
14
|
+
Copyright (c) 2026 Muzamil Chaudhery and PakDataKit Contributors
|