Property timeline
New Zealand property pages show a Property timeline: every recorded sale with its price and council sale type, every past council valuation, the decade the home was built and building consents. The data comes from the “Property timeline” section of homes.co.nz address pages.
Architecture
Section titled “Architecture”enrichment dispatcher (NZ lane) └─ homes-co-nz linker (FindListingData) ├─ GET gateway.homes.co.nz/address/search find the homes.co.nz property ID ├─ GET gateway.homes.co.nz/properties property card (rooms, areas, current CV) └─ GET gateway.homes.co.nz/property/{id}/timeline │ ▼ PropertyUpdateMessage.timeline (property-updates topic) CouncilValuation.history (council-ratings topic) │ ▼ Mill: property_timeline_events ──► GET /api/v1/properties/{id}/timeline ──► PropertyTimeline componentThe linker runs for every New Zealand property the enrichment scheduler queues, and every property is re-queued once it is two days stale, so all NZ listings pick up a timeline without a separate job. Properties first scraped from homes.co.nz get theirs at their first enrichment pass.
A failed timeline request does not fail the link: the property card data and source links are still submitted.
homes.co.nz event mapping
Section titled “homes.co.nz event mapping”homes.co.nz key |
Pillow type |
Fields kept |
|---|---|---|
property_sale |
sale |
price (absent when undisclosed), sale_type, sale id |
valuation |
valuation |
capital_value, land_value, improvement_value |
built |
built |
decade_built |
consent |
consent |
description, consent_id |
user_valuation |
dropped | Owner-entered estimates are not authoritative |
Valuation events are also sent as the council valuation’s history, which fills the existing Council valuation history chart.
Mill storage
Section titled “Mill storage”property_timeline_events (migration 21) holds one row per event with its source. Each update replaces the events stored from each source present in it, so corrections and merged sales on homes.co.nz carry through; an update with no events changes nothing. Mill validates events on write (known type, YYYY-MM-DD date between 1800 and next year, valuations need a capital value) and keeps at most 200 per source. Reads return events newest first and drop events another source already reported.
Every event carries the site that reported it. Enrichment updates carry the property’s own source (often openstreetmap.org), so linkers must set each event’s source.
| Endpoint | Purpose |
|---|---|
GET /api/v1/properties/{id}/timeline |
Timeline, newest first (empty list when none, 404 for no property) |
The MCP server exposes it as get_property_timeline.
Display
Section titled “Display”The timeline card shows the last sale price, years since the last sale and the latest CV, filters for sales and valuations, and each event with its change from the previous sale or valuation. Sale type codes (S11, M11, X11 and so on) are explained in plain language. Long timelines collapse to six events.