Skip to content

Data sources

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 114 6 KB
banks.json 50 5 KB
cities.json 226 14 KB
districts.json 177 12 KB
divisions.json 30 5 KB
holidays.json 7 5 KB
income-tax-slabs.json 8 10 KB
networks.json 53 2 KB
post-offices.json 2,560 341 KB
postal-codes.json 457 66 KB
sales-tax-rates.json 9 3 KB
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 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.

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).

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.

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.

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.

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)

Section titled “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 “ 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)

Section titled “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:

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”

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).

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)

Section titled “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.

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.

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

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.

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

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.

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.

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.

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.