The Layer-1 Guarantee: Geographic Coherence by Construction
The Layer-1 guarantee behind Fake Addresses is geographic coherence: every field in a generated US record — street, city, county, state, ZIP code, area code — is derived from the same single point, not assembled independently and hoped into agreement. Most competing address generators pick a street name, a city, and a ZIP code from separate lists and never check whether the three actually belong together, which is why their output routinely fails basic format validation.
Fake Addresses inverts that process. A ZCTA is picked first, then a specific point inside it — a spot on a real street — becomes the single source every other field is derived from: county and state by point-in-polygon lookup against that same ZCTA's underlying boundary data, city from the USPS last-line city assigned to that ZIP code (not the official place boundary name, which frequently differs), and area code from the North American Numbering Plan area covering that county.
Street numbers are the one field chosen for the opposite property: instead of picking a number that plausibly exists, Fake Addresses picks one deliberately outside every range the Postal Service has assigned to a delivery point on that street segment. The result of both halves together is the product itself — output that is postal-format-valid because every field agrees with every other field, and non-deliverable because the one field capable of making it real was deliberately excluded.
How a Record Is Built: the Point-First Algorithm
Building a Fake Addresses record starts with picking a ZCTA — a ZIP Code Tabulation Area, the the national statistical agency's own geographic approximation of a ZIP code, built from Census tabulation blocks rather than the point-based delivery data the Postal Service itself uses ([U.S. the national statistical agency]()). That choice is weighted by whatever the request specifies: a state, a city, or a specific ZIP code filter, never a uniform nationwide draw.
Inside that ZCTA, Fake Addresses picks a real the street reference data road-network edge — a named street segment, excluding highway ramps and alleys — whose midpoint falls inside the ZCTA's boundary, then interpolates a point somewhere along that edge, offset slightly to one side or the other depending on which side even-numbered and odd-numbered addresses fall on. That single point becomes the record's coordinates.
From that point, everything else follows by point-in-polygon lookup: which county polygon contains it, which state, which time zone from a county-level table (with split counties handled by their actual polygon boundary, not a single flat assumption). The city comes from a separate lookup — the USPS last-line city assigned to that ZIP code — because official place boundary names and USPS mailing-city names frequently disagree, especially in unincorporated areas.
The area code comes from the North American Numbering Plan area or areas serving that county, matched against rate-centre data. The street number is the final field: an integer outside every address range shown as already assigned on that edge, with the correct parity for the side of the street the point falls on, formatted per USPS Publication 28's abbreviation rules.
What the Nightly Validation Harness Checks
Fake Addresses runs every check below on 2,000 sampled records on every pull request, and on 10,000 records nightly:
| Check | Method |
|---|---|
| Point inside ZCTA | Point-in-polygon |
| County, state, time zone correct | Point-in-polygon on the output coordinates |
| City correct | **Not yet assertable.** Every record currently uses the official place boundary name and is flagged city_source: place_boundary, excluded from this claim until the USPS ZIP-to-city table is built |
| Area code valid | NPA is one of the set serving that **state**. No free county or rate-centre NPA source exists, so county-level precision is not claimed |
| Street exists | Edge name is present in the road-network data for that ZCTA |
| Street number non-deliverable by construction | Outside every address range the Census road network publishes for that segment, on both sides, parity-matched. other open address data is **not** currently checked — it has not been ingested |
| Format | Round-trips through a US address parser with identical fields |
| Reserved values | Phone 555-0100 to 555-0199; email on RFC 2606 reserved domains; SSN area 000/666, group 00; card numbers only published sandbox PANs |
| Determinism | Same seed and dataset version returns byte-identical output |
Limits of This Method
Limits of this method exist, and publishing them here is part of the guarantee, not an admission against it. A ZCTA is an approximation, not an exact match for a ZIP code: some valid ZIP codes, particularly PO-box-only and single-organization ZIP codes, have no corresponding ZCTA at all, and Fake Addresses never emits those as street-address ZIP codes for that reason.
The USPS last-line city lookup depends on a free USPS developer API call made at data-build time. If that lookup is ever unavailable for a specific ZIP code, Fake Addresses falls back to the official place boundary name instead, and that record is flagged with a city_source: "place_boundary" marker and excluded from the full coherence claim rather than silently presented as USPS-verified.
Area code mapping is done at the county and rate-centre level, which is accurate for the overwhelming majority of numbers. It is an approximation where a single county is served by more than one rate centre with different area codes assigned unevenly across it — Fake Addresses picks a valid NPA for the county, not a guarantee of the exact NPA a specific real address would be assigned.
The nightly non-deliverability sample checks a fixed number of freshly generated records against live USPS Delivery Point Validation, not every record ever generated historically — it is a statistically meaningful, continuously re-run sample, not an exhaustive audit of every possible output. International coverage varies by country and is labelled accordingly: 'full' where point-level source data exists, 'admin-area' where only regional boundaries are available, and 'format-only' where Fake Addresses can format an address correctly but does not yet guarantee geographic coherence within that country.
Dataset Versions and Reproducibility
Dataset versions stamp every record Fake Addresses generates, in the form YYYY.MM, so a seed's output can be reproduced even after the underlying data is refreshed. Every API response and bulk export carries its dataset version explicitly; a caller who wants a past data shape can request it by version rather than getting whatever the current refresh happens to produce.
A data refresh — new road-network edges, an updated USPS city table, a corrected county boundary — always produces a new dataset version rather than silently changing an existing one. Old dataset versions stay addressable for at least twelve months, specifically so a ?seed= value pinned in a committed CI fixture keeps returning the exact record it returned the day the fixture was written, even years later.
This is the same discipline that makes the coherence guarantee auditable rather than just asserted: because every record is tied to a specific, versioned build, the validation-harness results described above apply to a specific, named dataset version, not a vague, continuously shifting 'current state' that would be impossible to independently verify after the fact. The full algorithm, source by source, is published openly rather than kept as a trade secret — a QA engineer who wants to verify a specific claim here can read the same working the validation harness itself runs against.
Frequently asked questions
Is Fake Addresses' output guaranteed to be non-deliverable?
Not as an absolute, unprovable guarantee — as a measured, re-checked figure, once the nightly Delivery Point Validation sample has run. That sample has not run yet, so Fake Addresses does not publish a non-deliverability count today; when it does, the number will be read directly from the log, never typed by hand, and the build stops shipping if a sample is ever not clean.
What happens if a Fake Addresses record turns out to be real and deliverable?
The nightly sample is built to catch exactly that. If any record is confirmed deliverable, the build fails, the specific street-number range involved is added to an exclusions list, and the public non-deliverability figure pauses until the next clean sample.
Does Fake Addresses guarantee the same coherence level for every country?
No. Each country ships with an explicit coherence level shown on its page — 'full' where point-level source data exists, 'admin-area' where only regional boundaries are available, or 'format-only' where the address format is correct but geographic coherence within the country is not yet guaranteed.
Why does the mailing city sometimes differ from what I'd expect?
Fake Addresses uses the USPS last-line city for a ZIP code, not the official place boundary name, because those two names frequently disagree — an unincorporated area, for example, often has a official place boundary name the Postal Service never uses on mail.
Sources
- U.S. the national statistical agency — A ZCTA (ZIP Code Tabulation Area) is a the national statistical agency geographic approximation of a ZIP Code built from Census tabulation blocks; not every valid ZIP Code has a 2020 ZCTA.
- United States Postal Service — Postal Explorer — USPS Publication 28 defines a "standardized address" as one using official USPS abbreviations, and a "complete address" as one containing everything needed to match the ZIP+4 and City State files.