# Zillow Research Home Value & Market Heat Scraper (`dataspryva/zillow-research-home-value-and-market-heat-scraper`) Actor

Get US state-level home value trends, active-listing inventory, and metro-level market heat index data from Zillow's published research files. Filter by state and cap the number of records returned.

- **URL**: https://apify.com/dataspryva/zillow-research-home-value-and-market-heat-scraper.md
- **Developed by:** [Dataspryva](https://apify.com/dataspryva) (community)
- **Categories:** Real estate, Automation, Lead generation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.49 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
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 Research Data Scraper — ZHVI, ZORI & Market Heat

Download Zillow Research's public housing datasets as clean rows for analytics, dashboards and market reports. Choose from 208 home-value, rent, inventory, days-on-market, price-cut, sales, market-heat, forecast, new-construction and affordability files, for the US, states, metros, counties, cities, ZIP codes and neighborhoods Zillow publishes. No Zillow account, API key or proxy is needed.

### What this actor does

- **208 datasets in one actor:** every live file on Zillow's research data page, including all ZHVI cuts (all homes, SFR, condo, bedrooms, tiers), ZORI rent cuts, inventory, new listings, pending listings, median list price, sale prices, sales counts, days to pending/close, price cuts, sale-to-list, percent sold above/below list, market heat, ZHVF/ZORF forecasts, new construction and affordability.
- **Four modes:** `latest` returns one row per region with the newest value and 1-month, 3-month and 1-year changes; `history` returns tidy rows for every region and date; `snapshot` returns a 12-metric view for selected metro regions with rent-to-price yield; `catalog` lists the available datasets.
- **Region and date filters:** match names or Zillow RegionIDs, and select an inclusive date range.
- **Zillow join keys:** records carry `regionId`, `sizeRank`, `regionName` and `regionType` so they join cleanly to other Zillow series.
- **Uses only published research files:** it reads Zillow's CSV files, not the listings site, so it is not affected by listing anti-bot walls.
- Empty values are omitted from records rather than returned as `null`.

### Output per observation

One record per region in `latest` mode, or per region and date in `history` mode:

- `recordType` — `observation`, `metricSnapshot` or `dataset`
- `datasetId`, `category`, `metric`, `metricName` — the selected dataset and metric
- `geography`, `frequency` — `metro`, `state`, `county`, `city`, `zip`, `neighborhood` or `us`; `monthly` or `weekly`
- `regionId`, `sizeRank`, `regionName`, `regionType` — Zillow's region identity
- `stateName`, `state`, `city`, `countyName`, `metro` — location fields, with state/county/metro filled in when Zillow leaves them blank
- `stateFips`, `municipalCodeFips` — present in county-level files
- `date` — observation date (`YYYY-MM-DD`)
- `value` — numeric value in the dataset's `unit`
- `unit` — `USD`, `USD/month`, `USD/year`, `USD/sqft`, `percent`, `days`, `count`, `index`, `ratio` or `years`
- `latestValue`, `latestDate` — newest value in `latest` and `snapshot` modes
- `change1mPct`, `change3mPct`, `change1yPct` — changes in `latest` and `snapshot` modes when prior values exist (4-week, 13-week and 52-week offsets on weekly datasets)
- `grossRentalYieldPct` — annual rent divided by home value, when a snapshot has both ZORI and ZHVI
- `baseDate`, `horizonMonths` — forecast origin and horizon (1, 3 or 12 months) on forecast rows
- `sourceUrl`, `dataSource`, `scrapedAt` — the exact file read and the download time

In `catalog` mode, each record describes one dataset: `datasetId`, `category`, `metric`, `metricName`, `geography`, `frequency`, `unit`, `dataType`, `firstDate`, `lastDate`, `sizeBytes`, `isForecast` and `sourceUrl`.

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `mode` | string | `latest` | `latest`, `history`, `snapshot` or `catalog`; `search`, `stateValues` and `nationalTrends` are kept for old saved tasks and return the previous wide format |
| `dataset` | string | `market_temp_index_metro_uc_sfrcondo_month` | One of 208 Zillow Research datasets; the picker labels each by category, metric, geography and variant |
| `customDatasetUrl` | string | – | Advanced: a newer Zillow Research CSV URL, if Zillow adds a file before this actor's catalog is updated |
| `regions` | array | – | Region names or substrings, e.g. `["Austin, TX"]`, `["Texas"]`, `["90210"]`; empty for all |
| `regionIds` | array | – | Exact Zillow RegionIDs; if set with `regions`, a row must match both |
| `startDate` | string | – | Inclusive start date, `YYYY-MM-DD` |
| `endDate` | string | – | Inclusive end date, `YYYY-MM-DD` |
| `includeChanges` | boolean | `true` | Add 1-month, 3-month and 1-year changes in `latest`/`snapshot` |
| `snapshotMetrics` | array | all 12 | Metrics to include in `snapshot` mode |
| `category` | string | `all` | Filter the catalog by category in `catalog` mode |
| `maxItems` | integer | `1000` | Record cap, 1–100,000 |

#### Example: latest home values and market heat for Austin

```json
{
  "mode": "latest",
  "dataset": "zhvi_metro_uc_sfrcondo_tier_0_33_0_67_sm_sa_month",
  "regions": ["Austin, TX"],
  "includeChanges": true
}
```

#### Example: full rent history for one metro

```json
{
  "mode": "history",
  "dataset": "zori_metro_uc_sfrcondomfr_sm_month",
  "regions": ["Austin, TX"],
  "startDate": "2015-01-01",
  "maxItems": 500
}
```

#### Example: 12-metric snapshot for a city

```json
{
  "mode": "snapshot",
  "regions": ["Austin, TX"],
  "snapshotMetrics": ["zhvi", "zori", "inventory", "daysToPending", "marketHeatIndex"]
}
```

#### Example: browse the catalog

```json
{
  "mode": "catalog",
  "category": "Market heat index"
}
```

### Use cases

- **Housing analysts** — track ZHVI, ZORI and inventory trends for metros, counties or ZIP codes.
- **Investors** — compare typical home values and rents, including gross rental yield, across markets.
- **PropTech and data teams** — load tidy region/date/value rows into a warehouse for dashboards and models.
- **Market researchers** — monitor market heat, days to pending, price cuts and sale-to-list ratios.
- **Economic and policy teams** — pull affordability, new-construction and forecast series for reports.
- **Data journalists** — export a single ZIP or metro's full history for a story.

### FAQ

**Is this affiliated with Zillow?**
No. This actor reads Zillow Research's public data files. Zillow is not affiliated with and does not endorse this actor. Attribution to Zillow Research is required when you publish the data.

**Do I need a Zillow account, API key or proxy?**
No. The research CSV files are public. The actor needs no login, API key, cookie or proxy configuration.

**What is the difference between ZHVI and ZORI?**
ZHVI is Zillow's typical home value index. ZORI is its observed rent index. The dataset picker includes all-homes, single-family, condo, bedroom-count and price-tier cuts where Zillow publishes them.

**Why does rent data cover fewer metros than home values?**
Zillow publishes ZORI for fewer regions than ZHVI. The actor returns only regions present in the chosen file; it does not fill missing regions with estimates.

**Why do some months have no value for my region?**
Zillow starts some series later or stops publishing a cut. Empty cells are skipped, so a record appears only when Zillow published a value for that region and month.

**Why does history data sometimes change between runs?**
Zillow restates its back-series when methodology or source data change. Each run reads the current published file, so a later download can differ from an earlier one. `scrapedAt` records when the file was read.

**How do I get a full ZIP or neighborhood history?**
Those files are large and the actor caps output at 100,000 records per run. Use `latest` for a current snapshot, or split the request by state, region or date range.

**Are market heat and forecast values percentages?**
Market heat is an index value; higher means a hotter seller's market. ZHVF and ZORF forecast values are percentages. The `unit` field on every row tells you which applies.

**Can I use a dataset that is not in the picker?**
Yes. Paste its Zillow Research CSV URL into `customDatasetUrl`. Only `files.zillowstatic.com/research/...csv` URLs are accepted.

**How current is the data?**
Zillow updates monthly datasets around the middle of the following month and weekly files on a monthly cadence. The `latestDate` field shows the newest observation in the file you selected.

# Actor input Schema

## `mode` (type: `string`):

What to return: latest values, full history, a multi-metric region snapshot, or the dataset catalog. The legacy options keep old saved tasks working with the previous wide output.

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

Zillow Research file to read. Covers home values, rents, inventory, days on market, price cuts, sales, market heat, forecasts, new construction and affordability at the geography levels Zillow publishes.

## `customDatasetUrl` (type: `string`):

Optional Zillow Research CSV URL (https://files.zillowstatic.com/research/...csv) for a dataset newer than this actor's catalog. Overrides Dataset.

## `regions` (type: `array`):

Optional region names or substrings: 'Austin, TX', 'Texas', 'TX', '90210', 'Harris County'. Matches region, state, city, county and metro names. Leave empty for all regions.

## `regionIds` (type: `array`):

Optional exact Zillow RegionIDs (for example 102001 for the United States). If both Regions and Region IDs are set, a row must match both.

## `startDate` (type: `string`):

Optional inclusive start date in YYYY-MM-DD format. Omit for the earliest published date.

## `endDate` (type: `string`):

Optional inclusive end date in YYYY-MM-DD format. Omit for the latest published date.

## `includeChanges` (type: `boolean`):

Add 1-month, 3-month and 1-year percentage changes to latest and snapshot records when prior values exist.

## `snapshotMetrics` (type: `array`):

Metrics to include in snapshot mode. Allowed values: zhvi, zori, inventory, newListings, medianListPrice, medianSalePrice, salesCount, daysToPending, priceCutShare, saleToListRatio, marketHeatIndex, newConstructionSales. Leave empty for all 12.

## `category` (type: `string`):

Filter the dataset catalog in catalog mode. Ignored in other modes.

## `maxItems` (type: `integer`):

Maximum number of records to return. Large ZIP or neighborhood histories need a date range, region filter, or a higher cap.

## Actor input object example

```json
{
  "mode": "latest",
  "dataset": "market_temp_index_metro_uc_sfrcondo_month",
  "includeChanges": true,
  "category": "all",
  "maxItems": 3
}
```

# Actor output Schema

## `observations` (type: `string`):

Dataset containing tidy observation rows, metric snapshots, or dataset catalog records, depending on the selected mode.

# 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 = {
    "mode": "latest",
    "dataset": "market_temp_index_metro_uc_sfrcondo_month",
    "includeChanges": false,
    "category": "all",
    "maxItems": 3
};

// Run the Actor and wait for it to finish
const run = await client.actor("dataspryva/zillow-research-home-value-and-market-heat-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 = {
    "mode": "latest",
    "dataset": "market_temp_index_metro_uc_sfrcondo_month",
    "includeChanges": False,
    "category": "all",
    "maxItems": 3,
}

# Run the Actor and wait for it to finish
run = client.actor("dataspryva/zillow-research-home-value-and-market-heat-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 '{
  "mode": "latest",
  "dataset": "market_temp_index_metro_uc_sfrcondo_month",
  "includeChanges": false,
  "category": "all",
  "maxItems": 3
}' |
apify call dataspryva/zillow-research-home-value-and-market-heat-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,dataspryva/zillow-research-home-value-and-market-heat-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/mhbqXuxSnwXKuO0uP/builds/LmI1eGACKbWePrgNH/openapi.json