Part of a Data Solution
- Explore →
Postal Codes Solution
Every worldwide postal-code dataset in one bundle — the ultimate global reference for precise postal codes.
Premium
You're viewing a free sample
Get the complete dataset — all rows and files — delivered instantly after checkout, with lifetime access to the latest version.
- Secure checkout via Stripe
- Instant download after payment
- Lifetime access to the latest version
- Creative Commons Attribution 4.0 International license
API Access
Access dataset files directly from scripts, code, or AI agents.
Browse dataset files
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.
Start with these files — they give you everything you need to understand and access the dataset.
- 1. Fetch datapackage.yaml to inspect schema and resources
- 2. Download data resources listed in datapackage.yaml
- 3. Read README.md for full context
Data Files
postal-codes-bg-sample
| Field | Type | Description | Constraints | Title |
|---|---|---|---|---|
| country_code | string | ISO 3166-1 alpha-2 -- always BG | Country Code | |
| postal_code | string | Bulgarian postal code (4 digits) | { "pattern": "^\\d{4}$" } | Postal Code |
| place_name | string | Locality/place name, bilingual Cyrillic / Latin-transliteration (e.g. "Aitos / Ajtos") | Place Name | |
| admin_name1 | string | Oblast (province) -- 28/28 covered, bilingual Cyrillic / Latin | Administrative Name 1 | |
| admin_code1 | string | ISO 3166-2:BG code | Administrative Code 1 | |
| admin_name2 | string | Obshtina (municipality) -- 265 distinct values, bilingual | Administrative Name 2 | |
| admin_code2 | string | GeoNames' own municipality code | Administrative Code 2 | |
| admin_name3 | string | 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 |
Download
Download sample CSVAbout
- Last updated
- 2 October 2026
- Total rows
- 100
- Format
- CSV
- File size
- 13.5 kB
About this dataset
Bulgaria (BG): migration notes
Internal record of the P5 migration from the old scripts to the producer: the discrepancies found, their causes, and who decided what. This is a dated record, so the numbers are as of the migration and not kept current. It is not shipped in the zip.
- Issue: pc-28e.7.7 (closed 2026-10-02)
- Commit:
4a59582(worktree commit3f0591f, same content), landed in batch 1 - Parity verdict:
explained(row_orderonly); signed off by the user - Producer:
custom, refresh disabled
Sources
| Input | URL | Notes |
|---|---|---|
| GeoNames postal export | https://download.geonames.org/export/zip/BG.zip | The only input, as in the old builder |
Parity against the live zip (2026-10-02)
Rows: 5,303 live and 5,303 fresh, none only on one side. 0 changed cells. The only class is row_order ×1: places reordered within postal codes, consistent with GeoNames reordering its export. No example of the moved rows was recorded.
Decisions
| Decision | By | Basis |
|---|---|---|
Accept the row_order difference | User (session 2479b1c9-…, 2026-10-02: "I sign off on the row order") | Batch 1 sign-off, recorded in docs/parity/p5.md |
| Keep dropping the corrupted 6045 "Смолян / Smoljan" / "Девин / Devin" row, but accept zero or one match (more than one raises) | Agent | The old builder asserted exactly one match. With this change the build won't fail once GeoNames fixes the row |
| Remove the row counts and the "2993/5303 rows (56%)" fraction from README and descriptor; "20 pairs repeat" → "some pairs repeat" | Orchestrator instruction (the README counts rule, user 2026-10-02) | Counts change whenever the data does |
Leave the row counts in ATTRIBUTION.txt for now | User (session 2479b1c9-…, 2026-10-02: attribution files shouldn't carry row counts, "file a bead to fix it later") | Filed as pc-3d2, folded into pc-hfz |
Drop the README's licence_status.decision sentence and use the standard GeoNames accuracy wording | Orchestrator (batch 1 doc fixes b7fb93b, then 5311ad3), after the user said "Fix the small doc problems you've noticed" | The descriptor has no licence_status field |
Transforms carried over
Folded from build_postal_codes_product.py:
admin_code1→ ISO 3166-2:BG. GeoNames' 3-letter oblast codes (BLG, BGS, VAR, …) are crosswalked to BG-01..BG-28 (verified against Wikipedia 2026-08-30). An unknown code is aProducerError.- The corrupted 6045 duplicate is dropped (see Decisions). It has the wrong oblast and county and no accuracy; every other Devin row is coded SML.
alternative_city_nameis empty. Bilingual names ("Айтос / Ajtos") are kept as GeoNames gives them.- The old asserts are now
ProducerErrors: primary key (postal_code, place_name, admin_code2, admin_code3) unique, all 28 oblasts present, no literalnan, no float accuracy ("4.0"). The exact row-count assert is gone.
Open questions
- Whether upstream still contains the corrupted 6045 row on today's file wasn't recorded. The output matches live row for row, so the drop presumably still applies.
ATTRIBUTION.txtstill says "5,303 rows" and "2993/5303 rows (56%)", and.licensing-notes.mdhas historical counts. Both are for pc-3d2 / pc-hfz.
Provenance
Reconstructed 2026-10-05 from the agent transcript 2479b1c9-c4dd-47e5-be82-34ccf8d49a80/subagents/agent-ab16439725d736d53.jsonl, the orchestrator session 2479b1c9-…, the commit messages (4a59582, b7fb93b, 5311ad3), the bd close reason and docs/parity/p5.md.