# Zillow Property Search

<p>Search real estate listings across the United States. Query a bounding box, a centre point with a radius, a list of region ids, or a custom polygon, then narrow the results with price, bedroom, size and listing-status filters.</p><p>The response carries each listing in full, including its list price, value and rent estimates, address, property facts, media links and listing status.</p><h2>Choosing an area</h2><p>Use <a href="/docs/zillow-api/zillow_autocomplete">Zillow Autocomplete</a> first to resolve a place into a region id or a bounding box. A centre point with <code>radius_mi</code> is converted into a bounding box for you.</p><h2>Paging</h2><p>Requests are capped so that <code>page * page_size</code> never exceeds 1000. Ask for up to 100 rows per page, or 1000 rows in a single call with <code>page=1&amp;page_size=1000</code>.</p>

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

## 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 |
| --- | --- | --- | --- |
| `latitude` | number | No | Centre latitude of the search area. |
| `longitude` | number | No | Centre longitude of the search area. |
| `radius_mi` | number | No | Search radius around the centre point, up to 100 miles. Required with a latitude and longitude centre point unless a complete bounding box is given instead. |
| `north_latitude` | number | No | Northern bound of an explicit bounding box. |
| `south_latitude` | number | No | Southern bound of an explicit bounding box. |
| `east_longitude` | number | No | Eastern bound of an explicit bounding box. |
| `west_longitude` | number | No | Western bound of an explicit bounding box. |
| `region_ids[]` | array | No | Region ids from the autocomplete endpoint, up to 20. |
| `polygon` | string | No | Custom search boundary as lat,lon\|lat,lon\|:lat,lon\|lat,lon: points separated by \|, polygons separated by \|:. |
| `region_id_type` | integer | No | How the region ids are interpreted: 0 state, 1 county, 2 city, 3 ZIP code, 5 neighborhood. The autocomplete endpoint returns the matching value as region_id_type. |
| `sort_ascending` | boolean | No | Sort lowest first instead of highest first. |
| `lot_size_min` | integer | No | Smallest lot size in square feet. |
| `include_off_market` | boolean | No | Supplement the results with off-market listings. The totals reported then cover a larger population. |
| `listing_category` | string | No | category1 for sale (default), category2 for rent, or all. |
| `sort_order` | string | No | One of relevance, price, beds, baths, yearBuilt, daysOn, featured, livingArea, lotArea, nearby, recentlyChanged, rentalDays, rentalPriorityScore. |
| `min_price` | integer | No | Lowest list price to include. |
| `max_price` | integer | No | Highest list price to include. |
| `min_beds` | integer | No | Fewest bedrooms to include. |
| `max_beds` | integer | No | Most bedrooms to include. |
| `min_baths` | integer | No | Fewest bathrooms to include. |
| `max_baths` | integer | No | Most bathrooms to include. |
| `living_area_min` | integer | No | Smallest living area in square feet. |
| `year_built_min` | integer | No | Earliest construction year. |
| `home_statuses[]` | array | No | Statuses from one listing type only: for-sale statuses (fsba, fsbo, newConstruction, comingSoon, auction, foreclosure, foreclosed, preforeclosure), forRent, or recentlySold. Defaults to every for-sale status, or forRent when listing_category is category2. |
| `keywords` | string | No | Free-text filter applied to listings. |
| `zoom_level` | integer | No | Map zoom level, 6 to 25. |
| `page` | integer | No | Page number, 1-based. |
| `page_size` | integer | No | Rows per page. page * page_size must not exceed 1000. |
| `allow_empty` | boolean | No | Return an empty result set for an area with no matches instead of raising. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/zillow/search?latitude=47.6062&longitude=-122.3321&radius_mi=5&listing_category=category1&page_size=20"
```

## Example response

```json
{
    "data": {
        "listings": [],
        "count": 0,
        "total_matching_count": 0,
        "freshness": []
    }
}
```

## 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)