# Changelog of Zillow API + Market KPIs (Bridge Interactive Alternative) (`sian.agency/zillow-property-scraper`) Actor

- **URL**: https://apify.com/sian.agency/zillow-property-scraper/changelog.md
- **Full Actor documentation**: https://apify.com/sian.agency/zillow-property-scraper.md

## Changelog

All notable changes to Zillow Property Scraper will be documented in this file.

### \[2026-08-26]

#### 🆔 Fixed — MLS search mode returned nothing at all

- **`searchMode: "mls"` now actually returns properties.** Two faults had to be fixed, and either one alone still produced nothing: the MLS ID was sent under a parameter name Zillow's API accepts and then ignores, **and** this route returns a single property object where every other route returns a list, so the result was discarded even once the lookup worked. Single (`mlsId`) and bulk (`mlsIds`) lookups both work now.
- **The example MLS ID in the input form was not a real listing** — it is now a live one (`S1710866`), so the prefilled example returns a property instead of nothing.

### \[2026-07-30]

#### 🔗 Fixed — Bulk search-URL input now works

- Pasting a list of Zillow search URLs failed with "Invalid Zillow URL" before fetching anything. Bulk lists (`searchUrls`, `urlsCsv`) now work from the UI or the API, and duplicates are collapsed.

### \[2026-07-10] - 0.2.0 - 8th Search Mode: AI Prompt

#### 🆕 New search mode: `aiPrompt`

Describe what you're looking for in plain English instead of building a URL or filter set — e.g. `"3 bed house near good schools under $500k in Austin"`. Uses Zillow's own natural-language search and reuses the exact same auto-pagination, dedup, KPI engine, and HTML report as the other 7 modes.

| `searchMode` | Input fields | Tier |
|---|---|---|
| `aiPrompt` | `aiPrompt` · `aiPrompts` (PAID) | FREE+PAID |

- `listingStatus` is ignored in `aiPrompt` mode — describe status in the prompt itself (e.g. "homes **for sale** in Austin").
- Result counts and precision vary by prompt — the upstream search is documented as "not as accurate as the other search endpoints at identifying filters." Treat it as a discovery tool, not a deterministic query.
- No new pricing event — charges the existing `PropertyExtracted` event per property pushed, same as every other mode (response shape confirmed identical: `searchResults[].property` + `resultsCount.totalMatchingCount`).
- Superseded the experimental `feat/ai-prompt-search` branch scaffold, which had guessed the wrong endpoint path (`/search/by-ai-prompt`) and param name (`prompt`) — both corrected against the live OpenAPI spec (`ai_search_prompt`, no hyphen in the path) and a live test call before merge.

### \[2026-05-01] - 7 Search Modes — Multi-Endpoint Release

#### 🚀 Major Feature: Six new search modes

The actor previously only accepted a Zillow search URL. It now exposes **7 search modes** via a new `searchMode` input — every mode reuses the same auto-pagination, dedup, KPI engine, and HTML report.

| `searchMode` | Input fields | Tier |
|---|---|---|
| `url` *(default)* | `searchUrl` · `searchUrls` · `urlsCsv` (existing) | FREE+PAID |
| `address` | `addressQuery` · `addressQueries` (PAID) | FREE+PAID |
| `mls` | `mlsId` · `mlsIds` (PAID) | FREE+PAID |
| `polygon` | `polygonCoords` (≥3 `[lng,lat]` pairs) | PAID |
| `coordinates` | `centerLat` · `centerLng` · `radiusMiles` | FREE+PAID |
| `mapbounds` | `north` · `south` · `east` · `west` | PAID |
| `offmarket` | `offmarketZip` (ZIP only) | PAID |

#### 🆕 New shared inputs

- **`listingStatus`** — `For_Sale` (default) · `For_Rent` · `Sold`. Required upstream by every mode except `url` and `offmarket`.
- **`maxResultsPerQuery`** — replaces the old `maxResultsPerUrl` (legacy field removed). Default lowered from 42 → **40** so a default click-Run finishes in exactly ONE upstream API request across every mode (URL pages return ~41 listings; the old default of 42 forced a wasted second fetch for one extra item).

#### 🔁 Backward-compatible

- Default `searchMode` is `url` — existing runs and saved configs work unchanged.
- Output dataset adds a `sourceQuery` field (always populated); `sourceUrl` is now nullable for non-URL modes.

#### 🆕 What's new under the hood

- New `src/modules/searchModes.js` registry — one entry per endpoint with `validate` / `buildParams` / `describe` / per-mode `extractResults` / `extractTotal` / `transform` overrides. Adding a future search mode is a single-file PR.
- `searchByMode(mode, params, apiKey)` replaces `searchByUrl()` and dispatches to the right upstream endpoint.
- New `transformPropertyV2` adapter — the new endpoints return a wrapped `searchResults[].property` shape with restructured fields (`bedrooms`/`bathrooms`/`livingArea`, address as object, `location.{lat,lng}`, `price.value`, nested `taxAssessment`, `media.allPropertyPhotos.medium[]`); URL mode keeps the original `transformProperty`.
- HTML report subtitle and per-query table now show which mode produced the data.

#### ⚠️ Breaking

- `maxResultsPerUrl` input field has been **removed**. Any saved configs / scheduled runs / API callers using the old name need to switch to `maxResultsPerQuery` (same semantics).

### \[2026-04-30] - Market Intelligence Update

#### 🚀 Major Feature: Market Diagnostics Built In

- **🌐 Total inventory count** - Every run now returns Zillow's full `total_results` count for the search, exposed via the new "Search Totals" output. See your market depth at a glance.
- **🔄 Auto-pagination** - One URL, all pages. We automatically paginate `/2_p/`, `/3_p/`, ... up to your `maxResultsPerUrl` cap. No more manual page suffix juggling. Optionally append `/N_p/` to start from a specific page.
- **📈 Market KPIs out of the box** - Each run produces a `market-kpis.json` record and HTML dashboard with:
  - **Investor signals**: median gross rental yield, price-to-Zestimate ratio, price-to-tax-assessed ratio
  - **Market depth**: coverage ratio (pulled vs available), stale-listing share (>60 days on market)
  - **Distribution stats**: min/median/avg/p90/max for price, area, $/sqft, beds, baths
  - **Inventory breakdown**: counts by home type, home status, status type
- **🎨 Redesigned HTML report** - New KPI cards, distribution snapshot, inventory breakdown, and per-URL totals table

#### 🆕 Outputs Added

- `searchTotals` (`search-totals.json`) - per-URL `total_results`, pages scraped, properties pushed, start page
- `marketKpis` (`market-kpis.json`) - all computed KPIs in structured JSON, ready for downstream pipelines

#### 💼 Why this matters

No other Zillow scraper on the Apify Store returns inventory count, rental yield, or stale-share — actionable signals investors and analysts need *before* they look at individual listings. We turn raw scrape into a market diagnostic.

#### 🎉 Zillow Property Scraper - Launch!

- **Paste-a-URL Simplicity** - Paste any Zillow search URL and get clean structured property data instantly
- **30+ Fields Per Property** - Full address, price, beds/baths, sqft, Zestimate, Rent Zestimate, tax assessed value, GPS coordinates, all photos, 3D and video flags
- **Bulk + CSV Input** - Process unlimited Zillow search URLs in one run via array or CSV upload (PAID tier)
- **Auto Deduplication** - Same ZPID appearing across paginated pages is removed automatically — no double-charging
- **Pay-Per-Property Pricing** - Flat $0.003 per property extracted, $0.005 per run start. Only pay for what you get.
- **FREE Tier** - Try it free with 25 properties per run, no credit card required
- **All US Markets Covered** - Works on every Zillow search URL: city, state, ZIP, map bounds, filtered searches, for-sale, for-rent, and sold listings

#### 💎 User Benefits

- Zero coding required — paste a URL, click Run, download JSON or CSV
- Reliable structured data with consistent schema across runs
- Time savings: 100 properties extracted in under 30 seconds
- Cost transparency: pay-per-result pricing, no hidden fees
- Export to Excel, Google Sheets, or directly into your CRM via API

#### 🎯 Use Cases

- Real estate investors finding properties priced below Zestimate for off-market outreach
- Real estate agents building comparative market analyses (CMAs) from recently sold listings
- Proptech teams running multi-city pricing trend research with CSV bulk upload
- Buy-to-rent investors calculating rental yield from price + Rent Zestimate
- Real estate agencies enriching CRM lead lists with property photos, GPS, and Zestimate
- Tax appeal services identifying over-assessed properties via tax assessed value vs price
- Property aggregator and directory sites bootstrapping their listing databases