# Data sources

> Where every pakdatakit dataset comes from, how many records it has, and when it was last checked (data version 2026-11-18).

Source: https://pakdatakit.dev/data/

**Data version: 2026-11-18.** Every port ships the same files from `data/`, and the shared test vectors check that they agree.

| File | Records | Size |
| --- | --- | --- |
| [`area-codes.json`](https://github.com/chmuzamil/pakdatakit/blob/main/data/area-codes.json) | 114 | 6 KB |
| [`banks.json`](https://github.com/chmuzamil/pakdatakit/blob/main/data/banks.json) | 50 | 5 KB |
| [`cities.json`](https://github.com/chmuzamil/pakdatakit/blob/main/data/cities.json) | 226 | 14 KB |
| [`districts.json`](https://github.com/chmuzamil/pakdatakit/blob/main/data/districts.json) | 177 | 12 KB |
| [`divisions.json`](https://github.com/chmuzamil/pakdatakit/blob/main/data/divisions.json) | 30 | 5 KB |
| [`holidays.json`](https://github.com/chmuzamil/pakdatakit/blob/main/data/holidays.json) | 7 | 5 KB |
| [`income-tax-slabs.json`](https://github.com/chmuzamil/pakdatakit/blob/main/data/income-tax-slabs.json) | 8 | 10 KB |
| [`networks.json`](https://github.com/chmuzamil/pakdatakit/blob/main/data/networks.json) | 53 | 2 KB |
| [`post-offices.json`](https://github.com/chmuzamil/pakdatakit/blob/main/data/post-offices.json) | 2,560 | 341 KB |
| [`postal-codes.json`](https://github.com/chmuzamil/pakdatakit/blob/main/data/postal-codes.json) | 457 | 66 KB |
| [`sales-tax-rates.json`](https://github.com/chmuzamil/pakdatakit/blob/main/data/sales-tax-rates.json) | 9 | 3 KB |
| [`tehsils.json`](https://github.com/chmuzamil/pakdatakit/blob/main/data/tehsils.json) | 591 | 91 KB |

PakDataKit's datasets live in `data/` and are generated by
`scripts/generate-data.mjs` (except `networks.json`, `area-codes.json`,
`holidays.json` and `sales-tax-rates.json`, which are edited directly). Two official lists are kept as
extracted CSV files in `data/sources/` and read by the generator: Pakistan
Post's post code directory and the 2023 census's administrative units. The exported `dataVersion` is the
date the data was last checked.

**Data version: 2026-11-18**

The datasets were audited against official sources on 16 November 2026;
[AUDIT.md](https://github.com/chmuzamil/pakdatakit/blob/main/AUDIT.md) has the findings, the fixes made and what is still open.

Official bodies (PTA, NADRA, SBP, Pakistan Post) publish few machine-readable
lists, so some entries rest on secondary sources. Each section says how sure we
are. To correct an entry, open an issue or pull request with a source.

## Banks (`banks.json`): IBAN bank codes

SBP does not publish a list of IBAN bank codes, and IBAN codes do not always
match SWIFT BIC prefixes (e.g. Silkbank is `SAUD`). Codes are therefore checked
against real IBANs. Names follow SBP's lists of regulated institutions
(https://www.sbp.org.pk/sbp-regulated-institutions/commercial-banks and
.../microfinance-banks, retrieved 2026-11-16), with a former name kept in
brackets where people still search for it.

- **Confirmed from IBANs printed by SBP:** 35 codes, from SBP's list of dam
  fund accounts at every bank
  (https://archive.sbp.org.pk/notifications/FD/DamFund/Detail-1.pdf, undated,
  about 2018, retrieved 2026-11-16): `AIIN`, `ABPA`, `ASCM`, `ALFH`, `BAHL`,
  `BKIP`, `KHYB`, `BPUN`, `BKCH`, `CITI`, `DEUT`, `DUIB`, `FAYS`, `FWOM`,
  `HABB`, `MPBL`, `ICBK`, `JSBL`, `MUCB`, `MCIB`, `MEZN`, `NBPA`, `SAMB`,
  `SAUD`, `SIND`, `SMES`, `SONE`, `SCBL`, `SUMB`, `UNIL`, `ZTBL` (Zarai
  Taraqiati Bank), `TMFB`, `WMBL`, `FMFB` and `SMFB` (Sindh Microfinance
  Bank). The same list shows an `SBPP` IBAN in use. `ZTBL` and `SMFB` were
  added on 2026-11-16 from this list. (It prints ICBC's IBAN with a digit `1`
  for the `I`; the checksum is only valid with `ICBK`.)
- **Also confirmed from IBANs printed by SBP:** `KHBL` (Khushhali), `JCMA`
  (Mobilink Microfinance Bank), `FINC` (ABHI, as FINCA), `UMBL`, `NRSP` and
  `APNA`, from SBP's account lists for the Prime Minister's Flood Relief Fund
  2022 (https://archive.sbp.org.pk/IBANs-of-PM-Flood-Relief-Fund.pdf) and the
  2023 relief fund for Türkiye and Syria
  (https://archive.sbp.org.pk/ReliefFund-Turkiye.pdf), both retrieved
  2026-11-16. That makes 41 codes confirmed by SBP documents.
- **Confirmed from published IBANs on smaller sites:** `SADA` (SadaPay), `NAYA`
  (NayaPay).
- **Confirmed from real account IBANs shared by a maintainer:** `RQMI` (Raqami
  Islamic Digital Bank) and `MSHQ` (Mashreq Bank Pakistan), both digital banks.
- **Legacy codes with no official source:** `MCBL`, `NBPB`, `TAMW` and `NIBP`.
- **Not included, because no code could be confirmed:** Punjab Provincial
  Cooperative Bank, LOLC Microfinance Bank (formerly Pak Oman), Halan
  Microfinance Bank (formerly Advans), ASA Microfinance Bank, the EMIs Finja,
  Akhtar Fuiou Technologies, E-Processing Systems, Wemsol and YAP Pakistan,
  HugoBank, KT Bank and Bank of AJK. A second search on 2026-11-16 (SBP's
  relief-fund lists and each institution's own website) found no printed IBAN
  for any of them.
- **Types** follow SBP's groups on its list of regulated institutions:
  "Public Sector Commercial Banks" are `public-sector` (National Bank of
  Pakistan, Sindh Bank, The Bank of Khyber, The Bank of Punjab), "Local
  Private Banks" are `commercial`, and "Islamic", "Foreign", "Specialized"
  and "Digital" banks have the type of the same name.
- **Spelling.** Names use each bank's own styling ("Bank Alfalah Limited",
  "Bank Al Habib Limited", "BankIslami Pakistan Limited", "Citibank N.A.
  Pakistan"). SBP's list spells some differently, and not consistently
  ("Bank Al-Falah Limited", "Bank Al-Habib Limited", "Al-Baraka Bank
  (Pakistan) Limited", "Bank Islami Pakistan Limited", "Citi Bank N.A",
  "Industrial & Commercial Bank of China", "Allied Bank limited"), so it is
  recorded here and not copied.
- **Closed:** `SMES` → "SME Bank Limited (in liquidation)", `active: false`.
  SBP cancelled its licence and de-scheduled it on 17 March 2025
  (https://archive.sbp.org.pk/notifications/bprd/2025/ntf6.htm). `NIBP` was
  de-scheduled on 7 July 2017 on its merger into MCB Bank
  (https://archive.sbp.org.pk/notifications/bprd/2017/ntf2.htm).
- **Merged or renamed** banks keep their code with the current name, e.g.
  `SAUD` → "Silkbank Limited (merged into United Bank Limited)" (de-scheduled
  by SBP on 10 March 2025,
  https://archive.sbp.org.pk/notifications/bprd/2025/ntf4.htm) and `TMFB` →
  "Easypaisa Bank Limited" (a scheduled bank from 23 January 2025,
  https://archive.sbp.org.pk/notifications/bprd/2025/ntf1.htm).

## Mobile networks (`networks.json`)

`03XX` prefixes and the operator each was originally allocated to. PTA has no
current operator-by-prefix table. Its National Numbering Plan 2008 paper
(https://www.pta.gov.pk/assets/media/nnp_08_final.pdf, retrieved 2026-11-16)
gives the two-digit allocations: 30 Mobilink (Jazz), 31 Paktel (now Zong), 32
Warid (now Jazz), 33 Ufone, 34 Telenor, 35 SCO, 36 Instaphone, and 37 to 39
"for future use". Individual prefixes are cross-checked with Google
libphonenumber and operator announcements.

- `0329` (Jazz) and `0355` (SCO) included.
- `0370`–`0371` (Zong) included, from libphonenumber only. **Unverified:**
  two searches in November 2026 (PTA's annual reports for 2021 to 2024, its
  numbering documents and licensee list, the ITU page for Pakistan and
  zong.com.pk) found no official document that gives 037x to an operator. `0372`–`0379` are **not**
  included, as no allocation or use was found.
- `0364` (Instaphone, licence cancelled in 2008) is not included.
- `034x` is labelled Telenor, the original allocation. Telenor Pakistan was
  merged into PTML (Ufone) in July 2026: PTCL announced the "successful
  completion of the amalgamation" on 2 July 2026
  (https://ptcl.com.pk/Home/PressReleaseDetail/?ItemId=934&linkId=130,
  retrieved 2026-11-16). The label is kept because the dataset records the
  operator a prefix was allocated to, no new brand has been announced
  officially (PTCL still writes "Ufone 5G"), and PTA's own pages still list
  Telenor Pakistan. With number portability, the current operator can differ
  for any prefix.

## Landline area codes (`area-codes.json`)

114 codes, from the numbering plan PTA sent to the ITU on 9 November 2021
(https://www.itu.int/dms_pub/itu-t/oth/02/02/T02020000A10002PDFE.pdf,
retrieved 2026-11-16), which lists every code with its district. The 73 codes
held before November 2026 came from PTCL's national dialling-code list
(https://ptcl.com.pk/Info/National-Dialing-Codes) and all appear in the ITU
plan with the same districts.

- **Added 2026-11-16 from the ITU plan:** 18 codes in Balochistan (`822`
  Zhob to `856` Awaran), 8 in Khyber Pakhtunkhwa (`924` Khyber and Mohmand,
  `932` Malakand, `939` Buner, `942` Bajaur, `944` Upper Dir, `945` Lower
  Dir, `965` South Waziristan, `996` Shangla), 7 in Gilgit-Baltistan (`5811`
  Gilgit to `5817` Astore) and 8 in Azad Jammu and Kashmir (`5821` Neelum to
  `5828` Bhimber).
- Names are the districts the plan gives, spelt as in `districts.json` so
  that `getAreaCode` finds them: the plan writes "Neelum", "Sudonthi",
  "Bhimer" and "K.Abdullah / Pishin" for Neelam, Sudhnuti, Bhimber and Killa
  Abdullah and Pishin. `832` is listed there as Bolan, the former name of
  Kachhi district; both names find it. For the two districts split since
  2021, the successors are listed with the plan's name: `835` Dera Bugti,
  North Dera Bugti and South Dera Bugti; `965` South Waziristan, Lower South
  Waziristan and Upper South Waziristan.
- PTCL's own list differs for Azad Jammu and Kashmir (Muzaffarabad "58",
  Kotli "574") and has no Mirpur or Gilgit entry. The ITU plan is the newer
  list from PTA, so it is followed.
- **Number lengths** are not taken from the ITU plan (its length table could
  not be read reliably). The patterns in `numbers.ts` come from
  libphonenumber's PK metadata (v9.0.41), which already accepted numbers in
  all 41 added codes: ten digits in all for the `58xx` codes, so a four-digit
  code is followed by six digits.

## Districts (`districts.json`)

177 districts as of October 2026: Punjab 41, Sindh 30, Khyber Pakhtunkhwa 40,
Balochistan 41, Gilgit-Baltistan 14, Azad Jammu and Kashmir 10, Islamabad 1.

> **Unverified: Central Dir, Allai and Paharpur** (Khyber Pakhtunkhwa). They
> rest on a news report of January 2026, not on a notification. Official
> pages updated in November 2026 do not show them: Malakand Division lists
> 10 districts without Central Dir (cmd.kp.gov.pk), Hazara Division lists 8
> without Allai (chd.kp.gov.pk), and the KP Bureau of Statistics'
> Development Statistics 2026 has Allai as a tehsil of Batagram and Paharpur
> as a tehsil of Dera Ismail Khan (all retrieved 2026-11-16). They are kept
> until a notification settles it either way. Nine more districts are also
> not confirmed on an official page; see the end of this section.

- **Khyber Pakhtunkhwa** (APP, January 2026: "increased to 40"): Lower and Upper
  South Waziristan (2022), Central Dir and Allai (January 2023), Paharpur
  (November 2025), Bar Swat (January 2026; reported as "Upper Swat" before
  the Board of Revenue notification of 27 January 2026).
- **Balochistan** (Revenue Department notification, 8 July 2026; Dawn,
  ProPakistani): Quetta split into Quetta East and Quetta West; Dera Bugti
  became South Dera Bugti and Upper Dera Bugti became North Dera Bugti; new
  Barshore, Tump and Wadh districts; Hub and Usta Muhammad (2022). Taftan is not
  included: no notification was found and the official count of 41 is reached
  without it.
- **Punjab:** Taunsa, Kot Addu, Murree, Wazirabad and Talagang (2022). A 2026
  notification of four more districts was confirmed fake.
- **Sindh:** proposed Karachi district renames (2024) were not found notified,
  so current names are kept.
- Former names (Quetta, Dera Bugti, Upper Dera Bugti, South Waziristan, Upper
  Swat) still resolve in `getDistrictProvince`.
- **Official confirmation, checked 2026-11-16** (details in AUDIT.md,
  section 9). Confirmed on official pages: Murree, Talagang, Wazirabad, Kot
  Addu and Taunsa (Punjab Board of Revenue list); Lower and Upper South
  Waziristan and Hub (Election Commission delimitation report, 2023); Bar
  Swat (Malakand Division's website); Usta Muhammad, Barshore and Tump
  (Balochistan budget documents, June 2026). **Not confirmed on any official
  page that could be read:** Central Dir, Allai and Paharpur (Khyber
  Pakhtunkhwa's divisional websites and its Development Statistics 2026
  still show Allai and Paharpur as tehsils and list no Central Dir); Quetta
  East and West, North and South Dera Bugti and Wadh (Balochistan); and
  Darel, Tangir, Gupis-Yasin and Roundu (Gilgit-Baltistan's 2024-25
  development programme treats them as sub-divisions). These stay in the
  dataset on the strength of the notifications and reports cited above, and
  are the entries most likely to need correcting.

## Cities (`cities.json`)

District headquarters and major towns, plus every city that has a postal code
in `postal-codes.json`, each mapped to its province.

## Postal codes (`postal-codes.json`, `post-offices.json`)

Both files come from Pakistan Post's "Post Code Directory of Delivery Post
Offices" (Part I), a 45-page PDF dated February 2021
(https://www.pakpost.gov.pk/images/national%20post%20code%20directory.pdf,
retrieved 2026-11-16). Its office name, code, account office and province
columns are extracted to `data/sources/pakpost-delivery-post-offices.csv`
(2,564 rows), and `scripts/generate-data.mjs` builds both files from it.

- **`post-offices.json`** (2,560 entries, for `getPostOffice` and
  `searchPostOffices`): every office, as `code`, `office` (the directory's
  name in title case), `town`, `district` and `province`. The directory
  lists four codes twice, for the same place under two spellings (`22190`,
  `40520`, `56320`, `63050`); the first row is kept.
- **`postal-codes.json`** (457 entries, for `getCityByPostalCode`,
  `getPostalCode`, `getPostalCodes`, `getPostalAreas` and
  `searchPostalCodes`): only the offices that belong to a city in
  `cities.json`, as `city`, `postalCode`, `area` (the office name),
  `province`, and `district` and `primary` where they apply.
- **Which city an office belongs to.** The directory has no city column, so
  this is worked out:
  1. the 110 entries checked by hand before the import keep their city
     (including the eight codes corrected in November 2026);
  2. an office named after a city in `cities.json`, in the same province,
     belongs to that city ("ABBOTTABAD GPO" → Abbottabad);
  3. every office under the Karachi, Lahore and Islamabad account offices
     belongs to that city;
  4. an office whose name starts or ends with the city of its own account
     office belongs to that city ("GULISTAN COLONY, FAISALABAD").

  Any other office is in a town or village that is not on the city list. It
  is only in `post-offices.json`, where `town` is the office's own name
  ("Dulmial"); `getCityByPostalCode` returns `null` for it.

- **District** is given only where the town is the headquarters a district
  is named after (349 offices). An account office can serve several
  districts, so it is not used to guess one.
- **Province** is the directory's, with its spelling normalised ("Azad
  Kashmir" → Azad Jammu and Kashmir, "Federal Capital" → Islamabad Capital
  Territory, and the misprints "Punjba" and "SIndh").
- **Primary.** `getPostalCode(city)` returns the hand-checked code for the 95
  cities that had one. For 63 more cities it returns the code of the office
  named "<city> GPO", or else the office named after the city.
- **Names** are converted from the directory's capitals to title case; its
  spellings are kept, including misprints ("Islamabad Primr Minister
  Sectt.").
- **Not included:** the 740 or so non-delivery post offices of Part II
  (https://www.pakpost.gov.pk/images/LIST%20OF%20NON%20DELIVERY%20POs.pdf).
- The directory is dated 2021. Pakistan Post's web table
  (https://www.pakpost.gov.pk/postcodes.php) is missing many offices, so it
  is not the source; it was used for the spot-check below.

## Divisions and tehsils (`divisions.json`, `tehsils.json`)

From Table 1 of the 2023 census (Pakistan Bureau of Statistics), which lists
every administrative unit with its area and population. Retrieved 2026-11-16:

- tehsils by district:
  https://www.pbs.gov.pk/wp-content/uploads/census_tables/tables/table_1_punjab_districts.pdf
  and the same file name for `sindh`, `kp` and `balochistan`, plus
  `table_1_islamabad.pdf`;
- districts by division: `table_1_punjab_province.pdf` and the same for the
  other three provinces.

The rows are extracted to `data/sources/census-2023-admin-units.csv`. The
totals match the census report's Table 1.1: **30 divisions, 136 districts and
591 tehsil-level units** (Punjab 146, Sindh 138, Khyber Pakhtunkhwa 148,
Balochistan 158, Islamabad 1).

- **Tehsil-level units** are what the census counts: 306 tehsils, 107
  talukas (Sindh), 134 sub-divisions (Karachi, the merged districts of Khyber
  Pakhtunkhwa and much of Balochistan), 43 sub-tehsils (Balochistan) and one
  de-excluded area (Rajanpur). Each entry has a `type`.
- **Census district.** Every tehsil has a `censusDistrict`: the district it
  was in at the census. The census had 136 districts; `districts.json` has
  the 177 of today. Three census districts have since been split and are no
  longer district names: Quetta, Dera Bugti and South Waziristan.
- **Current district.** `currentDistrict` is the same as `censusDistrict`
  for the 119 census districts that have not lost territory to a new
  district. For tehsils of the 17 that have (Rawalpindi, Chakwal,
  Gujranwala, Muzaffargarh, Dera Ghazi Khan, South Waziristan, Upper Dir,
  Batagram, Dera Ismail Khan, Swat, Lasbela, Jaffarabad, Quetta, Dera Bugti,
  Pishin, Kech and Khuzdar) it is set only where an official
  source confirms where the tehsil is now, and is `null` otherwise.
  - **Confirmed (Punjab, all 25 tehsils of the five parent districts):**
    Murree and Kotli Sattian are in Murree district; Talagang and Lawa in
    Talagang; Wazirabad in Wazirabad; Kot Addu and Chowk Sarwar Shaheed in
    Kot Addu; Taunsa and Koh-e-Suleman in Taunsa; the others stay in
    Rawalpindi, Chakwal, Gujranwala, Muzaffargarh and Dera Ghazi Khan.
    Source: the Board of Revenue's list of tehsils by district as on 31
    December 2023, in the Punjab Bureau of Statistics' Statistical Pocket
    Book 2025
    (https://bos.punjab.gov.pk/system/files/Statistical%20Pocket%20Book%202025%20Final.pdf,
    retrieved 2026-11-16). That list also has tehsils created since the
    census (Vehova, Alipur Chatha and others), which are not in this data.
  - **Not confirmed, so `null` (78 tehsils):** the tehsils of Swat, Upper
    Dir, Batagram, Dera Ismail Khan and South Waziristan (Khyber
    Pakhtunkhwa) and of Quetta, Dera Bugti, Pishin, Kech, Khuzdar, Lasbela
    and Jaffarabad (Balochistan). No official list of tehsils by district
    for today's districts could be read for either province.
- **Divisions** are the census's 30. Divisions created since (Gujrat in
  Punjab, listed on punjab.gov.pk) are not included, and districts created
  since the census have no division here.
- **Not covered:** Azad Jammu and Kashmir (3 divisions, 10 districts, 32
  tehsils per "AJK at a Glance 2023") and Gilgit-Baltistan. The census tables
  have no rows for them, and no official list of their tehsils was found.
- **Spelling** is the census's, in title case, with district names changed
  to ours ("UMER KOT" → Umerkot, "KAMBAR SHAHDAD KOT" → Qambar Shahdadkot,
  "TORGHAR" → Tor Ghar).
- **Repaired by hand.** The letters "LLA" are missing from four names in the
  district tables' text (the PDF prints them, but they do not come out of
  it). They are restored in `data/sources/census-2023-admin-units.csv`:

  | Census text    | Restored to     | Evidence                                                 |
  | -------------- | --------------- | -------------------------------------------------------- |
  | `AI`           | Allai           | Allai tehsil of Batagram; KP Development Statistics 2026 |
  | `KAR KAHAR`    | Kallar Kahar    | Punjab Board of Revenue tehsil list ("Kalar Kahar")      |
  | `KAR SAYADDAN` | Kallar Sayaddan | Punjab Board of Revenue tehsil list ("Kallar Syedan")    |
  | `TANDO AHYAR`  | Tando Allahyar  | The census's own province table prints "TANDO ALLAHYAR"  |

## Public holidays (`holidays.json`)

Eid ul Fitr, Eid ul Adha, Ashura and Eid Milad un Nabi dates actually observed
in 2020–2026; each entry has a `source` URL, and every source is a Cabinet
Division notification or an SBP circular letter (checked 2026-11-16; the last
seven news links, for 2020–2023, were replaced that day with the SBP circular
that states the same dates). Later years are estimated from the tabular Hijri calendar
and marked `estimated: true`. Fixed-date holidays follow the years they applied
in (e.g. Iqbal Day restored in 2022, Youm-e-Takbeer from 2024).

## Sales tax rates (`sales-tax-rates.json`)

Standard rates only, from 1 July 2019, each with the period it applied, the
law that sets it and an official document. Edited directly. Reduced, higher
and sector rates (telecom at 19.5%, restaurants paid by card, Third Schedule
goods, further tax and so on) are not included. All documents retrieved
2026-11-18.

| Tax                                         | Rate | Applied               | Source                                                                                                                                                                                                                                                                                                       |
| ------------------------------------------- | ---- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 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)                                                                                                               |
| 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)                                                                          |
| 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)                                                                |
| 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)                                                                                                                                                        |
| 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)                                                                                                 |
| 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) |
| 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)                                                                                          |
| 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)                                                                                                                           |
| 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)                                                                                                                                             |

How sure we are:

- **Verified** from the Act or Finance Act itself: every change of rate and
  every current rate.
- **The earlier rates (federal 17%, Sindh 13%, ICT 16%)** are confirmed as the
  rate the amending Act replaced. That they applied all the way back to
  1 July 2019 rests on finding no amendment in between, not on a 2019
  consolidation.
- **The federal rise to 18%** was first notified by S.R.O. 179(I)/2023 of
  14 February 2023, which is not on FBR's website; the dataset uses
  23 February 2023, when the Finance (Supplementary) Act 2023 took effect.
- **Balochistan for 2025-26 and 2026-27**: BRA's consolidated Act goes up to
  the Finance Act 2024, and BRA's own FAQ, which is undated, still gives 15%.
  The Balochistan Finance Acts 2025 and 2026 were not found online.
- **Islamabad Capital Territory after 30 June 2025**: FBR has not published a
  2026 consolidation; the Finance Act 2026 does not amend the ICT Ordinance.
- In Balochistan, ICT and (before 2022) Khyber Pakhtunkhwa the law has no
  single "standard rate": it is the rate on almost every line of the
  Schedule, which BRA's FAQ and FBR's circular call the standard rate.

## Income tax on salary (`income-tax-slabs.json`)

The salaried rate table for each tax year: Division I of Part I of the First
Schedule to the Income Tax Ordinance 2001, clause (2), which applies where
salary is more than 75% of taxable income. Edited directly. Each year was
read from FBR's own consolidated Ordinance for that year, and checked against
the next year's consolidation, whose footnote quotes the table it replaced.
Every band's fixed amount equals the previous band's fixed amount plus its
rate on its width (the tests check this). All documents retrieved 2026-11-18.

| Tax year       | Law                                             | Source                                                                                                   |
| -------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| 2020 (2019-20) | Finance Act 2019                                | https://download1.fbr.gov.pk/Docs/20199191692232848IncomeTaxOrdinance,2001amendedupto30-06-2019.pdf      |
| 2021 (2020-21) | Finance Act 2019, unchanged by Finance Act 2020 | https://download1.fbr.gov.pk/Docs/202011414113915861I.T.OrdinanceAmendedupto(30-06-2020).pdf             |
| 2022 (2021-22) | Finance Act 2019, unchanged by Finance Act 2021 | https://download1.fbr.gov.pk/Docs/20217141672549772IncomeTaxOrdinanceAmendedupto30.06.2021.pdf           |
| 2023 (2022-23) | Finance Act 2022                                | https://download1.fbr.gov.pk/Docs/202412215123222278IncomeTaxOrdinanceAmendedupto30.06.2022.pdf          |
| 2024 (2023-24) | Finance Act 2023                                | https://download1.fbr.gov.pk/Docs/202412215122448762IncomeTaxOrdinance,2001Amendedupto30.06.2023.pdf     |
| 2025 (2024-25) | Finance Act 2024                                | https://download1.fbr.gov.pk/Docs/2024751675120641IncomeTaxOrdinance,2001-amended-upto30.06.2024.pdf     |
| 2026 (2025-26) | Finance Act 2025                                | https://download1.fbr.gov.pk/Docs/2025881983148210Income-Tax-Ordinance,-2001-Amended-upto-31.07.2025.pdf |
| 2027 (2026-27) | Finance Act 2026                                | Finance Act 2026 (primary) and two further sources, listed below                                         |

Tax year 2027 has three sources, all retrieved 2026-11-18:

1. **Primary: the Finance Act, 2026**, Gazette of Pakistan (Extraordinary),
   Part I, 26 June 2026
   (https://download1.fbr.gov.pk/Docs/20266291261044366FinanceAct2026.pdf).
   - Section 5(44)(a)(i) substitutes the table in clause (2) of Division I,
     Part I, First Schedule (Gazette page 580). Its eight bands, fixed
     amounts and rates match `income-tax-slabs.json` exactly.
   - Section 1(2) brings the Act into force on 1 July 2026, the first day of
     tax year 2027.
   - Section 5(2)(b) replaces the 9% salaried surcharge in the proviso to
     section 4AB with "no surcharge shall be payable".
   - This is the URL in the dataset's `source` field for 2027.
2. **FBR's explanation: Circular No. 02 of 2026-27 (Income Tax)**, C. No.
   1(50)S(ITP)/2026, 8 September 2026
   (https://download1.fbr.gov.pk/Docs/202698139527880CircularNo.2of2026-27.pdf).
   - Paragraph 7 restates the same table.
   - Paragraph 8 confirms that the 9% surcharge on salaried individuals is
     withdrawn, while the 10% surcharge on other individuals and associations
     of persons continues.
   - The circular does not name a tax year, which is why the commencement
     comes from the Act.
3. **FBR's consolidated Ordinance**
   (https://download1.fbr.gov.pk/Docs/2026724177725705IncomeTaxOrdinanace2001.pdf).
   It prints the same table, with a footnote quoting the 2026 table it
   replaced.

How sure we are, and what is left out:

- **Verified** from FBR's consolidated Ordinance for each year. For 2027 the
  table was also checked against the Finance Act, 2026 as gazetted and FBR
  Circular No. 02 of 2026-27. For earlier years the Finance Act texts
  (Gazette) were not read; FBR's consolidations are the source.
- **Not applied** (out of scope): the surcharge under section 4AB (from tax
  year 2025: 10% of the tax over Rs 10 million of taxable income; 9% for
  salaried individuals in 2026; none for salaried individuals in 2027), tax
  credits, exemptions, the separate rate for pension from a former employer
  (2026 onwards: 0% up to Rs 10 million, 5% above), and withholding
  adjustments.
- Tax is rounded half up to the paisa; the Ordinance's own rounding to whole
  rupees is left to the caller.

## Urdu alphabetical order (no dataset)

`compareUrdu` follows the Unicode CLDR collation tailoring for Urdu
(`common/collation/ur.xml`, "standard", CLDR release 49, unchanged since
2015), https://github.com/unicode-org/cldr/blob/release-49/common/collation/ur.xml,
retrieved 2026-11-18. Its own reference is the CRULP/PAN Localization paper
"Urdu Encoding and Collation Sequence". The government's National Language
Promotion Department (https://nlpd.gov.pk) does not publish a sort order
online, so CLDR is the order cited. The implementation was checked against
ICU's `ur` collator (Node.js, CLDR 48, identical rules) on 200,000 random
pairs of Urdu words.

## Electricity and gas bill numbers

No dataset: `parseElectricityRef` and `validateGasConsumerNumber` check the
formats that the utilities' own bill pages ask for. All pages were retrieved
on 2026-11-18.

- **DISCO reference number**: 14 digits, with urban or rural chosen
  separately (`U`/`R`), on PITC's bill pages for all 11 companies
  (https://bill.pitc.com.pk/lescobill and the same for gepco, fesco, iesco,
  mepco, pesco, hazeco, hesco, sepco, qesco and tesco). PITC's illustration
  groups it as 2 + 5 + 7 digits, which is how `formatted` shows it.
- **DISCO customer ID**: 10 digits, or 11 for LESCO (the same PITC pages).
- **K-Electric account number**: "13 digits KE Account Number starting from
  04000" (https://beta.ke.com.pk/know-your-area-status/ and
  https://ke.com.pk/bills-e-payments/). K-Electric says its contract and
  consumer numbers are for its internal use, so they are not accepted.
- **SNGPL consumer number**: 11 digits
  (https://www.sngpl.com.pk/login.jsp?mdids=85).
- **SSGC customer number**: "10-digit Customer Number"
  (https://viewbill.ssgc.com.pk/web/).
- **Not published**: what the reference number's digit groups mean, which
  digits belong to which DISCO, and any check digit. So `disco` is `null`
  except for K-Electric, and only the format is checked. IESCO also notes
  that reference numbers can change
  (https://www.iesco.com.pk/search-reference-number).

## Couriers

No dataset: `mapCourierStatus` maps only the statuses a courier documents
publicly. All pages were retrieved on 2026-11-18.

- **PostEx**: "Merchant API Integration Guide", version M- v4.1.9 (undated):
  order status IDs 1 to 9 and 15 to 18 (§3.15) and tracking history codes
  0001 to 0008 and 0013 (§3.8). The guide is PostEx's own, but it is hosted
  on Amazon S3
  (https://merchant-api-guide.s3.ap-south-1.amazonaws.com/PostEx-COD_API_Integration_Guide_V4.1.9.pdf)
  and not linked from postex.pk. Its history codes 0002, 0006 and 0007 all
  read "Returned"; "Package on Root" is mapped as written and also as "on
  route".
- **Leopards**: only "Returned to Shipper", defined in its e-commerce FAQ
  (https://ecom.leopardscourier.com/faqs). Its API documentation site
  (https://merchantapi.leopardscourier.com) has no content.
- **TCS, M&P, Trax and BlueEx**: no public status list. Their API documents
  are behind merchant or developer logins, so nothing is mapped. Copies on
  third-party sites were not used.
- **Tracking numbers**: no courier documents a format, so there is no
  tracking-number detection. PostEx's guide only uses the placeholder
  `CX-XXXXXXXXXXX`.

`normalizeCityForCourier`'s short forms (`LHR`, `Khi`, `Pindi`, `ISB`, `FSD`,
the former name Lyallpur, Urdu names and so on) are common usage, not an
official list. Each maps to a city in `cities.json`.

## FBR Digital Invoicing

No dataset: `buildFbrInvoice` and `validateFbrInvoice` follow these
documents, retrieved on 2026-11-18:

- **PRAL, "Technical Specification for DI API", version 1.12** (issued
  7 April 2025, last updated 24 July 2025):
  https://download1.fbr.gov.pk/Docs/20257301172130815TechnicalDocumentationforDIAPIV1.12.pdf,
  linked from https://www.fbr.gov.pk/di-technical-assistance/173967/173970.
  PRAL's download index (https://dicrm.pral.com.pk/assets/docs/documents.json)
  lists it as the current version. It gives the fields, the sale types and
  the error codes.
- **PRAL, "Error Message Guide (Sales)"**:
  https://dicrm.pral.com.pk/assets/docs/Manuals/Error%20Message%20Guide%20-%20(Sales).pdf.
  This is the source of the rules on numbers (0300: not negative or empty;
  0302: at most 2 decimals, 4 for quantity), on SROs (0077, 0078) and on
  reduced-rate goods (0091).
- **PRAL, "DI Scenarios Description for Sandbox Testing"** (v1.11): the sample
  invoices, used for the arithmetic examples (1000 × 18% = 180; Rs.3 × 12 =
  36; retail price 100 × 18% = 18 for Third Schedule goods).
- **Legal basis**: S.R.O. 69(I)/2025, Sales Tax Rules chapter XIV
  (https://download1.fbr.gov.pk/SROs/2025129141598258SRO69(I)2025.pdf).

Where the documents disagree or are silent, the code does this:

- **Key names** are those of the specification's sample JSON
  (`invoiceType`, `buyerRegistrationType`), not the misspellings in its field
  table, and `invoiceType` is `Sale Invoice` (the table says "Sales
  Invoice", but the samples and the document type API say "Sale Invoice").
- **NTN length** is 7 (error 0002's text also mentions 9, but 0401, 0402 and
  the guide say 7 or 13).
- **Rounding**: none is documented. Sales tax is rounded half up to the
  paisa, and a declared tax within one paisa of it is accepted. This is the
  library's choice.
- **Sale types** are compared ignoring case and spaces, because the
  specification's table and its samples differ in capitals.
- **Not checked**: anything that needs FBR's reference APIs or records
  (registration, provinces, HS codes, units, rates, sale types, SRO lists,
  the original invoice of a debit note). There are no string length limits
  in the specification, so none are checked.

## CNIC

First digit = province of registration, per FBR's tax-ID description filed with
the OECD (1 Khyber Pakhtunkhwa, 2 former FATA, 3 Punjab, 4 Sindh, 5
Balochistan, 6 Islamabad, 7 Gilgit-Baltistan). `8` for Azad Jammu and Kashmir
comes from secondary sources only. Last digit odd = male, even = female.

## Passport numbers

`validatePassport` accepts two letters followed by seven digits (`AB1234567`).
DGIP does not publish the format, and its forms only ask for "Passport Number".

- **Source:** the EU Council's PRADO register gives this pattern for the 2013
  ordinary passport
  (https://www.consilium.europa.eu/prado/en/PAK-AO-02003/index.html). The page
  sits behind a bot check, so it was confirmed through search-result text, not
  the page itself.
- **Observed on real passports:** the maintainer checked real ordinary
  (green) and official (blue) Pakistani passports in November 2026; their
  numbers have this shape. No numbers are recorded here.
- **Fits ICAO Doc 9303:** the document-number field is 9 characters, with the
  check digit stored separately in the machine-readable zone
  (https://www.icao.int/publications/Documents/9303_p4_cons_en.pdf).
- **Still unconfirmed:** diplomatic (red) passports and the e-passport
  variants (2022 onwards), and what the letters mean. A real number in another
  shape will be rejected; treat `false` as unusual, not fake.

## Vehicle registration plates

`parseVehiclePlate` accepts 1–4 letters, then 1–4 digits, optionally followed
by a two-digit year after a separator (`LEA-1234-19`). There is no national
format: each province's excise department sets its own.

- **Reported formats** (Wikipedia, partly inconsistent,
  https://en.wikipedia.org/wiki/Vehicle_registration_plates_of_Pakistan):
  Sindh cars 3 letters + 3 digits; Islamabad and Balochistan 2 letters + 3
  digits; Khyber Pakhtunkhwa 2 letters + 4 digits; Gilgit-Baltistan 3 letters +
  2 digits; AJK motorcycles and public transport 4 letters + 3 digits; older
  Punjab plates 4 digits plus a two-digit year.
- **Number length:** Punjab's excise department auctions registration marks of
  1 to 4 digits (https://excise.punjab.gov.pk/auctions).
- **Recent changes:** numbers now stay with the owner in Islamabad
  (https://profit.pakistantoday.com.pk/2025/07/20/ict-excise-deptt-introduces-personalized-number-plates-digital-cards-online-tax-payment/),
  Khyber Pakhtunkhwa
  (https://arynews.tv/kp-new-vehicle-registration-number-plate-system-sep-17-2025)
  and Sindh, from 16 February 2026
  (https://profit.pakistantoday.com.pk/2026/02/16/sindh-enforces-cnic-based-number-plates-owners-can-retain-registration-marks/).
  Punjab announced new series from May 2026
  (https://propakistani.pk/2026/04/29/punjab-to-launch-five-new-vehicle-number-series/)
  without publishing their layout.
- **Not checked:** series letters against districts (no official list, e.g. for
  `LEA`/`LEB` = Lahore), and labels printed on the plate such as "ICT" or
  "PUNJAB", which are not part of the number.
