Bulgaria (BG) — internal licensing notes

Source research, 2026-08-29

GeoNames is the only viable source. No official open alternative found.

GeoNames BG postal export

https://download.geonames.org/export/zip/BG.zip   # 5,304 rows

Licence CC BY 4.0, verified against export/zip/readme.txt on 2026-08-29 — Bulgaria carries no per-country caveat (the only caveat countries are GB, CL, CN, IE, MT, AR, BR).

Admin data is rich, not a gap like South Africa. Verified directly against the raw source: admin_name1 (oblast) filled on 5,304/5,304 rows, 28 distinct — matches Bulgaria's real 28 oblasts exactly. admin_name2 (obshtina/municipality) filled on 5,303/5,304, 262 distinct (Bulgaria has 265 municipalities — near-complete). admin_name3 (settlement within municipality) filled on 2,993/5,304 (56%) — a genuine partial gap, not a defect. Names are bilingual, Cyrillic and transliterated Latin separated by " / " (e.g. "Айтос / Ajtos") — disclose this format rather than picking one.

Real primary-key collision found — must be handled, not silently deduped. 20 (postal_code, place_name) pairs repeat because the SAME 4-digit code and the SAME village/town name exist in TWO DIFFERENT municipalities (e.g. postal code 4270 "Първомай / Purvomaj" exists as a village in both Blagoevgrad oblast/Petrich municipality AND Plovdiv oblast/Parvomay municipality — these are two real, different places that happen to share both a postal code and a name). A build must key on (postal_code, place_name, admin_code2) or disclose the collision, not assume the 13-column schema's usual (postal_code, place_name) primary key holds — it does not, on 20 rows.

Official alternative — not found

No official Bulgarian Posts (Български пощи) bulk open-data postal file was found. Search turned up only third-party aggregators: postcodebase.com (paid, restrictive personal/internal-use-only licence, sales final), a Back4App-hosted table (terms not verified), and Wikipedia's "Postal codes in Bulgaria" (format explanation only, no per-code table). None beats GeoNames on licence clarity or coverage.

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

{
  "channel": "postal-codes-r2",
  "source_url": "https://download.geonames.org/export/zip/BG.zip",
  "licence_id": "CC-BY-4.0",
  "collected_at": "2026-08-29",
  "decision": "compatible",
  "decided_by": "claude-session-2026-08-29",
  "decided_at": "2026-08-29"
}

Proposed tier

B ($49). Single official-quality source (GeoNames) normalised in place — real work (28/262 admin tiers already usable, but the 20-row primary-key collision needs a deliberate join-key fix, and the bilingual name format needs a documented convention). No second source consolidated.

Verdict

Build it. No licensing obstacle. The only real engineering task is handling the primary-key collision correctly and deciding how to present the bilingual Cyrillic/Latin place names (keep as-is, split into two fields, or pick one with the other in alternative_city_name — a real judgment call worth flagging before building, not deciding unilaterally).

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

Built via datasets/bg/scripts/build_postal_codes_product.py. Bilingual names kept as-is (both scripts, " / "-separated) rather than split or truncated.

Found a second real defect beyond the 20-pair collision already known: postal code 6045 appeared TWICE in the raw source with contradictory data — one row claimed oblast "Smoljan"/municipality "Devin" but was coded SZR (Stara Zagora's code everywhere else, and had no accuracy value); the other claimed oblast "Stara Zagora"/municipality "Stara Zagora", self-consistent with an accuracy value. Checked before deciding: all 16 other Devin-municipality rows are consistently coded SML (Smolyan, Devin's real oblast) — so the "Smoljan"/"Devin" row was a corrupted duplicate, not a second real place. Dropped it; kept the self-consistent row.

Real primary key turned out to be (postal_code, place_name, admin_code2, admin_code3), not the (postal_code, place_name, admin_code2) originally proposed — 4 more collisions existed within the same municipality (one row is the municipality's own seat, settlement field empty; the other is a distinct settlement sharing the parent's code), only resolved by adding admin_code3.

ISO 3166-2:BG derived via a verified crosswalk (Wikipedia, checked 2026-08-30) from GeoNames' internal 3-letter codes — GeoNames' own codes are NOT the ISO codes for Bulgaria (unlike Hungary, where they happened to match).

Frictionless validation: valid: True.

Status: built and validated locally only. Nothing published to R2, nothing committed to git. datasets/bg/README.md and datapackage.yml updated in place (tier B, premium_source_key: bg/bg.zip, real sources/licenses, replacing the "Multiple sources" placeholder).