# Zillow Market Data

<p>Get monthly market time series for a geography: home value and rent indices, sale prices, transaction volume, days to close, sale-to-list ratios and inventory. Each series covers every place of the requested geography type, so a single request covers the whole country.</p><h2>Geography is a filter, not a filename</h2><p>Each file holds every place of one geography type. Set <code>region_name</code>, <code>state</code>, <code>metro</code> or <code>county</code> to narrow the rows to the places you want.</p><h2>Comparables are scoped, not listed</h2><p>Comparable properties come from running a listing search over the same area with the <a href="/docs/zillow-api/zillow_search">search endpoint</a>. There is no separate comparable-sales array on this endpoint.</p>

- **Documentation:** [https://scrappa.co/docs/zillow-api/zillow_market_data](https://scrappa.co/docs/zillow-api/zillow_market_data)
- **API group:** Zillow API
- **Endpoint:** `GET https://scrappa.co/api/zillow/market-data`

## Authentication

Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `family` | string | Yes | Dataset family, for example zhvi, zori or invt_fs. |
| `geography` | string | Yes | City, County, Metro, National, Neighborhood, State or Zip. |
| `region_name` | string | No | Filter rows to one place by name. |
| `state` | string | No | Filter rows to one state. |
| `metro` | string | No | Filter rows to one metropolitan area. |
| `county` | string | No | Filter rows to one county. |
| `segment` | string | No | Property-type segment for families other than the home value and rent indices. |
| `stat` | string | No | Statistic suffix such as sm (smoothed mean) or sa (seasonal average). |
| `variant` | string | No | Metric variant such as bdrmcnt_4 or tier_0.33_0.67. Required when a family and geography match more than one dataset. |
| `limit` | integer | No | Maximum places to return, up to 500 per page. |
| `offset` | integer | No | Matching places to skip before the page starts. Use it to reach places past the first 500. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/zillow/market-data?family=zhvi&geography=Zip&variant=bdrmcnt_4&region_name=98052"
```

## Example response

```json
{
    "data": {
        "places": [],
        "places_available": 0,
        "total_rows_matched": 0
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 400 | The request validation failed | A query parameter is missing, malformed, or outside its documented range. This is the only Zillow response that carries no error code: the body has a message and a field list and nothing else, so match it on the 400 status. |
| 422 | No research dataset matches that family and geography | The requested research file does not exist for the combination given. |
| 422 | More than one research dataset matches | The family, geography and variant given do not identify a single research file. |
| 422 | No accuracy figures are published for that region | The named state or metropolitan area publishes no estimate-accuracy data. |
| 422 | The upstream rejected the request | Zillow answered with a deterministic 4xx. |
| 422 | The building returned does not match the requested address | The decoded building token resolved to a building at a different address than the slug names. |
| 503 | The listing source answered with a block or rate-limit page | The request reached the source, but what came back was a challenge or rate-limit page rather than the data. |
| 503 | The listing source returned a server error | The request was served and answered with a 5xx. |
| 503 | The listing source did not answer in time | The request was sent and no answer came back before the deadline. |
| 503 | The request could not be sent | No approved exit could be reached, so the request never reached the listing source. |
| 503 | No approved exit is available | There was no usable approved exit to send the request through. |
| 503 | The upstream returned a document this integration cannot read | The publisher changed the shape of a response or served a document that is not the expected file. |

## More Scrappa resources

- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)