# Zillow ZIP Market Scraper (`structlabs/zillow-zip-market-scraper`) Actor

Scrape Zillow search results by ZIP, city or URL for forSale, forRent and recentlySold. Reads the JSON search API (3.2 KB per listing), extracts full hdpData.homeInfo with zestimate, rent Zestimate, tax assessed value and days on Zillow, and auto-splits price bands above 800 listings.

- **URL**: https://apify.com/structlabs/zillow-zip-market-scraper.md
- **Developed by:** [Mohit Tripathi](https://apify.com/structlabs) (community)
- **Categories:** Real estate
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.76 / 1,000 listing scrapeds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Zillow ZIP Market Scraper

Scrape Zillow search results by **ZIP, city, lat,lng or Zillow URL** for `forSale`, `forRent` and `recentlySold`. Reads Zillow's JSON search API directly — no browser — and returns one row per listing with the full `hdpData.homeInfo` block.

- **Pay per event:** `listing-scraped` **$2.00 / 1,000 rows** + `apify-actor-start` $0.05 / 1,000 starts.
- **3.19 KB per listing** on the JSON API vs 15.62 KB/listing on the HTML `__NEXT_DATA__` route (and the HTML route is 403 for datacenter *and* residential clients).

### Input

| Field | Type | Default | Notes |
|---|---|---|---|
| `locations` | array | `["10001"]` | ZIP, city/state, `lat,lng`, or Zillow search URL. |
| `status` | string | `forSale` | `forSale`, `forRent`, `recentlySold`. |
| `priceBands` | array | auto | Optional `{"min":0,"max":250000}` bands; auto-generated above 800 listings. |
| `maxListings` | integer | `500` | Hard stop; billing stops here. |
| `maxPagesPerBand` | integer | `20` | Zillow caps pagination at ~20 pages. |
| `requestTimeoutSecs` | integer | `30` | Per request. |

Prefill (`10001`, for sale, 1 page) runs in ~5.5 s.

### Output

```json
{
  "zpid": "72515759",
  "status": "Condo for sale",
  "price": 1999000,
  "price_text": "$1,999,000",
  "currency": "USD",
  "price_period": "total",
  "address": "133 W 17th St APT 3A, New York, NY 10011",
  "city": "New York",
  "state": "NY",
  "zip": "10011",
  "latitude": 40.740005,
  "longitude": -73.996635,
  "home_type": "CONDO",
  "bedrooms": 2,
  "bathrooms": 2,
  "living_area": 1400,
  "lot_size": null,
  "lot_size_unit": null,
  "year_built": null,
  "days_on_zillow": 7,
  "zestimate": 1739100,
  "rent_zestimate": 8431,
  "tax_assessed_value": null,
  "price_change": null,
  "price_history": null,
  "is_building": false,
  "is_zillow_owned": false,
  "image_url": "https://photos.zillowstatic.com/fp/8a1f015a912a338aff11c00d5465e7ee-p_e.jpg",
  "url": "https://www.zillow.com/homedetails/133-W-17th-St-APT-3A-New-York-NY-10011/72515759_zpid/",
  "price_band": null,
  "source": "zillow.com",
  "scraped_at": "2026-11-20T09:40:12.000000+00:00"
}
```

Rentals use `price_period: "monthly"` and `price` = monthly rent. Apartment-building cards (`is_building: true`) have no `hdpData`; their `price` is `minBaseRent`.

### Cost

| Volume | `listing-scraped` | Actor starts | Total |
|---|---|---|---|
| 1,000 listings | $2.00 | $0.05 | **$2.05** |
| 10,000 listings | $20.00 | $0.05 | **$20.05** |

No charge for blocked pages, empty pages, duplicates, or rows without `zpid` plus price/address.

### Source notes (verified)

- HTML search pages (`/homes/10001_rb/`) return **403** for both the datacenter IP and residential proxies — `__NEXT_DATA__` is not a usable route.
- `PUT https://www.zillow.com/async-create-search-page-state` returns JSON with `cat1.searchResults.listResults` and `categoryTotals.cat1.totalResultCount`: **41 listings, 133,898 bytes → 3.19 KB/listing**. That is **80% smaller** than the 15.62 KB/listing HTML figure.
- `searchQueryState` needs `usersSearchTerm` **plus** `mapBounds` plus `isMapVisible: true`; a term alone returns zero results, and Zillow resolves the region from the map box (not the term).
- Status filters: the full `isForSaleByAgent` / `isForSaleByOwner` / `isNewConstruction` / `isComingSoon` / `isForSaleForeclosure` / `isForRent` / `isRecentlySold` block must be sent; a single `isForRent` flag returns nothing.
- Price filter: `filterState.price = {"min": ..., "max": ...}` works (verified 0–250k → 8 results, 1M–1.5M → 476 results).
- Pagination: `pagination.currentPage`; 41 per page, ~20 pages max.
- ZIPs are geocoded to a centroid with zippopotam.us, then searched in a ±0.008° lat / ±0.010° lon box and filtered to the exact ZIP. Cities use Nominatim's bounding box.
- Direct requests are blocked; every request goes through Apify **Residential** proxy with 5 attempts, 3–15 s backoff. A blocked page is skipped and never billed.

### Price-band splitting

When `totalResultCount > 800` (and `maxListings > 200`):

1. Probe the location, then query bands `0–250k`, `250–500k`, `500–750k`, `750k–1M`, `1M–1.5M`, `1.5M–2M`, `2M+` (rentals: `0–1k`, `1–2k`, `2–3k`, `3–5k`, `5k+`).
2. Any band still above 800 is split in half again, up to depth 3.
3. Results merge and dedupe by `zpid`.

Verified on Austin, TX: 7,514 for-sale listings → bands split (`0–250k` = 827 → `0–125k` / `125k–250k`, `250–500k` = 3,757 → `250–375k` / `375–500k`, …), 250 unique listings returned with no duplicates.

### MCP

```json
{
  "actor": "structlabs/zillow-zip-market-scraper",
  "input": {"locations": ["10001", "Austin, TX"], "status": "forSale", "maxListings": 250}
}
```

### Local verification

- 20-input gate with `ACTOR_TEST_PAY_PER_EVENT=true apify run`: **18/20 returned rows, 20/20 clean** (zero exceptions, zero duplicates, correct ZIP on every ZIP run). The two zero-row runs were ZIP `30301`, a PO-box-only ZIP with no Zillow inventory; the same cases with `30305` returned 41 and 45 rows.
- Median 10.9 s per run; the 250-listing banded Austin run took 89 s.
- `hdpData.homeInfo` fields (`zestimate`, `rentZestimate`, `taxAssessedValue`, `daysOnZillow`) present wherever Zillow publishes them.

### Pricing source

Canonical store-discount ladder (FREE/BRONZE/SILVER/GOLD/PLATINUM/DIAMOND) lives in `pricing.json`. Apify `actor.json` cannot carry pricing and `apify push` does not change account pricing; after any manual API change, the newest `pricingInfos` record must match `pricing.json`.

### n8n Workflow & MCP Quickstart

Run this Actor from an AI agent over MCP, or import the ready-made n8n workflow:

- n8n workflow, MCP config and quickstarts: https://github.com/structlabs-hq/zillow-zip-market-scraper-n8n-mcp
- MCP endpoint: https://mcp.apify.com/?actors=structlabs/zillow-zip-market-scraper

# Actor input Schema

## `locations` (type: `array`):

ZIP codes (10001), cities (Austin, TX), lat,lng pairs, or Zillow search URLs. Each location is geocoded to a map box and queried separately.

## `status` (type: `string`):

forSale, forRent or recentlySold. Each status uses Zillow's own filter set.

## `priceBands` (type: `array`):

Optional list of {"min":0,"max":250000} bands. Leave empty to auto-split when a location publishes more than 800 listings.

## `maxListings` (type: `integer`):

Hard stop. Each pushed listing is one listing-scraped billing event.

## `maxPagesPerBand` (type: `integer`):

Zillow caps search pagination at about 20 pages (roughly 820 listings).

## `requestTimeoutSecs` (type: `integer`):

Per search request.

## Actor input object example

```json
{
  "locations": [
    "10001"
  ],
  "status": "forSale",
  "maxListings": 41,
  "maxPagesPerBand": 1,
  "requestTimeoutSecs": 30
}
```

# Actor output Schema

## `dataset` (type: `string`):

No description

## `table` (type: `string`):

No description

## `market` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "locations": [
        "10001"
    ],
    "status": "forSale",
    "maxListings": 41,
    "maxPagesPerBand": 1,
    "requestTimeoutSecs": 30
};

// Run the Actor and wait for it to finish
const run = await client.actor("structlabs/zillow-zip-market-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "locations": ["10001"],
    "status": "forSale",
    "maxListings": 41,
    "maxPagesPerBand": 1,
    "requestTimeoutSecs": 30,
}

# Run the Actor and wait for it to finish
run = client.actor("structlabs/zillow-zip-market-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "locations": [
    "10001"
  ],
  "status": "forSale",
  "maxListings": 41,
  "maxPagesPerBand": 1,
  "requestTimeoutSecs": 30
}' |
apify call structlabs/zillow-zip-market-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,structlabs/zillow-zip-market-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/vo81UNnaizfNhToqe/builds/B0XcCN7rCw0mpX5bz/openapi.json
