Grains, Keys & Amenities Model¶

The three grains¶

Grain	Row type	Primary key	Foreign key
Building	`BuildingRow`	`join_key` (canonical street-address+ZIP key, used across the discovery/merge pipeline)	—
Floorplan	`FloorplanRow`	`id`	`property_id` → building
Unit	`UnitRow`	`id`	`floorplan_id` → floorplan

The warehouse additionally uses property_id as the key for joining buildings to floorplans.

Warning

Never assume join_key == property_id when joining buildings to floorplans. They are different identifiers, and conflating them silently drops or misjoins a meaningful share of Miami-area rows.

`floorplans.plan_key` — cross-source plan identity¶

Different data producers describe the same physical apartment layout differently — for example, one source's internally-generated ID versus another's own listing ID for what is in fact the same floorplan, "Abaco," at the same property. plan_key clusters rows that represent one real floorplan across producers.

It is computed over a property's whole current row set, and recomputed automatically whenever unit rows are replaced, so it self-heals as new data arrives.
Read surfaces — including the client API — collapse on plan_key and emit one floorplan per cluster.
The winner within a cluster is picked by priority: has a price > producer trust ranking > row id.
Critically, only the name is ever borrowed across a cluster. Rent from one source is never mixed with square footage from another.
A row with no assigned cluster falls back to its own id.

Amenities model¶

Amenities are tracked at three grains, each additive. To get the full amenity list for one apartment, union all three:

buildings.amenities — shared facilities (pool, gym, doorman)
floorplans.amenities — what the floorplan listing itself advertises
units.amenities — what distinguishes one specific apartment from others on the same floorplan

Each level only ever states what it adds. Absence at a given level means "not observed there," never "confirmed absent."

Amenities are stored as a JSON array (serialized as text in the CSV contract, cast to a real JSON array on API surfaces), drawn from a controlled vocabulary — an unrecognized or unmapped source string is dropped rather than passed through.

Note

Five boolean floorplan columns — washer_dryer, garage, fireplace, den_study, sunroom — remain the authoritative source for those specific amenities and are kept alongside the general amenities list rather than being replaced by it.

buildings.photo_url (the building's own photo) is distinct from floorplans.image_url (a floorplan diagram, not a photo).

Field provenance¶

Enriched fields carry a per-field provenance tag — scraped_live / derived / hud / seed — rather than being asserted as uniformly trustworthy. Downstream consumers, and the coverage-measurement tooling in particular, rely on this tag to weight confidence.

Building name & photo provenance (source-ranked, not last-writer-wins)¶

Photos. A photo's source is recorded in buildings.photos_source (none / own_site / zillow / apartments.com). A fixed rank prefers an aggregator's photo gallery over the building's own site, and an own-site photo is refused entirely if that site has failed identity verification. The first photo in the array is always also stored as photo_url, for compatibility with consumers that only read a single photo field.

Names. An aggregator-sourced name only ever replaces a placeholder name (blank, weak, or a raw copy of the owner LLC's name) — a real marketing name already on file is never overwritten. The replacement's source is recorded per-building.

Commission evidence & confidence¶

Field	Meaning
`locator_friendly`	Verdict: `Yes` / `Likely` / `No` / `Unknown`
`locator_commission`	The commission terms
`commission_basis`	What the commission is calculated against
`commission_source`	Where the commission figure came from
`locator_confidence`	Confidence tier (see ladder below)
`locator_evidence`	A stored evidence snippet supporting the verdict
`mls_coop_commission`	Filled from MLS co-op listing data when available

Confidence ladder:

High — confirmed directly, via an owner/manager statement or a published brokers page.
Medium — inferred, from a sibling property in the same portfolio or a known property-manager-wide policy.
Low — a directional estimate or heuristic.

Unknown verdicts carry no confidence value.

mls_coop_commission is treated as the highest-trust source when present. Otherwise, a scraped /brokers-style page is the top evidence tier for a commission verdict, outranking the deterministic PM-policy-table lookup — except for already-known affordable-housing listings.

A single commission discovery at one building can generalize to that property manager's other buildings on future runs via a learned PM-policy cache — a discover-once, apply-broadly feedback loop.