Every parameter, response field, error code, and code example for all ZipMarketData endpoints. All authenticated endpoints require X-RapidAPI-Key and X-RapidAPI-Host: real-estate-market-data.p.rapidapi.com headers. See the RapidAPI Guide for authentication setup.
On this page
GET
/market-stats
Returns current real estate market statistics for any US ZIP code, including median prices, days on market, inventory levels, and year-over-year price change. Covers 28,000+ ZIP codes with real MLS data from Redfin. All other ZIP codes return a clearly-labelled estimate anchored to regional averages.
Query Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| zip_code | string | Required | 5-digit US ZIP code (digits only) | 78701 |
Response Fields
| Field | Type | Description |
|---|---|---|
| zip_code | string | The requested ZIP code |
| data_date | string | Month of data in YYYY-MM format |
| median_sale_price | integer | Median closed sale price in USD |
| median_list_price | integer | Median active listing price in USD |
| median_days_on_market | integer | Median days from list to pending/sold |
| active_listings | integer | Current active listing count |
| new_listings_30d | integer | New listings added in the past 30 days |
| price_reduced_pct | float | Fraction of listings with a price reduction (e.g. 0.18 = 18%) |
| list_to_sale_ratio | float | Sale price ÷ list price ratio (e.g. 0.982 = 98.2%) |
| mom_price_change | float | Month-over-month price change as decimal (0.004 = 0.4%) |
| yoy_price_change | float | Year-over-year price change as decimal (0.061 = 6.1%) |
| market_temperature | string | "Hot 🔥", "Warm", "Balanced", "Cool", or "Buyer's Market" |
| inventory_months | float | Months of supply at current absorption rate |
| data_source | string | "redfin_mls" (real) or "estimated" |
| data_note | string | Present only when data_source = "estimated" |
Market Temperature Scale
| Label | Days on Market | Market Condition |
|---|---|---|
| Hot 🔥 | < 15 days | Extreme seller's market — offers above asking, waived contingencies |
| Warm | 15–27 days | Seller's market — multiple offers common |
| Balanced | 28–41 days | Balanced market — negotiation possible |
| Cool | 42–57 days | Buyer-leaning — price reductions common |
| Buyer's Market | 58+ days | Strong buyer's market — significant negotiating power |
Example — cURL
curl -s \
-H "X-RapidAPI-Key: YOUR_KEY" \
-H "X-RapidAPI-Host: real-estate-market-data.p.rapidapi.com" \
"https://real-estate-market-data.p.rapidapi.com/market-stats?zip_code=90210"
Example — Python
import requests, os
resp = requests.get(
"https://real-estate-market-data.p.rapidapi.com/market-stats",
params={"zip_code": "90210"},
headers={
"X-RapidAPI-Key": os.environ["RAPIDAPI_KEY"],
"X-RapidAPI-Host": "real-estate-market-data.p.rapidapi.com"
},
timeout=10
)
data = resp.json()
print(f"${data['median_sale_price']:,} — {data['market_temperature']}")
Example Response
{
"zip_code": "90210",
"data_date": "2026-03",
"median_sale_price": 3850000,
"median_list_price": 3928000,
"median_days_on_market": 38,
"active_listings": 214,
"new_listings_30d": 67,
"price_reduced_pct": 0.27,
"list_to_sale_ratio": 0.961,
"mom_price_change": 0.0018,
"yoy_price_change": 0.034,
"market_temperature": "Balanced",
"inventory_months": 3.2,
"data_source": "redfin_mls"
}
GET
/price-history
Returns 12 months of median sale price, list price, sales count, and days-on-market data for any US city. Use this to chart price trends, identify seasonal patterns, and calculate appreciation rates. Optionally filter by property type.
Query Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| city | string | Required | City name (minimum 2 characters) | Austin |
| state | string | Required | 2-letter state abbreviation (uppercase) | TX |
| property_type | string | Optional | Filter: "all", "single_family", "condo", "townhouse" (default: "all") | single_family |
Response Fields
| Field | Type | Description |
|---|---|---|
| city | string | City name (title-cased) |
| state | string | 2-letter state code |
| property_type | string | The requested property type filter |
| monthly_data | array | Array of 12 monthly data objects (see below) |
| appreciation_12m_pct | float | Total % appreciation from first to last month (e.g. 5.2 = 5.2%) |
| peak_month | string | Month with highest median price in YYYY-MM format |
| months_available | integer | Number of months returned (up to 12) |
| data_source | string | "redfin_mls" or "estimated" |
monthly_data Object Fields
| Field | Type | Description |
|---|---|---|
| month | string | Month in YYYY-MM format |
| median_sale_price | integer | Median closed sale price that month |
| median_list_price | integer | Median list price that month |
| sales_count | integer | Number of closed sales that month |
| days_on_market | integer | Median days on market that month |
Example — cURL
curl -s \
-H "X-RapidAPI-Key: YOUR_KEY" \
-H "X-RapidAPI-Host: real-estate-market-data.p.rapidapi.com" \
"https://real-estate-market-data.p.rapidapi.com/price-history?city=Austin&state=TX&property_type=single_family"
Example — Python with chart output
import requests, os
resp = requests.get(
"https://real-estate-market-data.p.rapidapi.com/price-history",
params={"city": "Austin", "state": "TX", "property_type": "single_family"},
headers={
"X-RapidAPI-Key": os.environ["RAPIDAPI_KEY"],
"X-RapidAPI-Host": "real-estate-market-data.p.rapidapi.com"
},
timeout=10
)
data = resp.json()
print(f"{data['city']}, {data['state']} — {data['property_type']}")
print(f"12-month appreciation: {data['appreciation_12m_pct']:+.1f}%")
print(f"Peak month: {data['peak_month']}")
print()
for m in data["monthly_data"]:
bar = "█" * (m["median_sale_price"] // 50000)
print(f"{m['month']} ${m['median_sale_price']:>8,} {bar}")
Example Response (truncated)
{
"city": "Austin",
"state": "TX",
"property_type": "single_family",
"monthly_data": [
{
"month": "2025-04",
"median_sale_price": 578000,
"median_list_price": 595000,
"sales_count": 412,
"days_on_market": 28
},
{
"month": "2025-05",
"median_sale_price": 591000,
"median_list_price": 609000,
"sales_count": 487,
"days_on_market": 24
}
// ... 10 more months
],
"appreciation_12m_pct": 5.8,
"peak_month": "2026-01",
"months_available": 12,
"data_source": "redfin_mls"
}
GET
/rental-yield
Returns gross rental yield analysis for any US ZIP code, combining HUD Small Area Fair Market Rent data with Redfin median sale prices. Covers bedroom counts from 1 to 5. Use gross yield as a starting screen — subtract 35–45% for operating expenses to estimate net yield.
Query Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| zip_code | string | Required | 5-digit US ZIP code | 78701 |
| bedrooms | integer | Optional | Number of bedrooms: 1–5 (default: 2) | 3 |
Response Fields
| Field | Type | Description |
|---|---|---|
| zip_code | string | The requested ZIP code |
| bedrooms | integer | Bedroom count used for the estimate |
| median_sale_price | integer | Median home price used for yield calculation |
| estimated_monthly_rent | integer | HUD Fair Market Rent for this bedroom count |
| estimated_annual_rent | integer | Monthly rent × 12 |
| gross_yield_pct | float | Annual rent ÷ sale price × 100 (e.g. 7.2 = 7.2%) |
| yield_rating | string | "Excellent" (>8%), "Good" (6–8%), "Average" (4–6%), "Low" (<4%) |
| rent_to_price_ratio | float | Monthly rent ÷ sale price × 100 (the "1% rule" benchmark) |
| hud_fmr_year | integer|null | Year of the HUD FMR data used |
| data_source | string | "hud_fmr" (real) or "estimated" |
| disclaimer | string | Reminder that this is gross yield before expenses |
Gross yield vs net yield
The API returns gross yield (annual rent ÷ purchase price). To estimate net yield, subtract ~35–45% for operating expenses: property tax, insurance, maintenance, vacancy, and management fees. A gross yield of 8% translates to roughly 4.4–5.2% net.
Example — cURL (3-bedroom)
curl -s \
-H "X-RapidAPI-Key: YOUR_KEY" \
-H "X-RapidAPI-Host: real-estate-market-data.p.rapidapi.com" \
"https://real-estate-market-data.p.rapidapi.com/rental-yield?zip_code=78701&bedrooms=3"
Example — JavaScript (all bedroom sizes)
const apiKey = process.env.RAPIDAPI_KEY;
const host = "real-estate-market-data.p.rapidapi.com";
async function rentalMatrix(zipCode) {
const results = await Promise.all(
[1, 2, 3, 4].map(async (br) => {
const url = new URL(`https://${host}/rental-yield`);
url.searchParams.set("zip_code", zipCode);
url.searchParams.set("bedrooms", br);
const r = await fetch(url, {
headers: { "X-RapidAPI-Key": apiKey, "X-RapidAPI-Host": host }
});
return r.json();
})
);
console.log(`Rental matrix for ZIP ${zipCode}`);
results.forEach(d => {
console.log(
` ${d.bedrooms}BR: $${d.estimated_monthly_rent}/mo ` +
`→ ${d.gross_yield_pct}% gross yield (${d.yield_rating})`
);
});
}
rentalMatrix("78701");
Example Response
{
"zip_code": "78701",
"bedrooms": 2,
"median_sale_price": 685000,
"estimated_monthly_rent": 2180,
"estimated_annual_rent": 26160,
"gross_yield_pct": 3.82,
"yield_rating": "Low",
"rent_to_price_ratio": 0.318,
"hud_fmr_year": 2024,
"data_source": "hud_fmr",
"disclaimer": "Gross yield. Subtract ~35–45% for expenses to estimate net yield."
}
GET
/affordability
Returns a housing affordability index for any US metro area, using Census ACS median income and Redfin median home prices. The index measures whether a median-income household can comfortably afford a median-priced home: 100 = exactly affordable, above 100 = comfortable, below 100 = stretched. Pass your personal income for a tailored DTI analysis.
Query Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| metro | string | Required | Metro area or city name (minimum 2 chars) | Austin |
| income | integer | Optional | Your annual household income in USD (10,000–10,000,000) for personalised scoring | 95000 |
Response Fields
| Field | Type | Description |
|---|---|---|
| metro | string | Input metro name (title-cased) |
| matched_metro | string | Matched name from Census ACS database |
| affordability_index | float | Index score (100 = break-even, >100 = affordable, <100 = stretched) |
| interpretation | string | "Affordable" (≥100), "Stretched" (70–99), or "Unaffordable" (<70) |
| median_household_income | integer | Median household income for the metro (Census ACS) |
| median_home_price | integer | Estimated median home price for the metro |
| price_to_income_ratio | float | Home price ÷ annual income (lower is better; 3–4x is historically healthy) |
| monthly_payment_estimate | integer | Est. monthly P&I on median home (20% down, 7% rate) |
| down_payment_20pct | integer | 20% down payment amount in USD |
| years_to_save_down_payment | float | Years to save 20% down at 15% annual savings rate |
| income_data_year | integer | Year of the Census ACS income data |
| data_source | string | "census_acs+redfin_mls", "census_acs", or "estimated" |
| personalized | object|absent | Present only when income parameter is supplied (see below) |
personalized Object (when income is supplied)
| Field | Type | Description |
|---|---|---|
| household_income | integer | Your supplied income |
| monthly_payment | integer | Est. monthly payment on median home |
| debt_to_income_pct | float | Monthly payment as % of monthly income |
| affordability_verdict | string | "Comfortable" (<28% DTI), "Manageable" (28–35%), "Stretched" (36–42%), "Difficult" (>43%) |
| max_home_price_28dti | integer | Maximum affordable home price at 28% DTI threshold |
Example — cURL with personal income
curl -s \
-H "X-RapidAPI-Key: YOUR_KEY" \
-H "X-RapidAPI-Host: real-estate-market-data.p.rapidapi.com" \
"https://real-estate-market-data.p.rapidapi.com/affordability?metro=Denver&income=95000"
Example — Python (compare multiple metros)
import requests, os
API_KEY = os.environ["RAPIDAPI_KEY"]
HEADERS = {
"X-RapidAPI-Key": API_KEY,
"X-RapidAPI-Host": "real-estate-market-data.p.rapidapi.com"
}
metros = ["Austin", "Denver", "Phoenix", "Raleigh", "Nashville"]
print(f"{'Metro':<12} {'Index':>6} {'Label':<14} {'P/I Ratio':>9}")
print("─" * 50)
for metro in metros:
resp = requests.get(
"https://real-estate-market-data.p.rapidapi.com/affordability",
params={"metro": metro},
headers=HEADERS,
timeout=10
)
d = resp.json()
print(
f"{d['metro']:<12} {d['affordability_index']:>6.1f} "
f"{d['interpretation']:<14} {d['price_to_income_ratio']:>9.1f}x"
)
Example Response
{
"metro": "Denver",
"matched_metro": "Denver-Aurora-Lakewood, CO",
"affordability_index": 74.2,
"interpretation": "Stretched",
"median_household_income": 82400,
"median_home_price": 598000,
"price_to_income_ratio": 7.3,
"monthly_payment_estimate": 3186,
"down_payment_20pct": 119600,
"years_to_save_down_payment": 9.7,
"income_data_year": 2022,
"data_source": "census_acs+redfin_mls",
"personalized": {
"household_income": 95000,
"monthly_payment": 3186,
"debt_to_income_pct": 40.2,
"affordability_verdict": "Stretched",
"max_home_price_28dti": 418285,
"note": "28% DTI is the standard lender threshold for comfortable mortgage payments."
}
}
GET
/property-estimate
Returns a comprehensive investment analysis for any US ZIP code: estimated property value with confidence range, gross yield, cap rate, monthly cash flow, and cash-on-cash return. Assumes 20% down payment, 7% mortgage rate, 30-year loan, 40% expense ratio, and a 2-bedroom unit. Adjust your own model using the raw figures returned.
Query Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| zip_code | string | Required | 5-digit US ZIP code | 78701 |
Response Fields
| Field | Type | Description |
|---|---|---|
| zip_code | string | The requested ZIP code |
| estimated_value | integer | Median sale price (basis for all calculations) |
| value_range_low | integer | Lower bound of value estimate (−12% of median) |
| value_range_high | integer | Upper bound of value estimate (+12% of median) |
| gross_yield_pct | float | Annual rent ÷ estimated value × 100 |
| data_source | string | "redfin_mls" or "estimated" |
| investment_metrics | object | Core investment calculations (see below) |
| assumptions | object | Inputs used for the investment model |
investment_metrics Object
| Field | Type | Description |
|---|---|---|
| monthly_cash_flow | integer | Monthly rent after expenses minus mortgage payment (can be negative) |
| cap_rate_pct | float | Net operating income ÷ property value × 100 |
| cash_on_cash_return_pct | float | Annual cash flow ÷ down payment × 100 |
| investment_rating | string | "Excellent" (CoC≥8%), "Good" (4–7.9%), "Average" (0–3.9%), "Negative Cash Flow ⚠️" |
| down_payment_20pct | integer | 20% down payment in USD |
| monthly_mortgage | integer | Monthly principal + interest payment |
| estimated_monthly_rent | integer | HUD Fair Market Rent used for the model (2BR) |
assumptions Object
| Field | Value | Notes |
|---|---|---|
| down_payment_pct | 20 | Standard conventional loan minimum |
| mortgage_rate_pct | 7.0 | Approximate 30-year fixed rate at time of data |
| loan_term_years | 30 | Standard amortization period |
| expense_ratio_pct | 40 | Covers tax, insurance, maintenance, vacancy, management |
| bedrooms | 2 | HUD FMR bedroom category used for rent estimate |
Example — cURL
curl -s \
-H "X-RapidAPI-Key: YOUR_KEY" \
-H "X-RapidAPI-Host: real-estate-market-data.p.rapidapi.com" \
"https://real-estate-market-data.p.rapidapi.com/property-estimate?zip_code=30301"
Example — Python (bulk investment screener)
import requests, os, time
API_KEY = os.environ["RAPIDAPI_KEY"]
HEADERS = {
"X-RapidAPI-Key": API_KEY,
"X-RapidAPI-Host": "real-estate-market-data.p.rapidapi.com"
}
TARGET_ZIPS = ["30301", "37201", "28201", "35203", "45201"]
print(f"{'ZIP':<8} {'Price':>10} {'Cap Rate':>9} {'Cash Flow':>10} {'Rating'}")
print("─" * 58)
for zip_code in TARGET_ZIPS:
resp = requests.get(
"https://real-estate-market-data.p.rapidapi.com/property-estimate",
params={"zip_code": zip_code},
headers=HEADERS,
timeout=10
)
d = resp.json()
m = d["investment_metrics"]
print(
f"{zip_code:<8} ${d['estimated_value']:>9,} "
f"{m['cap_rate_pct']:>8.1f}% "
f"${m['monthly_cash_flow']:>+9,}/mo "
f"{m['investment_rating']}"
)
time.sleep(0.5)
Example Response
{
"zip_code": "30301",
"estimated_value": 310000,
"value_range_low": 272800,
"value_range_high": 347200,
"gross_yield_pct": 8.14,
"data_source": "redfin_mls",
"investment_metrics": {
"monthly_cash_flow": +284,
"cap_rate_pct": 4.89,
"cash_on_cash_return_pct": 11.02,
"investment_rating": "Excellent",
"down_payment_20pct": 62000,
"monthly_mortgage": 1653,
"estimated_monthly_rent": 2103
},
"assumptions": {
"down_payment_pct": 20,
"mortgage_rate_pct": 7.0,
"loan_term_years": 30,
"expense_ratio_pct": 40,
"bedrooms": 2
}
}
GET
/health
Returns the API status and data coverage counts. No authentication required. Use this to verify the API is running and check how many ZIP codes, cities, and metros have real data loaded. Useful for monitoring and debugging.
Example Response
{
"status": "ok",
"timestamp": 1743724800,
"api_version": "1.1.0",
"data_coverage": {
"zip_codes_with_market_data": 28412,
"cities_with_price_history": 3247,
"zip_codes_with_rental_data": 29018,
"metros_with_income_data": 923
},
"pipeline_status": {
"last_run": "2026-04-04T03:00:12Z",
"status": "success",
"records_loaded": 28412
}
}
Error Reference
All error responses use a consistent JSON format:
{ "detail": "Human-readable error description" }
| Status | Code Name | Common Causes | Resolution |
|---|---|---|---|
| 400 | Bad Request | Non-numeric ZIP code; state code not exactly 2 chars; city name under 2 chars | Validate inputs before calling. ZIP must be exactly 5 digits (e.g. "07030", not "7030"). |
| 403 | Forbidden | Missing or invalid RapidAPI key; calling the API directly without RapidAPI headers | Ensure X-RapidAPI-Key and X-RapidAPI-Host headers are present and correct. |
| 422 | Unprocessable Entity | Bedrooms outside 1–5; income below 10,000 or above 10,000,000 | Check the detail field — it names the failing parameter and constraint. |
| 429 | Too Many Requests | Exceeded daily plan limit or burst limit (120 req/min) | Implement exponential backoff. Cache responses for 24h. Upgrade plan if hitting daily limits regularly. |
| 500 | Internal Server Error | Transient database or server error | Retry after 5 seconds. Open a support ticket if the error persists for more than 5 minutes. |