veygrit/address-geography-postal

Veygrit public geography and postal candidates

Version 1.0.0. A partial pilot, not a worldwide address directory, postal-authority verification, ownership check, geocoder, or trained model. Derived exclusively from the cited GeoNames CC BY 4.0 public downloads. Attribution: GeoNames.

Coverage

Every country's coverage is partial. Zero streets means absent data, not absent streets. Source freshness varies; sourceupdatedat is retained where supplied, otherwise null. ASCII names are transliterations, not certified English translations. Names/aliases without language tags are not asserted to be official native-language labels. Untagged aliases can include former/historical names; source spellings may contain errors. These are search candidates, not verified current postal labels or automatic translation replacements. Confirm the current address with the user.

Tables and use

• —places: stable source-scoped IDs, country, kind, administrative path, parent IDs, source name, ASCII rendering and aliases. Only administrative areas, populated places/neighborhoods, and features explicitly classified as streets are retained.
• —postal_links: many-to-many code-to-place relations. Codes are strings (leading zeroes retained); postal_scope distinguishes full codes from prefixes/unknown precision.
• —resolution: name/postcode input with a set of expected candidate IDs. Ambiguous names and shared postcodes retain every corresponding candidate. Connected aliases and postcode groups stay in one deterministic train/validation/test split.

The places/postal_links tables use the HF split name train only for viewing their complete reference tables; they are NOT held-out evaluation data. Use resolution's separate splits for supervised experiments, and do not leak master-table targets into evaluation. Split assignment may change when new records connect existing groups; pin a dataset revision for reproducible evaluation. No model has been trained here.

Countries without postcodes

HK/MO/AE use place-name and administrative filtering. Never fabricate 00000, use a P.O. Box or a building/location identifier as a postcode, or infer a street from a postcode. Keep a user-entered building, number and unit separate. Precise location, if later added to an app, needs explicit consent and a separately licensed provider. Territory-wide codes cannot identify a city. Missing postal data is not evidence that a country has no postal system. policyreviewrequired preserves uncertainty.

Privacy, limits, and quality

No Veygrit user/account data, names of recipients, email, phone, saved addresses, delivery history, premise/unit numbers, coordinates or location histories are exported. Records outside the allowlisted GeoNames feature codes, including historical/abandoned feature classes, and Antarctica are excluded. Upstream classification may retain named buildings or residential developments as populated places; these are public geography labels, not recipient or private premise/unit records. Explicit review quarantines are listed in manifest.json and omitted from every published table and training split. The source is as-is; presence in this dictionary does not prove validity or delivery. Parent links are attached only from unambiguous source administrative codes, not name guesses. These codes are not relabelled as ISO subdivision IDs. Country boundaries, names and aliases reflect upstream data, not an independent boundary adjudication.

GeoNames postal data has country-specific truncation/coverage restrictions. This pilot uses AD/TH postal files only; do not reuse their full-code status for other countries. Do not fill a user's address without candidate confirmation; missing/conflicting candidates must preserve manual entry. Synthetic unit tests are not part of this release.

Provenance and updates

manifest.json contains source URLs, archive SHA256 hashes, retrieval dates, output hashes and exact counts. Filtering, normalization, hierarchy linking and resolution examples are Veygrit's transformations, not upstream endorsements. retrieved_at uses each locally downloaded archive's file modification time; it is not the upstream dataset's update date. Source revision timestamps can differ by record. Use GeoNames modifications/deletes with staging, referential-integrity validation, and a reviewed diff before publishing a new immutable revision. Deleted IDs must be retired, never reassigned. This release does not start an automatic daily job.

Sources: gazetteer documentation, postal documentation, feature codes.

License

Data and derived examples: Creative Commons Attribution 4.0 International. Credit GeoNames, link the license, and indicate Veygrit's transformations. No warranty.

World place candidates (separate snapshot)

284,501 public place candidates, 251 country/region profiles; 246 contain records. Select the world_places subset. Its train split is a reference table, not a training/evaluation split. The original places, postal_links and resolution pilot configurations and files are unchanged.

Partial GeoNames ADM1/ADM2 and cities500 coverage, not all world places or streets. No world postal or street/locality relationships are collected. Unresolved parents, untagged aliases and transliterations remain explicit; do not infer validated addresses or verified translations. No personal address records, recipients, phones, coordinates or raw sources are included. Antarctica is excluded from app profiles.

World and pilot IDs are source-scoped and may overlap geographically: do not concatenate without reviewed cross-source mapping. Pin a commit revision and verify the world manifest hashes. No model training or app deployment is performed.