
This page is for a product lead at a lending startup. They want a housing data API behind one market panel per ZIP code, on an internal underwriting screen. It covers the public sources first. Then it shows what our market-outlook call returns, what it costs and which figures describe the metro rather than the ZIP code.
Public housing market data by ZIP code
The Census Bureau's API serves the 2020 to 2024 American Community Survey 5-year estimates. Variable B25077_001E is the median value of owner-occupied housing units, and the API returns it by ZIP code tabulation area. A call needs a key, which the Census Bureau issues on request.
Those areas are the Census Bureau's approximations of ZIP codes, not the postal routes themselves. FHFA publishes a price index for 5-digit ZIP codes as an annual spreadsheet, labeled a developmental index and not seasonally adjusted.
Both sources update once a year. Neither says whether a ZIP code favors buyers or sellers this quarter, or how fast properties sell there. That is the job of a housing data API that answers per call.
What a housing data API returns
Our market-outlook call takes one required parameter, zip, and an optional days lookback that defaults to 90. It costs 2 credits. A request that fails with a 400, 401 or 402 costs 0 credits.
The table lists the top-level fields, using the names from the market-outlook page in our API docs. It shows field names only, with no values.
| Field in the API docs | What it holds |
|---|---|
| outlook_score | A value from 0 to 100, a label and a color_code |
| forecast_bars | One entry per horizon, each with label, percentage, trend and heat_index |
| market_velocity | avg_days_on_market_metro and local_absorption_rate |
| micro_stats | active_count, sold_count_90d, pending_count_90d and absorption_rate_pct for the ZIP code |
| source_breakdown | One block per input, named metro_index, local_transactions and metro_status, each with an available flag |
| weights_used | The weight each input carried on this call |
| metro_name, timestamp | The metro the ZIP code sits in, and when the response was built |
The docs set the score bands. Below 40 reads as a buyer's market, 40 to 60 as balanced and above 60 as a seller's market. They list 1, 3 and 6-month forecasts, and our Boise call returned all 3.
One Boise ZIP code sold 215 properties in 90 days against 105 active listings, an absorption of 204.76%.
When live market data is unavailable, the docs say its weight moves to the other 2 inputs. The weights_used field shows the weights applied, so read it and each available flag before you compare 2 scores.
How to build a ZIP code market box

- Pick the ZIP codes. The call takes one ZIP code at a time. For a city or county, the docs say to query each ZIP code and aggregate the results yourself.
- Call market-outlook for each ZIP code. Keep days at the default 90 unless the panel needs a shorter lookback. Each call costs 2 credits.
- Add sold/count-by-zip for a 365-day sales count. It costs 1 credit and puts a yearly figure next to the 90-day counts.
- Read the fields the panel needs. Most panels use outlook_score, the forecast_bars array and micro_stats. Store the timestamp with every figure.
- Handle the gaps. Check each available flag in source_breakdown and allow for null fields. The docs say to retry a 503 with backoff.
At 3 credits a ZIP code, a panel for 40 ZIP codes costs 120 credits per refresh. Our Boise call took 6.8 seconds, so cache each response with its timestamp. Here is the call, with the key read from an environment variable.
curl -G "https://api.homesage.ai/api/properties/market-outlook/" \ -H "Authorization: Bearer $HOMESAGE_API_KEY" \ --data-urlencode "zip=<a 5-digit US ZIP code>" \ --data-urlencode "days=90" The response comes back in this shape, trimmed, with types in place of values.
{ "metro_name": "City, ST", "timestamp": "ISO 8601 time", "outlook_score": {"value": "0 to 100", "label": "text", "color_code": "hex"}, "forecast_bars": [ {"label": "1 Month", "percentage": "number", "trend": "up or down", "heat_index": "number"} ], "micro_stats": {"active_count": "integer", "sold_count_90d": "integer", "pending_count_90d": "integer", "absorption_rate_pct": "number"} } Our guide to reading a housing market forecast for your ZIP code walks an investor through the same figures.
A real example from a Homesage.ai API call
We called market-outlook on 2026-11-07 for one Boise, Idaho ZIP code, with days=30. We also ran sold/count-by-zip for the 365 days to the same date, single-family only. The 2 calls used 3 credits.
| What the 2 calls returned | One Boise ZIP code |
|---|---|
| metro_name | Boise City-Nampa, ID |
| outlook_score | 71.1, Seller's Market |
| weights_used | metro_index 0.5, local_transactions 0.5, metro_status 0 |
| source_breakdown scores | metro_index 42.11, local_transactions 100, metro_status null and unavailable |
| Score check | 0.5 × 42.11 + 0.5 × 100 = 71.055, returned as 71.1 |
| metro_index data_date | 2026-09-30 |
| forecast_bars, estimated | 1 Month +0.6%, 3 Months +2%, 6 Months +1.65%, all up |
| avg_days_on_market_metro | 37 |
| micro_stats | active_count 105, sold_count_90d 215, pending_count_90d 0 |
| absorption_rate_pct | 204.76, which is 215 ÷ 105 × 100 |
| sold/count-by-zip, 365 days, single_family | 434 |
| Response time, market-outlook | 6.8 seconds |
The score sits between its 2 inputs. The local_transactions score of 100 lifted it above 60, and the metro_index score of 42.11 held it down. That metro part was dated 2026-09-30, so it lagged the call by about 5 weeks.

All 3 estimated forecasts point up, with the 3-month bar highest at 2%. The metro_status input came back unavailable with a null score, and pending_count_90d was 0. Panel code has to show those gaps as gaps.

Common market data mistakes to avoid
- Reading a metro figure as a ZIP code figure: avg_days_on_market_metro covers the metro. The micro_stats counts cover the ZIP code alone.
- Hard-coding the forecast bars: The spec example returns 2 bars and our Boise call returned 3. Loop over forecast_bars instead.
- Comparing a 90-day count with a 365-day count: In Boise, micro_stats showed 215 sales in 90 days. Our single-family count showed 434 in 365 days. The windows and filters differ, so neither scales to the other.
- Treating a survey median as a sale price: Census variable B25077_001E is the median value of owner-occupied units from survey estimates. No sale stands behind it.
- Ignoring weights_used: When an input is unavailable, the weights change. Compare 2 scores only when they were built on the same weights.
Your account terms set where these outputs can be shown, so check them before a score reaches your own customers.
Estimated values. Not investment advice. Data as of 2026-11-07.
Related reading: Is there a neighborhood data API?, What is the absorption rate in real estate?, Where can I get home sales data for an app?.
Frequently asked questions
Is there a free housing market data API?
How do I get housing market data by ZIP code?
How do you tell a buyer's market from a seller's market?
How often is housing market data updated?
Can I get housing market data for a city or county?
Try the call
Run market-outlook on one ZIP code before you wire up the whole list. Parameters, fields and errors are in our API docs.
- Homesage.ai API calls to market-outlook and sold/count-by-zip for one Boise, Idaho ZIP code, pulled 2026-11-07.
- Homesage.ai API docs, market-outlook, read 2026-11-07.
- Homesage.ai API docs, sold-count-by-zip, read 2026-11-07.
- US Census Bureau, American Community Survey 5-year data sets, 2020 to 2024 release.
- US Census Bureau, variable B25077_001E, median value.
- US Census Bureau, ZIP code tabulation areas.
- FHFA, house price index datasets, five-digit ZIP code file.