Settlement within municipality -- partially populated, a genuine source gap
Administrative Name 3
admin_code3
string
GeoNames' own settlement code
Administrative Code 3
latitude
number
GeoNames latitude (WGS84)
Latitude
longitude
number
GeoNames longitude (WGS84)
Longitude
accuracy
string
GeoNames accuracy of latitude/longitude. GeoNames documents 1=estimated, 4=geonameid, 6=centroid of addresses or shape; other values (e.g. 3) occur upstream without documentation. Empty where GeoNames gives none.
Accuracy
alternative_city_name
string
Not populated in this release
Alternative City Name
Part of a data solution
Postal Codes Solution
Every worldwide postal-code dataset in one bundle — the ultimate global reference for precise postal codes.
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)
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.
value
Final rows
5,303 (5,304 raw − 1 corrupted duplicate dropped)
Oblasts covered
28/28
Municipalities covered
265 (matches Bulgaria's real municipality count)
Distinct postal codes
4,359
(postal_code, place_name) collisions requiring the extended key
24
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).
API access
Access dataset files directly from scripts, code, or AI agents.
Each file has a stable URL (r-link) that you can use directly in scripts, apps, or AI agents. These URLs are permanent and safe to hardcode.