Zillow API for real estate data analytics: build investment dashboards

import requests, os, pandas as pd

API_KEY = os.environ["ZILLAPI_KEY"]
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

def get_property(address):
    """Pull property data and return as a dict."""
    r = requests.get(
        "https://api.zillapi.com/v1/properties/by-address",
        params={"address": address},
        headers=HEADERS,
    )
    return r.json()["data"]

def property_to_row(data):
    """Flatten property data into an analytics-ready dict."""
    return {
        "address": data["address"]["streetAddress"],
        "city": data["address"]["city"],
        "zip": data["address"]["zipcode"],
        "zestimate": data.get("zestimate", 0),
        "rent_estimate": data.get("rentZestimate", 0),
        "price": data.get("price", 0),
        "beds": data.get("bedrooms", 0),
        "baths": data.get("bathrooms", 0),
        "sqft": data.get("livingArea", 0),
        "year_built": data.get("yearBuilt", 0),
        "home_type": data.get("homeType", ""),
        "tax_assessed": data.get("taxAssessedValue", 0),
        "tax_annual": data.get("taxAnnualAmount", 0),
        "status": data.get("homeStatus", ""),
    }

# Pull a single property
data = get_property("17 Zelma Dr, Greenville, SC 29617")
row = property_to_row(data)
df = pd.DataFrame([row])
print(df.to_string(index=False))

import time

def search_market(bbox, status="FOR_SALE", home_type="SINGLE_FAMILY"):
    """Search for properties in a geographic area."""
    r = requests.post(
        "https://api.zillapi.com/v1/search",
        json={
            "bbox": bbox,
            "listingStatus": status,
            "homeType": [home_type],
        },
        headers=HEADERS,
    )
    return r.json()["data"]

# Pull Greenville, SC market
listings = search_market(
    bbox={"north": 34.90, "south": 34.80, "east": -82.35, "west": -82.45}
)

rows = [property_to_row(p) for p in listings]
df = pd.DataFrame(rows)
print(f"Loaded {len(df)} properties into DataFrame")
print(f"Median Zestimate: ${df['zestimate'].median():,.0f}")
print(f"Median Rent: ${df['rent_estimate'].median():,.0f}")

# Gross rental yield
df["gross_yield"] = (df["rent_estimate"] * 12 / df["zestimate"] * 100).round(1)

# Price per square foot
df["price_per_sqft"] = (df["zestimate"] / df["sqft"]).round(0)

# Effective tax rate
df["tax_rate"] = (df["tax_annual"] / df["zestimate"] * 100).round(2)

# Assessment-to-market ratio
df["assessment_ratio"] = (df["tax_assessed"] / df["zestimate"] * 100).round(1)

# Estimated cap rate (with expense assumptions)
insurance = df["zestimate"] * 0.004
maintenance = df["rent_estimate"] * 12 * 0.10
vacancy = df["rent_estimate"] * 12 * 0.05
total_expenses = df["tax_annual"] + insurance + maintenance + vacancy
noi = (df["rent_estimate"] * 12) - total_expenses
df["cap_rate"] = (noi / df["zestimate"] * 100).round(1)

# Show top 10 by yield
top_yield = df.nlargest(10, "gross_yield")[
    ["address", "zestimate", "rent_estimate", "gross_yield", "cap_rate", "price_per_sqft"]
]
print(top_yield.to_string(index=False))

import matplotlib.pyplot as plt

fig, axes = plt.subplots(2, 2, figsize=(14, 10))
fig.suptitle("Greenville, SC Market Analysis", fontsize=16)

# 1. Price distribution
axes[0, 0].hist(df["zestimate"] / 1000, bins=20, color="#2196F3", edgecolor="white")
axes[0, 0].set_xlabel("Zestimate ($K)")
axes[0, 0].set_ylabel("Properties")
axes[0, 0].set_title("Price Distribution")

# 2. Yield distribution
axes[0, 1].hist(df["gross_yield"], bins=20, color="#4CAF50", edgecolor="white")
axes[0, 1].set_xlabel("Gross Yield (%)")
axes[0, 1].set_ylabel("Properties")
axes[0, 1].set_title("Yield Distribution")

# 3. Price vs rent scatter
axes[1, 0].scatter(
    df["zestimate"] / 1000, df["rent_estimate"],
    alpha=0.5, c=df["gross_yield"], cmap="RdYlGn", s=30
)
axes[1, 0].set_xlabel("Zestimate ($K)")
axes[1, 0].set_ylabel("Monthly Rent ($)")
axes[1, 0].set_title("Price vs Rent (color = yield)")

# 4. Price per sqft by beds
df.boxplot(column="price_per_sqft", by="beds", ax=axes[1, 1])
axes[1, 1].set_xlabel("Bedrooms")
axes[1, 1].set_ylabel("$/sqft")
axes[1, 1].set_title("Price per Sqft by Bedroom Count")

plt.tight_layout()
plt.savefig("market_analysis.png", dpi=150)
print("Saved market_analysis.png")

markets = {
    "Greenville, SC": {"north": 34.90, "south": 34.80, "east": -82.35, "west": -82.45},
    "Columbia, SC": {"north": 34.05, "south": 33.95, "east": -81.00, "west": -81.10},
    "Charleston, SC": {"north": 32.82, "south": 32.72, "east": -79.90, "west": -80.00},
}

import statistics

comparisons = []
for name, bbox in markets.items():
    listings = search_market(bbox, status="RECENTLY_SOLD")
    rows = [property_to_row(p) for p in listings]
    mdf = pd.DataFrame(rows)

    if len(mdf) == 0:
        continue

    mdf["gross_yield"] = (mdf["rent_estimate"] * 12 / mdf["zestimate"] * 100)
    mdf["price_per_sqft"] = mdf["zestimate"] / mdf["sqft"]
    mdf["tax_rate"] = mdf["tax_annual"] / mdf["zestimate"] * 100

    comparisons.append({
        "market": name,
        "sample_size": len(mdf),
        "median_price": mdf["zestimate"].median(),
        "median_rent": mdf["rent_estimate"].median(),
        "median_yield": mdf["gross_yield"].median(),
        "median_ppsf": mdf["price_per_sqft"].median(),
        "median_tax_rate": mdf["tax_rate"].median(),
    })
    time.sleep(0.5)

comp_df = pd.DataFrame(comparisons)
print(comp_df.to_string(index=False))

def get_price_trend(address):
    """Extract price history and calculate appreciation."""
    data = get_property(address)
    history = data.get("priceHistory", [])

    if not history:
        return None

    records = []
    for event in history:
        records.append({
            "date": event.get("date", ""),
            "event": event.get("event", ""),
            "price": event.get("price", 0),
            "source": event.get("source", ""),
        })

    hdf = pd.DataFrame(records)
    hdf["date"] = pd.to_datetime(hdf["date"], errors="coerce")
    hdf = hdf.dropna(subset=["date"])
    hdf = hdf.sort_values("date")

    # Calculate appreciation between first and last sale
    sales = hdf[hdf["event"].str.contains("Sold", case=False, na=False)]
    if len(sales) >= 2:
        first_sale = sales.iloc[0]
        last_sale = sales.iloc[-1]
        years = (last_sale["date"] - first_sale["date"]).days / 365.25
        if years > 0 and first_sale["price"] > 0:
            total_return = (last_sale["price"] - first_sale["price"]) / first_sale["price"] * 100
            annual_return = total_return / years
            return {
                "address": data["address"]["streetAddress"],
                "first_sale": first_sale["price"],
                "last_sale": last_sale["price"],
                "years": round(years, 1),
                "total_return": round(total_return, 1),
                "annual_return": round(annual_return, 1),
            }

    return None

trend = get_price_trend("17 Zelma Dr, Greenville, SC 29617")
if trend:
    print(f"Address: {trend['address']}")
    print(f"First Sale: ${trend['first_sale']:,}")
    print(f"Last Sale: ${trend['last_sale']:,}")
    print(f"Years: {trend['years']}")
    print(f"Total Return: {trend['total_return']}%")
    print(f"Annual Return: {trend['annual_return']}%/yr")

# Portfolio definition (your properties and purchase prices)
portfolio = [
    {"address": "17 Zelma Dr, Greenville, SC 29617", "purchase_price": 245000, "purchase_date": "2022-03-15", "actual_rent": 1700},
    {"address": "100 Main St, Greenville, SC 29601", "purchase_price": 189000, "purchase_date": "2021-08-20", "actual_rent": 1400},
    {"address": "45 Augusta St, Greenville, SC 29601", "purchase_price": 315000, "purchase_date": "2023-06-01", "actual_rent": 2100},
]

results = []
for prop in portfolio:
    data = get_property(prop["address"])
    row = property_to_row(data)

    zest = row["zestimate"]
    purchase = prop["purchase_price"]
    rent = prop["actual_rent"]
    tax = row["tax_annual"]

    equity_gain = zest - purchase
    equity_pct = (equity_gain / purchase * 100) if purchase else 0
    gross_yield = (rent * 12 / zest * 100) if zest else 0
    actual_yield = (rent * 12 / purchase * 100) if purchase else 0

    results.append({
        "address": row["address"],
        "purchase": purchase,
        "current_value": zest,
        "equity_gain": equity_gain,
        "equity_pct": round(equity_pct, 1),
        "actual_rent": rent,
        "rent_estimate": row["rent_estimate"],
        "rent_gap": rent - row["rent_estimate"],
        "gross_yield": round(gross_yield, 1),
        "yield_on_cost": round(actual_yield, 1),
        "annual_tax": tax,
    })
    time.sleep(0.35)

pdf = pd.DataFrame(results)

# Portfolio summary
total_invested = pdf["purchase"].sum()
total_value = pdf["current_value"].sum()
total_equity = pdf["equity_gain"].sum()
total_rent = pdf["actual_rent"].sum() * 12
portfolio_yield = total_rent / total_value * 100

print("Portfolio Summary")
print(f"Properties: {len(pdf)}")
print(f"Total Invested: ${total_invested:,}")
print(f"Current Value: ${total_value:,}")
print(f"Total Equity Gain: ${total_equity:,} ({total_equity/total_invested*100:.1f}%)")
print(f"Annual Rent Income: ${total_rent:,}")
print(f"Portfolio Yield: {portfolio_yield:.1f}%")
print()
print(pdf[["address", "purchase", "current_value", "equity_gain", "equity_pct", "yield_on_cost"]].to_string(index=False))