# Generator data sources

The address generators select complete public business or institution addresses from `real-address-data.ts`. Street text, place name, city, administrative area and postal code remain associated with one source record. See [the import sources and selection rules](REAL_ADDRESS_DATA_SOURCES.md). `SUPPORTED_LOCATIONS` and `INTERNATIONAL_LOCATIONS` are selectable city/region/postal tuples derived from that address pool; their lengths are not counts of individual addresses or population coverage.

Every output includes `placeName` and `source` (`addressId`, `dataset`, `url`, `runId`, `retrievedAt`). `quality.addressStatus` is `source_backed`; `quality.identityStatus` is `generated`. The deprecated `fictional: true` field refers only to the composite profile's generated identity and is retained for compatibility. A source-listed address does not establish current delivery service or the identity of a resident. Delivery and phone assignment remain `not_checked`.

Names and phone numbers are generated independently of the place. US numbers use a representative state area code with NANPA's fictional `555-0100`–`555-0199` subscriber range. Other countries retain their documented reserved-range or format-only phone status. Never treat a generated name or phone as the contact for the source place.

The data version includes a content digest. Seeds replay within that version; refreshed source pools can change results. Batches sample a finite pool and may repeat addresses, including when many profiles use one filtered address. JSON, CSV, SQL and text exports retain source identifiers, URLs, run IDs and retrieval dates. Address-only copy excludes the generated identity.

`postalCodeStatus` distinguishes `provided`, `not_used` (Hong Kong and UAE) and `not_provided`. Missing regions and postal codes remain null. Invalid generator/API filters fail explicitly; website consumers should clear stale saved filters and explain the reset.

## Separate ZIP-only directory

`@workspace/generator/zip-catalog` retains the original 261 city/state/ZIP tuples: 250 curated GeoNames rows (the first 25 lexicographically sorted postal rows for each of 10 launch cities), four municipal-contact examples, and seven later major-city additions. `ZIP_LOCATIONS`, `generateZipCodes`, `matchingZipLocations`, `formatZipCode` and `exportZipRecords` provide ZIP-only output with no street, name or phone. The address generator does not import this directory at runtime.

- Archive SHA-256: `BB5F1CE8923414EF22A6D2412B18CADF3203B781F0119F6BA54A75E9D91E7A4A`
- License: [CC BY 4.0](https://www.geonames.org/about.html)
- Attribution: GeoNames
- Dataset caveat: supplied as-is; it does not establish current USPS delivery, a building, a street, or a resident.

The municipal-contact examples are Wilmington, DE 19801 ([city government](https://www.wilmingtonde.gov/government)), Concord, NH 03301 ([city contact](https://concordnh.gov/184/Contact)), Helena, MT 59601 ([city transportation systems](https://www.helenamt.gov/Departments/Transportation-Systems)), and Anchorage, AK 99501 ([state commerce directory](https://www.commerce.alaska.gov/web/dcra/StaffDirectory)). They establish ZIP-directory locality tuples only.

Run `node scripts/extract-curated-geonames.mjs path/to/US.txt` after downloading and extracting the archive to inspect the historical ZIP selection. Old population/locality datasets remain available to their maintenance scripts but are not imported by the address generators.