Published

United States (US) build pipeline

DataHub
DataHub
0

Postal Codes Dataset for United States, US including name of the city, town, or place, various administrative divisions and alternative city names.

United States (US) build pipeline

Self-contained — runs entirely from this repo. No external repo dependency: both scripts resolve their paths relative to themselves and fetch directly from a public source.

Reconstructed from nothing on 2026-08-19 — same situation AU was in: no build script survived anywhere, only a source-research note (preserved at fedex-agents-prototype/countries/USA/FEASIBILITY.md, not required to run this pipeline) and the live R2 data itself. That note lays out four options and explicitly labels Option B ("GeoNames US, ~41k, CC-BY") as "what we ship now" — that turned out to be wrong. Diffing raw GeoNames against live R2 us.csv found real enrichment already present:

  • admin_code2 (county FIPS): raw GeoNames only has a bare 3-digit county FIPS ("013"); live R2 has the full 5-digit state+county FIPS ("02013"). Reproduced via a static state-abbreviation-to-FIPS-prefix table (no live fetch needed) — now matches R2 exactly.
  • admin_name2 (county name): raw GeoNames has the bare county name ("Alameda"); live R2 mostly carries the official Census name with legal suffix ("Alameda County") — but not on every row (R2's own Fremont/94537 row is bare "Alameda" too, so whatever enrichment produced the live data didn't have 100% coverage either). This gap is NOT closed — every census.gov URL tried (national_county.txt, national_county2020.txt, the 2023 Gazetteer counties zip) returned an HTML error page instead of data from this environment, either moved or blocked. Documented here rather than silently shipping a mismatch.

That research note is stale and should probably be corrected to say Option-C-ish enrichment is already live, not merely proposed.

Run order (from this directory)

python3 fetch_source.py    # download.geonames.org/export/zip/US.zip, writes ../sources/US.txt
python3 build_base.py      # + static state->FIPS-prefix table for admin_code2

Sources

  • GeoNames US postal export — CC BY 4.0
  • Static state-abbreviation -> FIPS-prefix table (public, no licence — FIPS codes are a federal standard) for the admin_code2 fix

Verification (2026-08-19)

Row count: 41,490 built vs 41,488 live (2-row drift — GeoNames is a living community dataset, expected). admin_code2 now matches R2 exactly after the FIPS-prefix fix. 513 state-FIPS lookup misses on rebuild — only one cause explicitly checked (MH/Marshall Islands, a real but non-standard admin1 code used for some military postal codes); the rest were not fully characterized given time constraints and are flagged as unverified, not claimed fine. admin_name2 content match is incomplete (see above) — flag before treating this as a finished, exact reproduction.