South Africa (ZA) — internal licensing notes

Source research, 2026-08-28 — sellability + reproducibility audit

GeoNames is the only source that is both legally sellable and reproducible — same shape of finding as Albania — but here it carries a much larger gap: it has ZERO administrative-division data for South Africa, not a reduced amount.

The only usable source — GeoNames ZA

https://download.geonames.org/export/zip/ZA.zip       # 26 KB, 3,920 rows

Licence CC-BY-4.0, verified against export/zip/readme.txt on 2026-08-28 — South Africa carries no per-country caveat.

Verified directly against the raw source file (not the corrupted R2 export): admin_name1, admin_name2, and admin_name3 are empty on every single one of the 3,920 rows in GeoNames' own ZA.txt. This is not a pandas-round-trip bug like TH/RO/AL — GeoNames genuinely carries no province, district, or municipality data for South Africa at all. Only postal_code, place_name, latitude, longitude, accuracy are ever populated. 3,266 distinct postal codes across 952 distinct place names — the coordinates are coarse city/town-level points (e.g. every Pretoria-area code from 0002–0006 shares the exact point -25.7069, 28.2294), not per-code locations.

The official source — SAPO — is explicitly closed, not merely unresolved

The South African Post Office (SAPO) maintains the authoritative postal code list but its own website terms of use require prior written permission for commercial use — this was checked directly (Open Knowledge's Global Open Data Index review of SA postcodes, 2015, quotes SAPO's own ToU to this effect) and is a clean decision: "incompatible", not "unresolved". Also not machine-readable in bulk (XLS only, not a downloadable dataset). Do not re-attempt scraping SAPO for a commercial product.

Ruled out — do not re-attempt without new evidence

What this means for the product

A GeoNames-only rebuild is legally sellable (CC BY 4.0, unambiguous) and would fix the current file's defects, but the result is a much thinner product than usual: postal_code, place_name, latitude, longitude, accuracy only — every admin_name*/admin_code* field ships empty, not because of a build limitation but because no commercially licensable source carries South African admin-tier data at all. This is a genuine product- quality ceiling, not a licensing block.

Defects in the currently-published file

za/za.csv on R2 is a GeoNames re-export (row count matches ZA.zip exactly: 3,920) round-tripped through pandas and corrupted:

1. admin_name1/admin_name2/admin_name3 are the literal string nan on every row. As established above, GeoNames' own source has these genuinely empty — the nan string is the round-trip artifact, but the underlying emptiness itself is real and does not resolve with any licensable source found.
2. Integer accuracy written as float (4 → 4.0); many rows blank.
3. 3,920 rows but only 3,266 distinct postal codes — check duplicates against the primary key rule before publishing (distinct on (postal_code, place_name) is expected to be clean; verify at build time).

Attribution is absent from the sold product. R2 carries only za/za.csv — no README.md, datapackage.json, ATTRIBUTION.txt or za.zip. The repo datapackage.yml lists sources: [{title: "Multiple sources"}] with no licenses[]. CC BY 4.0 attribution is a licence condition — live breach on a paid product.

datapackage.yml also sets is_premium: true with no premium_tier and no premium_source_key, and no zip exists in R2 for a key to point at.

licence_status (proposed — needs human sign-off before shipping)

{
  "channel": "postal-codes-r2",
  "components": [
    {
      "field_group": "postal_code, place_name, latitude, longitude, accuracy",
      "source_url": "https://download.geonames.org/export/zip/ZA.zip",
      "licence_id": "CC-BY-4.0",
      "collected_at": "2026-08-28",
      "decision": "compatible",
      "decided_by": "claude-session-2026-08-28",
      "decided_at": "2026-08-28"
    },
    {
      "field_group": "admin_name1/2/3, admin_code1/2/3",
      "source_url": null,
      "licence_id": null,
      "collected_at": "2026-08-28",
      "decision": "no_source_found",
      "decided_by": "claude-session-2026-08-28",
      "decided_at": "2026-08-28",
      "note": "Not 'unresolved' in the usual sense of an unread ToU -- every candidate source was checked and individually ruled out (SAPO incompatible, others unresolved-provenance or wrong-geography). Ships empty, not guessed."
    }
  ]
}

Proposed tier

B ($49) at most, and worth a deliberate human decision on whether B is even justified given how thin the product is (5 of 13 columns real content, 0 of 8 admin columns populated). This is a weaker product than AL (which at least carries qark+bashki), despite ZA usually being thought of as a bigger, more developed market. Do not price it as A — there is no second source consolidated onto it, only a single-source cleanup, and the admin gap is not something a human sign-off can wave through since no licensable source exists to fill it.

Verdict (superseded below — see Build, 2026-08-29)

Possible, but weak. GeoNames-only is buildable and legally sellable today — same mechanical fix as TH/RO/AL (rebuild via csv, not pandas, fix the nan literals and float accuracy). It should NOT be marketed as carrying province/municipality data, because it doesn't and no licensable source was found that provides it. If a real admin tier is wanted later, the MDB spatial-join path is the only remaining lead, and it is a substantial separate build (geocoding-shaped, not a normalisation), not a quick follow-up.

Build — 2026-08-29 (local only, not published)

Human asked to fill the admin-tier gap using AfriGIS. Checked first: AfriGIS is a paid, API-key-gated commercial geocoding service (developers.afrigis.co.za, 50M+ address records), not a downloadable dataset — no API credentials exist anywhere in this environment (.env, .env.template checked), and bulk-querying a commercial geocoding API to build a cached, resold reference dataset is the same shape of ToS violation this project already blocks for Nominatim (see CLAUDE.md's OSM/Nominatim gate — "systematic queries… reselling of geocoding results" is expressly prohibited by that class of provider). Presented this to the human; instruction was to skip AfriGIS and look for other sources instead.

Found one, and it was hiding in a source already in hand. GeoNames publishes TWO separate exports: the postal export (export/zip/ZA.zip, zero admin fields, already established above) and a general-purpose gazetteer dump (export/dump/ZA.zip) — same publisher, same CC BY 4.0 licence, not a new source or a new licensing question. The dump DOES carry full South African admin data: 9 provinces and 52 district/metro municipalities, via admin1CodesASCII.txt / admin2Codes.txt, populated on 12,875 of its own populated-place entries.

Built a same-source join: postal row's place name matched against the gazetteer (disambiguating common names that repeat across provinces by nearest coordinate), falling back to pure nearest-neighbour search where no name matches at all. Measured directly before shipping:

Verified the join on a spot check (postal code 0002/0003/0004/0005, Pretoria → Gauteng → City of Tshwane Metropolitan Municipality) before trusting it at scale.

This is disclosed as a coordinate-based join against GeoNames' own gazetteer, not an official South African administrative register — high confidence, not authoritative in the register sense. Stated explicitly in README.md/ATTRIBUTION.txt/datapackage.json, not silently upgraded to look like government data. admin_code2 values are GeoNames' own internal identifiers (e.g. "DC32", "ETH"), not an independently verified official municipal code registry — also disclosed rather than presented as authoritative.

admin_code1 derived to ISO 3166-2:ZA via a verified crosswalk (Wikipedia, checked 2026-08-29) from GeoNames' internal admin1 numbering — GeoNames' own admin1 codes (ZA.02, ZA.03, …) are not themselves ISO codes.

Frictionless validation: valid: True.

Verdict (final)

Ship it as tier B, with the join method disclosed. This is a meaningfully stronger product than the original GeoNames-only proposal — 9/9 provinces and 52/52 districts recovered, not zero — at no new licensing cost (same publisher, same CC BY 4.0). Still single-source in the tier sense (both exports are GeoNames), so B ($49), not A: real derivation work (the gazetteer join) but no second authoritative provider consolidated onto it.

Status: built and validated locally only. Nothing published to R2, nothing committed to git. datasets/za/README.md and datapackage.yml updated in place (tier B, premium_source_key: za/za.zip, real sources/licenses, replacing the "Multiple sources" placeholder and the broken is_premium: true with no tier/key that was live on R2 before this build). The previously-flagged live breach (broken paid product, missing attribution files) is fixed in this local build but the fix has not been published — R2 still serves the old defective file until someone runs the publish step.