Zillow price history API: turn events into a timeline

Price history is an event list

PropertiesAPI returns priceHistory as an array of events supplied by the property source. Events can include a date, event label, price, price per square foot, change rate and source. This is different from a daily valuation series or a complete legal record of property transfers.

Begin by deciding what the timeline should explain. A listing activity view may show asking-price changes and listing removals. A transaction analysis needs stronger evidence that an event represents a completed sale. Do not treat every price in the array as a sale price.

Preserve the original event labels

Retain the source event text before mapping it into application categories. Your normalized categories might include listing, price change, sale and other. Keep an other category so an unfamiliar label does not silently become a sale.

A date without a time should remain a calendar date. Converting midnight UTC into the browser’s local timezone can show the previous day for some users. If you only received YYYY-MM-DD, render that date without inventing a collection time for the event.

Build a timeline without filling the gaps

Sort a copy of the events by valid date. Keep unknown dates in a separate section or preserve their original order with an unavailable label. Do not interpolate prices between listing events and call the result observed history.

If two events occur on the same day, preserve both unless you have a documented deduplication rule. A removal and a relisting may be distinct activities. Deduplicating only by date can erase the very sequence a reader is trying to understand.

for each event in priceHistory:
    retain original label, source and raw date
    parse date only when valid
    retain null price as missing
sort dated events by calendar date
render unknown-date events separately
label the view "Source-reported property events"

Keep price history separate from tax history

Tax history describes assessment years and tax-related amounts. It has a different cadence and meaning from listing activity. Joining these into one undifferentiated price chart can imply that assessed value is a market transaction.

Use distinct tables or clearly labeled series when both matter. A tooltip should identify the field, unit and source. If your application calculates a change percentage, name the two events used and skip the calculation when either value is missing or the denominator is zero.

Handle empty and incomplete arrays

An empty priceHistory array means no events were returned. It does not prove that the home has never sold or changed price. Show “No price history returned” instead of “No prior sales.”

For research requiring complete transactions, validate against an appropriate official or licensed source. The API response is a snapshot of source-reported information at collection time. Retaining that timestamp is essential when users compare an exported timeline with a page they view later.

Review the timeline with a small test set

Include no-history, same-day-event, missing-price and unknown-label cases. Verify that filtering the chart does not alter the original event array stored for audit. A timeline should help a reader understand the source, while preserving the uncertainty and gaps that came with it.