### Start Project with Docker

Source: https://github.com/pseudo-r/public-zillow-api/blob/main/CONTRIBUTING.md

Use this command to clone the repository and start the full service stack including PostgreSQL, Redis, and Django.

```bash
git clone https://github.com/pseudo-r/Public-Zillow-API.git
cd Public-Zillow-API

# Copy env file
cp .env.example zillow_service/.env

# Start PostgreSQL, Redis, Django + Celery
docker compose up
```

--------------------------------

### Deploy and Query Django REST API

Source: https://context7.com/pseudo-r/public-zillow-api/llms.txt

Commands to start the Django service via Docker and examples of querying the REST API endpoints.

```bash
# Start the service with Docker
cd zillow_service
docker compose up --build
# API: http://localhost:8001
# Swagger docs: http://localhost:8001/api/docs/

# Search for properties
curl -X POST http://localhost:8001/api/v1/search/ \
  -H "Content-Type: application/json" \
  -d '{"query": "Seattle, WA", "type": "sale", "price_min": 400000, "price_max": 900000, "beds_min": 2}'

# Search rentals
curl -X POST http://localhost:8001/api/v1/search/ \
  -H "Content-Type: application/json" \
  -d '{"query": "Austin, TX", "type": "rent", "rent_max": 2500}'

# Get property detail
curl http://localhost:8001/api/v1/properties/2077091803/

# Get Zestimate and history
curl http://localhost:8001/api/v1/properties/2077091803/zestimate/

# Get Walk/Transit/Bike scores
curl http://localhost:8001/api/v1/properties/2077091803/scores/

# Get climate risk
curl http://localhost:8001/api/v1/properties/2077091803/climate/

# Autocomplete
curl "http://localhost:8001/api/v1/autocomplete/?q=Seattle"
```

--------------------------------

### Property Photo URL Example

Source: https://github.com/pseudo-r/public-zillow-api/blob/main/README.md

A concrete example of a formatted photo URL.

```text
https://photos.zillowstatic.com/fp/abc123def456-uncropped_scaled_within_1536_1152.webp
```

--------------------------------

### ZestimateDeepDiveQuery Response Example

Source: https://github.com/pseudo-r/public-zillow-api/blob/main/README.md

A trimmed example response for the ZestimateDeepDiveQuery, showing property details like Zestimate, valuation range, and price history.

```json
{
  "data": {
    "property": {
      "zpid": "2077091803",
      "zestimate": 845000,
      "zestimateMinus": 760500,
      "zestimatePlus": 929500,
      "valuationRange": {"low": 760500, "high": 929500},
      "priceHistory": [
        {
          "date": "2024-03-15",
          "price": 850000,
          "priceChangeRate": 0.0,
          "event": "Listed for sale",
          "source": "MLS #12345",
          "pricePerSquareFoot": 459
        },
        {
          "date": "2021-08-10",
          "price": 720000,
          "priceChangeRate": null,
          "event": "Sold",
          "source": "MLS"
        }
      ]
    }
  }
}
```

--------------------------------

### Start Zillow Service with Docker

Source: https://github.com/pseudo-r/public-zillow-api/blob/main/README.md

Use these commands to initialize the service environment and launch the API container.

```bash
cd zillow_service
docker compose up --build

# API: http://localhost:8001
# Docs: http://localhost:8001/api/docs/
```

--------------------------------

### Zestimate Deep Dive Query Example

Source: https://github.com/pseudo-r/public-zillow-api/blob/main/docs/endpoints/graphql.md

Example of how to use the `ZestimateDeepDiveQuery` operation to retrieve Zestimate, valuation range, and price history for a property.

```APIDOC
## POST /graphql/

### Description
Retrieves detailed Zestimate information, including valuation range and price history, for a specific property.

### Method
POST

### Endpoint
`https://www.zillow.com/graphql/`

### Parameters

#### Request Body

- **operationName** (string) - Required - The name of the GraphQL operation to execute (`ZestimateDeepDiveQuery`).
- **variables** (object) - Required - Variables for the query.
  - **zpid** (ID!) - Required - The Zillow Property ID.
- **query** (string) - Required - The GraphQL query string.

### Request Example

```bash
curl -X POST "https://www.zillow.com/graphql/" \
  -H "Content-Type: application/json" \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36" \
  -H "client-id: hdp-react-web-client" \
  -d '{ \
    "operationName": "ZestimateDeepDiveQuery", \
    "variables": {"zpid": 2077091803}, \
    "query": "query ZestimateDeepDiveQuery($zpid: ID!) { property(zpid: $zpid) { zpid zestimate zestimateMinus zestimatePlus valuationRange { low high } priceHistory { date price priceChangeRate event source pricePerSquareFoot } } }" \
  }'
```

### Response

#### Success Response (200)

- **data** (object)
  - **property** (object)
    - **zpid** (ID) - The Zillow Property ID.
    - **zestimate** (float) - The current Zestimate value.
    - **zestimateMinus** (float) - Lower bound of the Zestimate range.
    - **zestimatePlus** (float) - Upper bound of the Zestimate range.
    - **valuationRange** (object)
      - **low** (float) - The lower bound of the valuation range.
      - **high** (float) - The upper bound of the valuation range.
    - **priceHistory** (array of objects)
      - **date** (string) - The date of the price change.
      - **price** (float) - The price at that date.
      - **priceChangeRate** (float) - The rate of price change.
      - **event** (string) - The type of event (e.g., 'Sale', 'Price Change').
      - **source** (string) - The source of the data.
      - **pricePerSquareFoot** (float) - Price per square foot at that date.

#### Response Example

```json
{
  "data": {
    "property": {
      "zpid": "2077091803",
      "zestimate": 750000.00,
      "zestimateMinus": 720000.00,
      "zestimatePlus": 780000.00,
      "valuationRange": {
        "low": 720000.00,
        "high": 780000.00
      },
      "priceHistory": [
        {
          "date": "2023-01-01",
          "price": 740000.00,
          "priceChangeRate": 0.02,
          "event": "Price Change",
          "source": "MLS",
          "pricePerSquareFoot": 300.00
        }
      ]
    }
  }
}
```
```

--------------------------------

### Start Zillow Service with Docker

Source: https://github.com/pseudo-r/public-zillow-api/blob/main/zillow_service/README.md

Use Docker Compose to build and run the service locally.

```bash
# Docker (recommended)
docker compose up --build

# API: http://localhost:8001
# Docs: http://localhost:8001/api/docs/
```

--------------------------------

### Example Zillow API Response (Home Search)

Source: https://github.com/pseudo-r/public-zillow-api/blob/main/README.md

A trimmed example of the response from the Zillow home search API, showing listing details and total counts.

```json
{
  "cat1": {
    "searchResults": {
      "listResults": [
        {
          "zpid": "2077091803",
          "id": "2077091803",
          "detailUrl": "/homedetails/123-Main-St-Seattle-WA-98101/2077091803_zpid/",
          "statusType": "FOR_SALE",
          "statusText": "House for sale",
          "price": "$850,000",
          "unformattedPrice": 850000,
          "address": "123 Main St, Seattle, WA 98101",
          "beds": 3,
          "baths": 2,
          "area": 1850,
          "latLong": {"latitude": 47.6062, "longitude": -122.3321},
          "imgSrc": "https://photos.zillowstatic.com/fp/abc123-uncropped_scaled_within_1536_1152.webp",
          "hasVideo": false,
          "isFeatured": false,
          "shouldShowZestimate": true,
          "zestimate": 845000,
          "hdpData": {
            "homeInfo": {
              "zpid": 2077091803,
              "zipcode": "98101",
              "city": "Seattle",
              "state": "WA",
              "latitude": 47.6062,
              "longitude": -122.3321,
              "price": 850000,
              "dateSold": null,
              "homeType": "SINGLE_FAMILY",
              "homeStatus": "FOR_SALE",
              "livingArea": 1850,
              "bedrooms": 3,
              "bathrooms": 2,
              "taxAssessedValue": 620000,
              "zestimate": 845000,
              "rentZestimate": 3200
            }
          }
        }
      ],
      "mapResults": [...] 
    },
    "searchList": {
      "totalPages": 12,
      "totalResultCount": 489
    }
  },
  "cat2": {
    "total": {"totalResultCount": 489}
  }
}
```

--------------------------------

### Home Value Chart Data Query Example

Source: https://github.com/pseudo-r/public-zillow-api/blob/main/docs/endpoints/graphql.md

Example of how to use the `HomeValueChartDataQuery` operation to retrieve historical home value data for charting purposes.

```APIDOC
## POST /graphql/

### Description
Retrieves historical home value data, suitable for charting, for a specific property.

### Method
POST

### Endpoint
`https://www.zillow.com/graphql/`

### Parameters

#### Request Body

- **operationName** (string) - Required - The name of the GraphQL operation to execute (`HomeValueChartDataQuery`).
- **variables** (object) - Required - Variables for the query.
  - **zpid** (ID!) - Required - The Zillow Property ID.
  - **useHVChartDataSource** (Boolean) - Optional - Whether to use the historical value chart data source.
- **query** (string) - Required - The GraphQL query string.

### Request Example

```bash
curl -X POST "https://www.zillow.com/graphql/" \
  -H "Content-Type: application/json" \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36" \
  -H "client-id: hdp-react-web-client" \
  -d '{ \
    "operationName": "HomeValueChartDataQuery", \
    "variables": {"zpid": 2077091803, "useHVChartDataSource": true}, \
    "query": "query HomeValueChartDataQuery($zpid: ID!, $useHVChartDataSource: Boolean) { property(zpid: $zpid) { zpid zestimateHistory(useHVChartDataSource: $useHVChartDataSource) { t v } } }" \
  }'
```

### Response

#### Success Response (200)

- **data** (object)
  - **property** (object)
    - **zpid** (ID) - The Zillow Property ID.
    - **zestimateHistory** (array of objects)
      - **t** (string) - Timestamp of the historical value.
      - **v** (float) - The estimated value at that timestamp.

#### Response Example

```json
{
  "data": {
    "property": {
      "zpid": "2077091803",
      "zestimateHistory": [
        {
          "t": "2022-01-01T00:00:00.000Z",
          "v": 700000.00
        },
        {
          "t": "2023-01-01T00:00:00.000Z",
          "v": 750000.00
        }
      ]
    }
  }
}
```
```

--------------------------------

### Initialize Local Development Environment

Source: https://github.com/pseudo-r/public-zillow-api/blob/main/zillow_service/README.md

Commands to set up a virtual environment, install dependencies, and run the Django development server.

```bash
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -e ".[dev]"
cp .env.example .env
python manage.py migrate
python manage.py runserver 8001
```

--------------------------------

### Execute Persisted Query via GET

Source: https://github.com/pseudo-r/public-zillow-api/blob/main/docs/endpoints/graphql.md

Example of using Automatic Persisted Queries (APQ). Note that the sha256Hash is deployment-specific.

```http
GET https://www.zillow.com/graphql/?operationName=ZestimateDeepDiveQuery&variables={"zpid":2077091803}&extensions={"persistedQuery":{"version":1,"sha256Hash":"<hash>"}}
```

--------------------------------

### Setup Local Development Environment

Source: https://github.com/pseudo-r/public-zillow-api/blob/main/CONTRIBUTING.md

Follow these steps to set up the project locally without Docker, requiring Python 3.12+, PostgreSQL 14+, and Redis 6+.

```bash
cd zillow_service
python -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -e ".[dev]"

# Copy and edit env
cp ../.env.example .env
# Set DATABASE_URL and CELERY_BROKER_URL to your local values

python manage.py migrate
python manage.py runserver
```

--------------------------------

### GET /api/v1/autocomplete/

Source: https://github.com/pseudo-r/public-zillow-api/blob/main/zillow_service/README.md

Get location suggestions based on a query string.

```APIDOC
## GET /api/v1/autocomplete/

### Description
Retrieve location suggestions for search queries.

### Method
GET

### Endpoint
/api/v1/autocomplete/

### Parameters
#### Query Parameters
- **q** (string) - Required - The search query string
```

--------------------------------

### Interact with Zillow API via cURL

Source: https://github.com/pseudo-r/public-zillow-api/blob/main/zillow_service/README.md

Examples for searching properties, retrieving details, and ingesting data using the API endpoints.

```bash
# Search for-sale homes in Seattle
curl -X POST http://localhost:8001/api/v1/search/ \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Seattle, WA",
    "type": "sale",
    "price_min": 400000,
    "price_max": 900000,
    "beds_min": 2
  }'

# Rental search in Austin
curl -X POST http://localhost:8001/api/v1/search/ \
  -H "Content-Type: application/json" \
  -d '{"query": "Austin, TX", "type": "rent", "rent_max": 2500}'

# Property detail
curl http://localhost:8001/api/v1/properties/2077091803/

# Zestimate + history
curl http://localhost:8001/api/v1/properties/2077091803/zestimate/

# Autocomplete
curl "http://localhost:8001/api/v1/autocomplete/?q=Seattle"

# Ingest a property
curl -X POST http://localhost:8001/api/v1/ingest/property/ \
  -H "Content-Type: application/json" \
  -d '{"zpid": 2077091803}'
```

--------------------------------

### Example Mortgage Rates Response (JSON)

Source: https://github.com/pseudo-r/public-zillow-api/blob/main/docs/endpoints/market_valuation.md

This is a sample JSON response structure for current mortgage rates, showing lender details, rates, APR, and payment information.

```json
{
  "rates": [
    {
      "lenderName": "Rocket Mortgage",
      "rate": 6.875,
      "apr": 7.103,
      "monthlyPayment": 2303,
      "fees": 1200,
      "points": 0.0,
      "program": "Fixed30Year",
      "nmlsId": "3030"
    },
    {
      "lenderName": "Better Mortgage",
      "rate": 6.750,
      "apr": 6.921,
      "monthlyPayment": 2271,
      "fees": 0,
      "points": 0.5,
      "program": "Fixed30Year"
    }
  ],
  "nationalAverage": {
    "rate": 6.92,
    "apr": 7.04
  }
}
```

--------------------------------

### Retrieve Comparable Sales

Source: https://github.com/pseudo-r/public-zillow-api/blob/main/docs/endpoints/market_valuation.md

Get a list of similar property sales using the SimilarSalesQuery operation.

```bash
curl -X POST "https://www.zillow.com/graphql/" \
  -H "Content-Type: application/json" \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36" \
  -H "client-id: hdp-react-web-client" \
  -d '{
    "operationName": "SimilarSalesQuery",
    "variables": {"zpid": 2077091803},
    "query": "query SimilarSalesQuery($zpid: ID!) { property(zpid: $zpid) { zpid comparables { zpid address price dateSold livingArea bedrooms bathrooms } } }"
  }'
```

--------------------------------

### Get Comparable Sales Data

Source: https://context7.com/pseudo-r/public-zillow-api/llms.txt

Fetch data for recently sold comparable homes near a specific property. This is useful for valuation analysis and includes details like address, price, and size.

```bash
curl -X POST "https://www.zillow.com/graphql/" \
  -H "Content-Type: application/json" \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36" \
  -H "client-id: hdp-react-web-client" \
  -d '{ \
    "operationName": "SimilarSalesQuery", \
    "variables": {"zpid": 2077091803}, \
    "query": "query SimilarSalesQuery($zpid: ID!) { property(zpid: $zpid) { zpid comparables { zpid address price dateSold livingArea bedrooms bathrooms } } }" \
  }'
```

--------------------------------

### GET /api/v1/properties/{zpid}/

Source: https://github.com/pseudo-r/public-zillow-api/blob/main/zillow_service/README.md

Retrieve detailed information for a specific property using its ZPID.

```APIDOC
## GET /api/v1/properties/{zpid}/

### Description
Fetch detailed property information by Zillow Property ID (ZPID).

### Method
GET

### Endpoint
/api/v1/properties/{zpid}/

### Parameters
#### Path Parameters
- **zpid** (integer) - Required - The unique Zillow Property ID
```

--------------------------------

### Interact with ZillowClient in Python

Source: https://context7.com/pseudo-r/public-zillow-api/llms.txt

Demonstrates property search, Zestimate retrieval, and property analytics using the ZillowClient. The client supports automatic retries and rate limiting.

```python
from clients.zillow_client import ZillowClient

# Initialize client
client = ZillowClient(timeout=30.0, request_delay=1.5)

# Search for properties
results = client.search_for_sale(
    search_term="Seattle, WA",
    region_id=16163,
    price_min=400000,
    price_max=900000,
    beds_min=2,
    sort="days"  # globalrelevanceex, days, priceDesc, priceAsc, sqftDesc
)
listings = results.data["cat1"]["searchResults"]["listResults"]
for listing in listings[:5]:
    print(f"{listing['address']} - {listing['price']}")

# Search for rentals
rentals = client.search_for_rent(
    search_term="Austin, TX",
    rent_max=3000,
    beds_min=1
)

# Search recently sold
sold = client.search_recently_sold(
    search_term="Denver, CO",
    days_max=90
)

# Get autocomplete suggestions
suggestions = client.autocomplete("Miami, FL")
for result in suggestions.data["data"]["zgsAutoComplete"]["results"]:
    print(f"{result['display']} - regionId: {result['metaData']['regionId']}")

# Get property detail from page
property_data = client.get_property_from_page(zpid=2077091803)
print(f"Price: ${property_data['price']:,}")
print(f"Zestimate: ${property_data['zestimate']:,}")

# Get Zestimate
zestimate = client.get_zestimate(zpid=2077091803)
prop = zestimate.data["data"]["property"]
print(f"Zestimate: ${prop['zestimate']:,} (range: ${prop['zestimateMinus']:,} - ${prop['zestimatePlus']:,})")

# Get Zestimate history
history = client.get_zestimate_history(zpid=2077091803)
for point in history.data["data"]["property"]["zestimateHistory"]:
    print(f"Date: {point['t']}, Value: ${point['v']:,}")

# Get scores
scores = client.get_walk_bike_transit_scores(zpid=2077091803)
score_data = scores.data["data"]["property"]
print(f"Walk Score: {score_data['walkScore']['walkscore']}")
print(f"Transit Score: {score_data['transitScore']['transit_score']}")
print(f"Bike Score: {score_data['bikeScore']['bikescore']}")

# Get climate risk
climate = client.get_climate_risk(zpid=2077091803)
risk = climate.data["data"]["property"]["climateRiskData"]
print(f"Flood: {risk['floodFactor']}, Fire: {risk['fireFactor']}, Heat: {risk['heatFactor']}")

# Get comparable sales
comps = client.get_comparable_sales(zpid=2077091803)
for comp in comps.data["data"]["property"]["comparables"]:
    print(f"{comp['address']} - ${comp['price']:,} ({comp['dateSold']})")

# Always close the client when done
client.close()

# Or use context manager
with ZillowClient() as client:
    results = client.search_for_sale("Portland, OR")
```

--------------------------------

### GET /getCurrentRates

Source: https://github.com/pseudo-r/public-zillow-api/blob/main/docs/endpoints/market_valuation.md

Fetches current mortgage rates based on specified loan parameters. No authentication is required.

```APIDOC
## GET /getCurrentRates

### Description
Returns current mortgage rates by loan program, loan amount, and credit score.

### Method
GET

### Endpoint
https://mortgageapi.zillow.com/getCurrentRates

### Query Parameters
- **partnerId** (string) - Required - Zillow partner ID. Example: `RD-ZZRCT81` (public default)
- **rateQuery.program** (string) - Required - Loan type / term. See values below.
- **rateQuery.loanAmountBucket** (string) - Required - Loan amount range. See values below.
- **rateQuery.creditScoreBucket** (string) - Required - Credit score range. See values below.
- **rateQuery.state** (string) - Optional - State code filter. Example: `WA`, `CA`, `TX`

### `rateQuery.program` Values
- `Fixed30Year` - 30-year fixed (most common)
- `Fixed20Year` - 20-year fixed
- `Fixed15Year` - 15-year fixed
- `Fixed10Year` - 10-year fixed
- `ARM5` - 5/1 adjustable rate
- `ARM7` - 7/1 adjustable rate
- `ARM10` - 10/1 adjustable rate

### `rateQuery.loanAmountBucket` Values
- `bucket0To100k` - $0–$100k
- `bucket100To200k` - $100k–$200k
- `bucket200To400k` - $200k–$400k
- `bucket400To500k` - $400k–$500k
- `bucket500kPlus` - $500k+

### `rateQuery.creditScoreBucket` Values
- `bucket620to639` - 620–639
- `bucket640to659` - 640–659
- `bucket660to679` - 660–679
- `bucket680to699` - 680–699
- `bucket700to719` - 700–719
- `bucket720to739` - 720–739
- `bucket740to759` - 740–759
- `bucket760Plus` - 760+

### Request Example
```bash
curl "https://mortgageapi.zillow.com/getCurrentRates?partnerId=RD-ZZRCT81&rateQuery.program=Fixed30Year&rateQuery.loanAmountBucket=bucket400To500k&rateQuery.creditScoreBucket=bucket740to759" \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36"
```

### Response
#### Success Response (200)
- **rates** (array) - An array of mortgage rate objects.
  - **lenderName** (string) - The name of the lender.
  - **rate** (number) - The interest rate.
  - **apr** (number) - The Annual Percentage Rate.
  - **monthlyPayment** (number) - The estimated monthly payment.
  - **fees** (number) - Associated fees.
  - **points** (number) - Discount points.
  - **program** (string) - The loan program.
  - **nmlsId** (string) - Optional: The NMLS ID of the lender.
- **nationalAverage** (object) - An object containing national average rate and APR.
  - **rate** (number) - The national average interest rate.
  - **apr** (number) - The national average APR.

#### Response Example
```json
{
  "rates": [
    {
      "lenderName": "Rocket Mortgage",
      "rate": 6.875,
      "apr": 7.103,
      "monthlyPayment": 2303,
      "fees": 1200,
      "points": 0.0,
      "program": "Fixed30Year",
      "nmlsId": "3030"
    },
    {
      "lenderName": "Better Mortgage",
      "rate": 6.750,
      "apr": 6.921,
      "monthlyPayment": 2271,
      "fees": 0,
      "points": 0.5,
      "program": "Fixed30Year"
    }
  ],
  "nationalAverage": {
    "rate": 6.92,
    "apr": 7.04
  }
}
```
```

--------------------------------

### BuildingPageOverviewQuery

Source: https://github.com/pseudo-r/public-zillow-api/blob/main/docs/endpoints/graphql.md

Retrieves an overview of a building, including unit counts, amenities, and available units.

```APIDOC
## POST /graphql/

### Description
Retrieves an overview of a building, including its name, unit count, available units with details, and amenities.

### Method
POST

### Endpoint
https://www.zillow.com/graphql/

### Parameters
#### Request Body
- **operationName** (string) - Required - The name of the GraphQL operation.
- **variables** (object) - Required - Variables for the query.
  - **zpid** (ID!) - Required - The Zillow Property ID.
- **query** (string) - Required - The GraphQL query string.

### Request Example
```json
{
  "operationName": "BuildingPageOverviewQuery",
  "variables": {"zpid": 2077091803},
  "query": "query BuildingPageOverviewQuery($zpid: ID!) { property(zpid: $zpid) { zpid buildingName unitCount availableUnits { zpid price bedrooms bathrooms livingArea availableFrom } amenities { category items } } }"
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains the query results.
  - **property** (object) - Property details.
    - **zpid** (ID) - The Zillow Property ID.
    - **buildingName** (string) - The name of the building.
    - **unitCount** (integer) - The total number of units in the building.
    - **availableUnits** (Array) - List of available units.
      - **zpid** (ID) - Zillow Property ID for the unit.
      - **price** (string) - The rental price.
      - **bedrooms** (integer) - Number of bedrooms.
      - **bathrooms** (float) - Number of bathrooms.
      - **livingArea** (float) - Living area in square feet.
      - **availableFrom** (string) - Date the unit is available from.
    - **amenities** (object) - Building amenities.
      - **category** (string) - The category of the amenity (e.g., "Parking", "Pet Policy").
      - **items** (Array<string>) - List of specific amenities within the category.

#### Response Example
```json
{
  "data": {
    "property": {
      "zpid": "2077091803",
      "buildingName": "The Grand Apartments",
      "unitCount": 150,
      "availableUnits": [
        {
          "zpid": "123456789",
          "price": "$2,500/mo",
          "bedrooms": 1,
          "bathrooms": 1.0,
          "livingArea": 750.0,
          "availableFrom": "2024-01-15"
        }
      ],
      "amenities": [
        {
          "category": "Parking",
          "items": ["Covered Garage", "Street Parking"]
        },
        {
          "category": "Pet Policy",
          "items": ["Cats Allowed", "Small Dogs Allowed"]
        }
      ]
    }
  }
}
```
```

--------------------------------

### Retrieve Walk, Transit, and Bike Scores

Source: https://github.com/pseudo-r/public-zillow-api/blob/main/docs/endpoints/market_valuation.md

Get location-based accessibility scores using the WalkTransitAndBikeScoreQuery operation.

```bash
curl -X POST "https://www.zillow.com/graphql/" \
  -H "Content-Type: application/json" \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36" \
  -H "client-id: hdp-react-web-client" \
  -d '{
    "operationName": "WalkTransitAndBikeScoreQuery",
    "variables": {"zpid": 2077091803},
    "query": "query WalkTransitAndBikeScoreQuery($zpid: ID!) { property(zpid: $zpid) { zpid walkScore { walkscore description ws_link } transitScore { transit_score description } bikeScore { bikescore description } } }"
  }'
```

--------------------------------

### Pagination Configuration

Source: https://github.com/pseudo-r/public-zillow-api/blob/main/docs/endpoints/search.md

Set the current page for search results.

```json
"pagination": {"currentPage": 2}
```

--------------------------------

### Retrieve Rental Costs and Fees (RCF) via API

Source: https://github.com/pseudo-r/public-zillow-api/blob/main/docs/endpoints/rentals.md

This POST request retrieves detailed monthly cost breakdowns, including rent, fees, and utilities, for a specific rental property using its ZPID. This powers the 'Total monthly cost' display.

```bash
curl -X POST "https://www.zillow.com/rentals/api/rcf/v1/rcf" \
  -H "Content-Type: application/json" \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36" \
  -d '{"zpid": 2077091803}'
```

--------------------------------

### Legacy Search API

Source: https://github.com/pseudo-r/public-zillow-api/blob/main/README.md

An older, but still partially active, search API. It can be accessed using GET or PUT methods.

```APIDOC
## GET/PUT www.zillow.com/search/GetSearchPageState.htm

### Description
This is an older, legacy search API that is still partially active. It can be used for search-related operations.

### Method
GET, PUT

### Endpoint
https://www.zillow.com/search/GetSearchPageState.htm

### Parameters
*Note: Specific parameters for this endpoint are not detailed in the provided text. Refer to Zillow's developer resources for a complete list.*

### Request Body
*Note: The structure of the request body is not detailed in the provided text. Refer to Zillow's developer resources for a complete list.*

### Response
*Note: Success and error response details are not provided in the source text.*
```

--------------------------------

### Walk, Transit, and Bike Score Response

Source: https://github.com/pseudo-r/public-zillow-api/blob/main/README.md

Example JSON response structure for property walkability, transit, and bike scores.

```json
{
  "data": {
    "property": {
      "zpid": "2077091803",
      "walkScore": {
        "walkscore": 92,
        "description": "Walker's Paradise",
        "logo_url": "https://cdn.walkscore.com/...",
        "ws_link": "https://www.walkscore.com/..."
      },
      "transitScore": {
        "transit_score": 75,
        "description": "Excellent Transit"
      },
      "bikeScore": {
        "bikescore": 68,
        "description": "Bikeable"
      }
    }
  }
}
```

--------------------------------

### Search for Rental Properties via cURL

Source: https://context7.com/pseudo-r/public-zillow-api/llms.txt

Queries rental listings by setting isForRent to true and using monthlyPayment for price range filtering.

```bash
curl -X PUT "https://www.zillow.com/async-create-search-page-state" \
  -H "Content-Type: application/json" \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36" \
  -d '{
    "searchQueryState": {
      "pagination": {},
      "usersSearchTerm": "Austin, TX",
      "mapBounds": {"west": -97.92, "east": -97.56, "south": 30.17, "north": 30.52},
      "regionSelection": [{"regionId": 28598, "regionType": 6}],
      "filterState": {
        "isForRent": {"value": true},
        "isForSaleByAgent": {"value": false},
        "isForSaleByOwner": {"value": false},
        "isNewConstruction": {"value": false},
        "isComingSoon": {"value": false},
        "isAuction": {"value": false},
        "isForSaleForeclosure": {"value": false},
        "beds": {"min": 1},
        "monthlyPayment": {"min": 1500, "max": 3000},
        "sortSelection": {"value": "days"}
      }
    },
    "wants": {"cat1": ["listResults", "mapResults"], "cat2": ["total"]},
    "requestId": 2
  }'
```

--------------------------------

### Get Autocomplete Location Suggestions

Source: https://context7.com/pseudo-r/public-zillow-api/llms.txt

Retrieves location suggestions and region IDs using a POST request to the Zillow GraphQL endpoint.

```bash
curl -X POST "https://www.zillow.com/zg-graph" \
  -H "Content-Type: application/json" \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36" \
  -H "client-id: search-sub-app-client" \
  -d '{
    "operationName": "GetAutocompleteResults",
    "variables": {
      "query": "Seattle, WA",
      "resultType": ["REGIONS", "FORSALE", "RENTALS", "SOLD"]
    },
    "query": "query GetAutocompleteResults($query: String!, $resultType: [AutocompleteResultType!]) { zgsAutoComplete(query: $query, resultType: $resultType) { results { display resultType metaData { regionId regionType city state lat lng } } } }"
  }'
```

--------------------------------

### Search for Properties for Sale via cURL

Source: https://context7.com/pseudo-r/public-zillow-api/llms.txt

Uses the async-create-search-page-state endpoint to query for sale listings with specific filters like price, bedrooms, and location.

```bash
curl -X PUT "https://www.zillow.com/async-create-search-page-state" \
  -H "Content-Type: application/json" \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36" \
  -H "Accept: */*" \
  -H "Accept-Language: en-US,en;q=0.9" \
  -d '{
    "searchQueryState": {
      "pagination": {},
      "usersSearchTerm": "Seattle, WA",
      "mapBounds": {"west": -122.5, "east": -122.2, "south": 47.5, "north": 47.7},
      "regionSelection": [{"regionId": 16163, "regionType": 6}],
      "filterState": {
        "price": {"min": 400000, "max": 900000},
        "beds": {"min": 2},
        "baths": {"min": 1},
        "sqft": {"min": 1000},
        "sortSelection": {"value": "globalrelevanceex"}
      },
      "isMapVisible": true,
      "isListVisible": true
    },
    "wants": {"cat1": ["listResults", "mapResults"], "cat2": ["total"]},
    "requestId": 2,
    "isDebugRequest": false
  }'
```

--------------------------------

### Rental Costs and Fees via GraphQL

Source: https://github.com/pseudo-r/public-zillow-api/blob/main/docs/endpoints/rentals.md

Fetches building-level rental cost and fee data using GraphQL. This is recommended for `_bld` pages, while the RCF API is for individual unit listings.

```APIDOC
## POST /graphql (RentalCostAndFeesBuildingQuery)

### Description
Retrieves building-level rental cost and fee data using a specific GraphQL operation.

### Method
POST

### Endpoint
https://www.zillow.com/graphql/

### Parameters
#### Request Body
- **operationName** (string) - Required - The name of the GraphQL operation, `RentalCostAndFeesBuildingQuery`.
- **variables** (object) - Required - Variables for the query.
  - **zpid** (ID!) - Required - The Zillow Property ID.
- **query** (string) - Required - The GraphQL query string.

### Request Example
```json
{
  "operationName": "RentalCostAndFeesBuildingQuery",
  "variables": {"zpid": 2077091803},
  "query": "query RentalCostAndFeesBuildingQuery($zpid: ID!) { property(zpid: $zpid) { zpid rentZestimate rentBreakdown { fees utilities includedUtilities } } }"
}
```

### Response
(Response structure depends on the GraphQL query. Typically includes `zpid`, `rentZestimate`, `rentBreakdown` with `fees`, `utilities`, and `includedUtilities`.)
```

--------------------------------

### GET /profile/{AgentName}

Source: https://github.com/pseudo-r/public-zillow-api/blob/main/docs/endpoints/property.md

Retrieves agent profile information from the Zillow profile page, including the encodedZuid required for further GraphQL queries.

```APIDOC
## GET /profile/{AgentName}

### Description
Fetches the agent profile page which contains embedded JSON data including the agent's unique identifier (encodedZuid).

### Method
GET

### Endpoint
https://www.zillow.com/profile/{AgentName}/

### Parameters
#### Path Parameters
- **AgentName** (string) - Required - The URL-friendly name of the agent.

### Response
#### Success Response (200)
- **encodedZuid** (string) - Unique agent ID used for GraphQL queries.
- **displayName** (string) - Agent full name.
- **profilePhotoSrc** (string) - URL of the profile photo.
- **businessName** (string) - Brokerage name.
- **phoneNumber** (string) - Contact phone number.
- **reviewsSummary.averageRating** (number) - Average star rating (0-5).
- **reviewsSummary.reviewCount** (number) - Total number of reviews.
- **profileStats.totalSales** (number) - Total sales count.
```

--------------------------------

### Execute Autocomplete via GraphQL

Source: https://github.com/pseudo-r/public-zillow-api/blob/main/README.md

Performs a POST request to the Zillow GraphQL endpoint to retrieve location-based autocomplete suggestions.

```bash
curl -X POST "https://www.zillow.com/zg-graph" \
  -H "Content-Type: application/json" \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36" \
  -d '{
    "operationName": "GetAutocompleteResults",
    "variables": {"query": "Seattle, WA", "resultType": ["REGIONS", "FORSALE", "RENTALS"]},
    "query": "query GetAutocompleteResults($query: String!, $resultType: [AutocompleteResultType!]) { zgsAutoComplete(query: $query, resultType: $resultType) { results { display metaData { regionId regionType } } } }"
  }'
```

--------------------------------

### Retrieve Local Legal Notices

Source: https://github.com/pseudo-r/public-zillow-api/blob/main/docs/endpoints/graphql.md

Fetches fair housing and local disclosure information for a specific property.

```bash
curl -X POST "https://www.zillow.com/graphql/" \
  -H "Content-Type: application/json" \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36" \
  -H "client-id: hdp-react-web-client" \
  -d '{
    "operationName": "LocalLegalProtectionQuery",
    "variables": {"zpid": 2077091803},
    "query": "query LocalLegalProtectionQuery($zpid: ID!) { property(zpid: $zpid) { zpid legalNotices { fairHousing { body url } localDisclosure } } }"
  }'
```

--------------------------------

### GET /homedetails (Property Detail Parsing)

Source: https://context7.com/pseudo-r/public-zillow-api/llms.txt

Extracts full property data from Zillow property pages by parsing embedded script tags.

```APIDOC
## GET /homedetails/{zpid}

### Description
Extract full property data from Zillow property pages. Data is embedded in __NEXT_DATA__ or hdpApolloPreloadedData script tags.

### Method
GET

### Endpoint
https://www.zillow.com/homedetails/{address}/{zpid}/

### Parameters
#### Path Parameters
- **zpid** (string) - Required - The Zillow Property ID

### Response
#### Success Response (200)
- **property** (object) - Contains fields like zpid, streetAddress, city, state, price, bedrooms, bathrooms, livingArea, zestimate, rentZestimate, yearBuilt, homeType, priceHistory, taxHistory, and schools.
```

--------------------------------

### Execute ZestimateDeepDiveQuery

Source: https://github.com/pseudo-r/public-zillow-api/blob/main/docs/endpoints/graphql.md

Retrieves detailed Zestimate information, valuation ranges, and price history for a specific property.

```bash
curl -X POST "https://www.zillow.com/graphql/" \
  -H "Content-Type: application/json" \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36" \
  -H "client-id: hdp-react-web-client" \
  -d '{
    "operationName": "ZestimateDeepDiveQuery",
    "variables": {"zpid": 2077091803},
    "query": "query ZestimateDeepDiveQuery($zpid: ID!) { property(zpid: $zpid) { zpid zestimate zestimateMinus zestimatePlus valuationRange { low high } priceHistory { date price priceChangeRate event source pricePerSquareFoot } } }"
  }'
```

--------------------------------

### Get Zillow Property Carousel Photos

Source: https://github.com/pseudo-r/public-zillow-api/blob/main/docs/endpoints/graphql.md

Retrieve carousel photos for a property, including their URLs and captions. Requires a valid property ZPID.

```bash
curl -X POST "https://www.zillow.com/zg-graph" \
  -H "Content-Type: application/json" \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36" \
  -H "client-id: search-sub-app-client" \
  -d '{ \
    "operationName": "GetCarouselPhotos", \
    "variables": {"zpid": 2077091803}, \
    "query": "query GetCarouselPhotos($zpid: ID!) { property(zpid: $zpid) { zpid photos { url caption } } }" \
  }'
```

--------------------------------

### GET /search/GetSearchPageState.htm

Source: https://github.com/pseudo-r/public-zillow-api/blob/main/docs/endpoints/search.md

Legacy endpoint for retrieving search page state. Note: This endpoint is partially active and may return 403 errors.

```APIDOC
## GET /search/GetSearchPageState.htm

### Description
Retrieves the search page state for a specific search term. It is recommended to use the 'async-create-search-page-state' endpoint instead.

### Method
GET

### Endpoint
https://www.zillow.com/search/GetSearchPageState.htm

### Query Parameters
- **searchQueryState** (string) - Required - URL-encoded JSON string containing pagination and search term details
- **wants** (string) - Required - URL-encoded JSON string specifying requested data categories
- **requestId** (string) - Optional - Identifier for the request

### Request Example
https://www.zillow.com/search/GetSearchPageState.htm?searchQueryState=%7B%22pagination%22%3A%7B%7D%2C%22usersSearchTerm%22%3A%22Austin%2C+TX%22%7D&wants=%7B%22cat1%22%3A%5B%22listResults%22%5D%7D&requestId=2
```

--------------------------------

### GraphQL (Primary Property Data)

Source: https://github.com/pseudo-r/public-zillow-api/blob/main/README.md

The primary endpoint for accessing property data using GraphQL. It supports POST requests or persisted GET requests.

```APIDOC
## POST/GET www.zillow.com/graphql/

### Description
This is the primary endpoint for accessing Zillow's property data using GraphQL. It supports both POST requests with a JSON payload and persisted GET requests.

### Method
POST, GET (persisted)

### Endpoint
https://www.zillow.com/graphql/

### Parameters
*Note: Specific parameters and query structures for this endpoint are not detailed in the provided text. Refer to Zillow's developer resources for a complete list.*

### Request Body (for POST)
*Note: The structure of the request body is not detailed in the provided text. Refer to Zillow's developer resources for a complete list.*

### Response
*Note: Success and error response details are not provided in the source text.*
```