`docs/source-matrix.md`

58 lines
# Source / licensing matrix — pastdoor v0.1 pilot

Per the deep-research-report editorial-tiers + the status-audit's source/licensing requirement.
Each row answers: where does the data come from, what is the access mode, what's the freshness window, what does the license allow, who owns it. **Tier A is the system-of-record; Tier B is archival depth; Tier C is verified secondary; Tier D is editorial leads only — never published.**

## Property history (BH pilot scope)

| Layer | Source | Access mode | Freshness | License / use | Tier | Notes |
|---|---|---|---|---|---|---|
| Parcel + APN + assessment | LA County Assessor (assessor.lacounty.gov) | Web portal address/APN search; bulk requires data-services request | ~daily | Public record; may not redistribute as bulk dataset without agreement | A | `parcel.apn` matches the AIN format `XXXX-XXX-XXX` |
| Parcel geometry | LA County GIS Open Data Portal (egis-lacounty.hub.arcgis.com) | Bulk GeoJSON / Shapefile download | annual snapshot | Open data; attribution required | A | We store as `parcel_version.geometry_geojson` until PostGIS lands |
| Recorded deeds & sales | LA County Registrar-Recorder/County Clerk | In-person / mail-order document retrieval; **no clean address-based online index** | per-recording | Public record; per-document copy fees | A | Non-trivial to ingest at scale — our seed sales rows are placeholder until a recorder workflow is contracted |
| City zoning / land use | LA City Planning — ZIMAS | Web portal; partial APIs | weekly | Public information | A | Beverly Hills properties are not in ZIMAS; BH has its own permit system |
| Building permits — BH | City of Beverly Hills | Nightly issued-permit dataset published by the city | daily | Public information | A | Our `place_event.kind='permit'` rows seed from this feed (not yet ingested live) |
| Building permits — LA City | LA Dept. of Building & Safety | Records request workflow + LADBS portal | per-application | Public information | A | Out of pilot scope; later expansion |
| Sanborn fire-insurance maps | Library of Congress — Sanborn Maps Collection | Free public download (TIFF/JP2) | static (1867–1970s) | Public domain (works of US gov + expired copyright) | B | Powers historical context; `media_asset.kind='historic_map'` |
| Architectural photo documentation | HABS / HAER (Library of Congress) | Free public download | static | Public domain | B | `media_asset.kind='archival_photo'` |
| Local archive — BH | Beverly Hills Public Library (Local History) | On-site research; selective digitization | per-collection | Research-use; credit required | B | Photographs, surveyor field books, postcards |
| Architect collections | UCLA Library Special Collections, Getty Research Institute | On-site research; finding aids online | per-collection | Research-use; credit required | B | Paul R. Williams papers (UCLA), A. Quincy Jones papers (UCLA) |
| Newspaper archives | LA Times historical archive (paid), Newspapers.com | Subscription | per-issue | Editorial-use citation | C | Verified date + page citation required before publish |
| Wikipedia | Wikipedia / Wikidata | Open API | live | CC-BY-SA-4.0 | C | Acceptable as cross-reference; never the sole source for an association |
| Find-a-Grave / Familysearch | Genealogy databases | Some open / some paywalled | live | Site-specific TOS | C | Vital years for entity records only |
| Google Street View | Google Maps Platform | Embed iframe (no key) + Maps JS API + Static API (key required) | rolling | Per Google Maps Terms — embed is allowed, redistribution is not | A (current) / Display-only (historical) | Live SV is the address page hero; year-by-year requires `NEXT_PUBLIC_GOOGLE_MAPS_API_KEY` |
| Census ACS | US Census Bureau | Bulk download / API | annual | Public domain | A | Used for neighborhood context, never per-address |
| Rental price anchor | FRED `ATNHPIUS06037A` (LA HPI) + `CUURA421SEHA` (BLS rent CPI) | Free CSV | quarterly | Public domain | A | Drives the 1978–1984 anchor curve in `data/multiplier_1978_1984.json` |

## Out of scope for v0.1

- **Current celebrity addresses** — explicitly excluded by policy + DB privacy trigger.
- **Active MLS data** — license-restricted; we link out, never mirror.
- **Active Airbnb / VRBO listings** — TOS prevents bulk scraping; sponsored placements come voluntarily.
- **STR / home-share regulation copy** — too jurisdiction-specific to write generically; will be added per-city only after legal review.

## Ingest strategy (per the status audit's recommendation)

1. **Official-source-first** — the system-of-record is always Tier A. Tier B/C ride on top.
2. **Append-only** — every event goes through `place_event` with `valid_from/valid_to/recorded_at`.
3. **Provenance per row** — `source_tier`, `source_label`, `source_url`, `confidence` are required, not optional.
4. **Editorial review queue** — Tier D never reaches `public_visible=true` without review.
5. **Probabilistic match for noisy keys** — when the source's address string doesn't normalize cleanly to a known APN, queue for review rather than auto-link.

## Data we plan to license / contract

- Recorder document retrieval workflow (LA County) — for selected addresses with strong demand
- BH nightly permit feed — confirm redistribution rights with the city before mirroring
- LA Times archival photo licensing — per-image, on demand
- Spatial parcel polygons at scale — LA County GIS open data is sufficient for v0.1

## Per-record provenance schema

Every public-facing record carries:
- `source_tier` — A | B | C (D is editorial-only, never public)
- `source_label` — human-readable origin ("LA County Assessor", "BH Public Library")
- `source_url` — link to the canonical record where possible
- `confidence` — 0.0–1.0 numeric
- `review_status` — pending | approved | rejected
- `public_visible` — boolean gate