# Public location address data

`src/real-address-data.ts` is a finite pool of publicly listed physical business and postal-service addresses. Each selected row keeps its street/building line, locality, available administrative region, and postcode together. Government offices, museums, universities and other noncommercial institutions are excluded from the active pool. These are not a residential-address register, a nationwide address census, a list of people living at those addresses, or a postal deliverability service.

## Sources and permissions

- [All the Places](https://alltheplaces.xyz/) publishes its location data under [CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/). Its [data documentation](https://github.com/alltheplaces/alltheplaces/blob/master/DATA_FORMAT.md) explains source URLs, address fields, and limitations. The importer uses a pinned weekly build, not the mutable latest build, and retains the originating organization's public URL on every row.
- `scripts/public-place-sources.mjs` configures the candidate sources and their business categories: banks, post offices, supermarkets, convenience stores and restaurants take priority, followed by other retailers, then hotels. Categories describe the source business, rather than being guessed from a street name. Empty, missing or malformed optional outputs in the pinned build are recorded in the local import report and never produce addresses.
- Daily-service candidates include Bank of America, Lloyds, Deutsche Bank, VTB, Georgian banks, HDFC, BCI, PUMB, Denizbank, SinoPac, Standard Chartered, Japan Post, NZ Post, 7-Eleven group stores, Carrefour, Aldi, McDonald's/McCafé, KFC and local pizza chains. A configured source is not a claim that it contributes accepted records: consult the selected pool/report for actual country coverage.
- `apple`: public Apple retail-location pages, used as an alternative to mainland China's Aldi supermarkets and in other locations with insufficient daily-service coverage.
- `marriott_hotels`: Marriott's public property records. Selected U.S. records preserve the source's city–state–ZIP combination. U.S. selection keeps every available state, reserves multiple records for major cities and tax-free-state destinations, and fills the remaining capacity by cycling through states and cities. Within a city quota it prefers different streets and postal codes. The default pool remains capped at 800 records; quotas never create extra records when the accepted source has fewer addresses.
- `ihg_hotels`: limited to countries where it supplements a smaller pool; it is not accepted indiscriminately. The source sometimes puts a province in the city field or a company name in the first street line.
- `accor`: supplements selected lower-coverage countries. Only a complete source string ending in an unambiguous `, postcode CITY` can be split. Street numbers and postal codes are never synthesized or repaired by adding zeros.
- `data/official-public-addresses.json`: the existing source-fact ledger is retained. Only HayPost branches and directly corrected hotel addresses are active; its former government and noncommercial institution records are excluded by the importer.
- `data/commercial-public-addresses.json`: first-party Kapitalbank branch addresses in Uzbekistan, copied as intact street/city/postal tuples from the bank's [published branch directory](https://kapitalbank.uz/en/contacts/our-adresses/). These records retain the original source and retrieval date; no branch postcode is inferred from another location.

The current selected pool has 5,350 addresses across 42 countries and regions. Each destination has daily-service addresses. After applying user location filters, the shared generator prefers daily services, then other retailers, then hotels. Hotel-only localities remain usable. Homepage previews omit external source links and the generated-contact notice; country/region results retain those details and offer a searchable, paginated source-reference list at the bottom of the page. API and exports retain provenance.

## Import and update

```sh
node scripts/import-real-addresses.mjs
node scripts/import-real-addresses.mjs --offline
node scripts/import-real-addresses.mjs --run=2026-09-26-13-32-25 --limit=150 --us-limit=800
```

The default source build is `2026-09-26-13-32-25`. `--cache` and `--output` can override the default paths. Raw GeoJSON, SHA-256 source metadata, and the import report go only to the Git-ignored `.local-artifacts/real-address-import/<run>/` directory. Do not commit those downloads or reports. The compact TypeScript file and curated source-fact inputs are product assets. For a replacement, first write a candidate with `--output=.local-artifacts/commercial-addresses/real-address-data.ts`; verify all 42 destinations, category distribution, unique IDs and U.S. state coverage before replacing product data. Failed coverage checks occur before output is written.

Changing a source build, curated facts, selection limits, or filters may change the seed-to-address mapping. `REAL_ADDRESS_DATA_VERSION` therefore includes a digest of the selected address records, excluding retrieval timestamps. Rerunning with the same cached source and configuration produces identical product data.

Before publishing an update, review the local report's per-country counts, city diversity, missing optional fields, source distribution, excluded-record reasons, and U.S. state coverage. Cross-check at least one selected address in every supported country against the linked first-party source. A successful fetch and an apparently valid postcode pattern do not independently prove every address is current or deliverable. Do not silently replace a questionable component with a different locality's field.

## Field contract

The module exports `RealAddress`, `REAL_ADDRESSES`, `REAL_ADDRESSES_BY_COUNTRY`, `REAL_ADDRESS_COUNTRY_COUNTS`, and `REAL_ADDRESS_DATA_VERSION`. `placeType` identifies the business category. `region` and `postalCode` are nullable. Keep them nullable when the source omits an optional field or the postal destination does not use one. US/Canadian results and imported hotels require a published postcode. Elsewhere, accepted daily-service listings may omit it, and the product reports `not_provided`; Hong Kong and the United Arab Emirates use `not_used` without invented placeholders.

`sourceRetrievedAt` records when the source was retrieved. It is **not** an independent verification date, survey date, or proof of delivery. `sourceRunId` identifies the dataset build; `sourceUrl` links to the originating public place. Do not describe source timestamps as `verifiedAt`.

The records intentionally contain no person's name, personal phone number, email address, or identification details. If another feature adds a generated name or phone, those fields must remain distinct from the real public location and must not imply a relationship to it.

## Country-specific quality decisions

- Mainland China uses readable local-language Aldi and Apple sources. Aldi municipality labels are taken literally from its complete published address line. Marriott's proprietary mainland region codes are not shown as provinces.
- Marriott explicitly encodes Hong Kong as `HON_CN` and Taiwan as `TW` inside its broader China hierarchy. Those source region values route the intact record to this site's respective postal-destination pool. Macao is outside the supported pool and is omitted.
- All IHG Hong Kong rows are excluded because the source also assigns mainland Zhuhai properties to Hong Kong. Apple Hong Kong region values are omitted: the official street lines identify the location, while some ATP region assignments incorrectly label apm and Festival Walk. The addresses themselves are preserved. [Official Apple Hong Kong directory](https://www.apple.com/hk/en/retail/storelist/?v=1.0.24).
- Unexplained numeric/proprietary administrative codes are rejected. Optional obsolete `Nord-Pas-de-Calais` values are omitted rather than presented as a current French region. Address/locality fields remain the original source values; consumers may separately maintain documented label aliases for filtering.
- All 40 postcode-using supported destinations have explicit checks whenever a postcode is present. All-zero, malformed, truncated, or outdated-format postcodes are rejected, never padded or shortened. A missing optional postcode stays null. Vietnam uses five digits, as documented by [Vietnam Post](https://vnpost.vn/en/tin-khac/national-postcode-contributes-to-improving-the-quality-of-service) and the [UPU](https://www.upu.int/UPU/media/upu/PostalEntitiesFiles/addressingUnit/vnmEn.pdf).
- ATM-only entries, parcel lockers and private-box counters are excluded. Complete published address lines may be retained when a dedicated street field is missing. Source-specific literal city boundaries are parsed for Japanese prefecture/municipality prefixes, Taiwan county/district prefixes, Belarusian city-first lines, Kazakhstan Papa John's city suffixes and Denizbank district/city suffixes. Missing or ambiguous localities are rejected. Source URLs with unresolved fragments and Domino's Saudi rows that reuse their store ID as a postcode are excluded.
- Company-only street lines, isolated building numbers, P.O. Box strings, explicit placeholders, future-opening properties, and detected province/county values in city fields are excluded. Outside the UAE, the selected street/building line must contain a number. This intentionally omits some legitimate but harder-to-interpret locations; it does not manufacture a number for them.
- Protea Hotel Delta in Warri and Holiday Inn Queenstown Frankton Road are excluded because of unresolved physical-address/postcode discrepancies. No replacement postcode is guessed.
- Selected IHG locations in Tashkent, Incheon, Seoul, Auckland, and Cairo use directly curated official rows that preserve district, suburb, or street information omitted by the ATP first-line field. When an official seed has the same source URL, it replaces the ATP row. Keep all necessary physical address lines together; separate P.O. Box and optional driving instructions are not required in a street address.

Coverage is the finite number of accepted records and actual localities in the generated file. A supported country label does not imply all of its cities or postal codes are covered. Display pool-derived coverage, retain sources, and disclose when a requested filter has no matching record instead of fabricating an address.