# Zillow Search

## Overview

| Property | Value |
|----------|-------|
| **Status** | active |
| **Method** | `GET` |
| **Endpoint** | `/v2/zillow/search` |
| **Base URL** | `https://api.piloterr.com` |
| **Credit Cost** | 3 credits per call |
| **Documentation** | https://www.piloterr.com/library/zillow-search |

## Description

Search Zillow listings from a search or map URL and retrieve prices, beds, baths, coordinates, and listing status.

## Authentication

- **Key Name:** `x-api-key`
- **Location:** HTTP Header
- **Get an API key:** https://app.piloterr.com/register

## Example Request

```bash
curl --location --request GET 'https://api.piloterr.com/v2/zillow/search' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Search homes in Staten Island, NY

```json
{
  "results": [
    {
      "id": "32361983",
      "area": 2500,
      "beds": 4,
      "list": true,
      "zpid": "32361983",
      "baths": 3,
      "pgapt": "ForSale",
      "price": "$699,000",
      "sgapt": "For Sale (Broker)",
      "address": "20 Kyle Ct, Staten Island, NY 10312",
      "img_src": "https://photos.zillowstatic.com/fp/b57fe9b7438cd7ee0a05df7753c78812-p_e.jpg",
      "pals_id": "479004_501695",
      "lat_long": {
        "latitude": 40.557384,
        "longitude": -74.19698
      },
      "has_image": true,
      "zestimate": 695900,
      "detail_url": "https://www.zillow.com/homedetails/20-Kyle-Ct-Staten-Island-NY-10312/32361983_zpid/",
      "broker_name": "Listing by: Real Broker NY LLC",
      "status_text": "House for sale",
      "status_type": "FOR_SALE",
      "address_city": "Staten Island",
      "has3_d_model": true,
      "address_state": "NY",
      "address_street": "20 Kyle Ct",
      "address_zipcode": "10312",
      "country_currency": "$",
      "unformatted_price": 699000,
      "raw_home_status_cd": "ForSale",
      "is_showcase_listing": true,
      "marketing_status_simplified_cd": "For Sale by Agent"
    },
    {
      "id": "32325469",
      "area": 1104,
      "beds": 3,
      "list": true,
      "zpid": "32325469",
      "baths": 2,
      "pgapt": "ForSale",
      "price": "$849,900",
      "sgapt": "For Sale (Broker)",
      "address": "43 Hickory Ave, Staten Island, NY 10305",
      "img_src": "https://photos.zillowstatic.com/fp/3a517276d08c426dce24e27c116cac1a-p_e.jpg",
      "pals_id": "820001_2602944",
      "lat_long": {
        "latitude": 40.59659,
        "longitude": -74.073944
      },
      "has_image": true,
      "zestimate": 836200,
      "detail_url": "https://www.zillow.com/homedetails/43-Hickory-Ave-Staten-Island-NY-10305/32325469_zpid/",
      "broker_name": "Listing by: Homes R Us Realty of NY, Inc.",
      "status_text": "House for sale",
      "status_type": "FOR_SALE",
      "address_city": "Staten Island",
      "has3_d_model": true,
      "address_state": "NY",
      "address_street": "43 Hickory Ave",
      "address_zipcode": "10305",
      "country_currency": "$",
      "unformatted_price": 849900,
      "raw_home_status_cd": "ForSale",
      "is_showcase_listing": true,
      "marketing_status_simplified_cd": "For Sale by Agent"
    }
  ]
}
```

## Documentation

## Overview
Extract property listings from any Zillow search or map results page. Returns a structured list of homes with prices, beds/baths, coordinates, listing status, broker info, and direct links to each property page.

## Quickstart
```
GET https://api.piloterr.com/v2/zillow/search?query=https://www.zillow.com/staten-island-ny/
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Full Zillow search or map results URL |

## Response fields
| Field | Type | Description |
|---|---|---|
| `results` | array | List of property listings |
| `results[].zpid` | string | Zillow property ID |
| `results[].id` | string | Listing ID (same as zpid in most cases) |
| `results[].address` | string | Full formatted address |
| `results[].address_street` | string | Street address |
| `results[].address_city` | string | City |
| `results[].address_state` | string | State code |
| `results[].address_zipcode` | string | ZIP code |
| `results[].price` | string | Formatted price (e.g. $699,000) |
| `results[].unformatted_price` | integer | Numeric price |
| `results[].beds` | integer | Number of bedrooms |
| `results[].baths` | number | Number of bathrooms |
| `results[].area` | integer | Living area in sqft |
| `results[].status_text` | string | Human-readable status |
| `results[].status_type` | string | Status code (e.g. FOR_SALE) |
| `results[].detail_url` | string | Zillow property page URL |
| `results[].img_src` | string | Main listing photo URL |
| `results[].broker_name` | string | Listing broker label |
| `results[].lat_long.latitude` | number | Latitude |
| `results[].lat_long.longitude` | number | Longitude |
| `results[].zestimate` | integer | Zestimate value (when available) |
| `results[].is_showcase_listing` | boolean | Showcase listing flag |
| `results[].pgapt` | string | Property group type |
| `results[].sgapt` | string | Listing subtype label |

## Notes
- Response is returned under `results`.
- Pass each result's `detail_url` to the Zillow Property endpoint for full listing details.
- Some listings include extra nested objects such as `hdp_data` and `carousel_photos_composable`.

## Main use cases
- Monitor for-sale inventory in a target city or ZIP code
- Build lead lists with price, beds, baths, and broker data
- Feed property discovery pipelines for real estate analytics
- Compare listing prices against Zestimate values at scale