Metadata-Version: 2.4
Name: tanzania-postcodes
Version: 0.1.0
Summary: Real Tanzania postal codes, sourced directly from TCRA's official gazetted National Postcode System -- not a third-party compilation.
Author-email: Freddy Nyanda <freddynyanda@proton.me>
License-Expression: MIT
Project-URL: Homepage, https://github.com/nyandajr/tanzania-postcodes
Project-URL: Repository, https://github.com/nyandajr/tanzania-postcodes
Project-URL: Source, https://www.tcra.go.tz/services/publication-of-postcode-list
Keywords: tanzania,postcode,postal-code,zip-code,tcra,address
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# 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`](https://pypi.org/project/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

```bash
pip install tanzania-postcodes
```

## Usage

```python
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`:

```python
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](https://www.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).
