tanzania-postcodes

Real Tanzania postal codes, sourced directly from TCRA's official gazetted National Postcode System (Government Gazette Notice No. 240, 22 April 2016) — not a third-party site's compiled or scraped version.

No Python package for Tanzania postcodes existed before this one. pgeocode, the most common general-purpose postal code library, explicitly doesn't support Tanzania (ValueError: country=TZ is not a known country code) — its data comes from GeoNames, which has no real Tanzania coverage.

Install

pip install tanzania-postcodes

Usage

import tanzania_postcodes as tzpc

# Look up everything at a postcode
tzpc.lookup("16112")
# [Postcode(region='Dar Es Salaam', district='UBUNGO', ward='Goba',
#            postcode='16112', locality='Goba', ...), ...]

# Search by name (ward, district, region, or locality)
tzpc.search("Goba")[0].postcode
# '16112'

# List all 26 regions
tzpc.regions()

# List all wards, optionally scoped to one region
tzpc.wards("Dar Es Salaam")

Each result is a Postcode:

Postcode(
    region: str,               # e.g. "Dar Es Salaam"
    district: str | None,       # e.g. "UBUNGO"
    ward: str,                  # e.g. "Goba" -- the unit TCRA's postcode identifies
    postcode: str,               # e.g. "16112"
    locality: str | None,       # mtaa/village within the ward
    sub_locality: str | None,   # kitongoji, where the source PDF has one
    old_postcode: str | None,   # legacy code, where the source PDF has one
    district_postcode: str | None,
)

Coverage

All 26 regions, 67,000+ locality-level records, 3,900+ unique ward postcodes. A postcode identifies a ward — the same postcode applies to every village/mtaa within it, which is why lookup() usually returns multiple records for one code.

Where this data comes from, and how it was built

TCRA publishes the postcode list as 26 separate regional PDFs (no CSV/Excel version exists) at tcra.go.tz/services/publication-of-postcode-list. Each PDF's table uses merged cells for repeated values, and — found during development — three different column layouts across the 26 files (some have a separate District level, some don't; some have an Old Postcode column, some don't; one region's table has no header row at all). scripts/parse_pdfs.py detects each table's actual header and maps columns by name rather than assuming one fixed schema, with a documented fallback for the one region missing a header entirely.

scripts/download_pdfs.py and scripts/parse_pdfs.py are included in this repo if you want to verify the extraction yourself or regenerate the dataset from TCRA's source PDFs directly.

Why this exists

Built after actually needing a Tanzania postcode (Goba ward, Dar es Salaam — 16112), confirming no Python package or well-covered general library had it, and finding TCRA's own official data was real, current, and genuinely extractable — just never turned into a package before.

License

MIT for this package's code. The underlying postcode data is Tanzania government public record (Government Gazette Notice No. 240, 2016).