
This page is for a developer at a lending startup who needs recent sale prices by ZIP code for an internal pricing model. It covers the national figures first. Then it shows what our 2 sold-data calls return, what they cost and where a price goes missing.
Where national home sales data comes from
The National Association of Realtors publishes existing-home sales each month. Its September 2026 report, released 2026-10-13, put sales 2.2% below a year earlier. The median price was $417,500. New-home sales come from a monthly report by the Census Bureau and HUD. Both describe the nation and its regions, not single properties or ZIP codes.
A pricing model needs the sale itself, meaning what sold, for how much and when. A comparative market analysis starts from the same rows.
What our sold-data calls return
Our API has 2 sold-data calls, and both take a 5-digit ZIP code. One returns a count. The other returns one row per sale.
| Call | What it returns | Credits |
|---|---|---|
| GET /api/properties/sold/count-by-zip/ | The number of properties sold in the ZIP code, as zip_code and count | 1 credit per call |
| GET /api/properties/sold/by-zip/ | One row per property sold in the ZIP code | 1 credit per 20 properties returned, rounded up |
Both calls take the same filters. The start_date and end_date parameters narrow the window. Both bounds are inclusive and must fall within the last 365 days.
The property_type parameter keeps only the types you model, such as single_family or condos. On the list call, limit caps the result at the most recent sales, and limit=20 always costs 1 credit.
The table lists what each row of the list call holds, using the field names from the sold-by-zip page in our API docs.
| Field in the API docs | What it holds |
|---|---|
| sold_price | Sale price in US dollars, or null when the price is withheld |
| sold_date | Sale date as YYYY-MM-DD, always within the last 365 days |
| property_type | The type as stored, such as single_family, condos or townhomes |
| dom | Days on market before the sale, or null when listing dates are missing |
| total_size, lot_size | Living area and lot size, both in square feet |
| bedrooms, bathrooms | Room counts, with bathrooms such as 2.5 for 2 full and 1 half |
| year_built, stories, parking | Build year, floor count and parking spaces |
| property_address, latitude, longitude | The street address and its WGS-84 coordinates |
The docs say each ZIP code's cache refreshes on demand once it is older than 4 hours.
In one Denver ZIP code, a limit of 40 cost 2 credits and reached back only to September. All 173 sales would cost 9.
How to pull home sales data

- Count the sales first. Call sold/count-by-zip with your ZIP code, dates and property_type for 1 credit. The count prices the list before you pull it, so 173 sales cost 9 credits.
- Pull the list with the same filters. Leave limit off for the whole window, or set it to cap the cost. When you poll, pull one month at a time instead of the whole year.
- Read the fields you need. A pricing model wants sold_price, sold_date and property_type. The call returns rows, so you compute the median and the bands yourself.
- Handle the gaps. Drop or count the rows where sold_price is null. A 402 on the list call puts the credit estimate in the error body, so lower limit and retry. The docs mark a 503 as safe to retry.
Here is the list call for one window, with the key read from an environment variable.
curl -G "https://api.homesage.ai/api/properties/sold/by-zip/" \ -H "Authorization: Bearer $HOMESAGE_API_KEY" \ --data-urlencode "zip=<a 5-digit US ZIP code>" \ --data-urlencode "start_date=2026-05-07" \ --data-urlencode "end_date=2026-11-07" \ --data-urlencode "property_type=single_family" Rows come back in this shape, with types in place of values.
[ { "sold_date": "YYYY-MM-DD", "sold_price": "integer, or null", "property_type": "single_family", "total_size": "integer, or null", "dom": "integer, or null" } ] The list call charges only on a 200, so a 400, 401 or 402 costs 0 credits.
Missing sale prices and non-disclosure states
Some rows carry sold_price as null. Our docs give private sales, off-market transfers and some agent sales as cases where the price is withheld. The property still appears in the list, because it sold.
State law adds a second gap. Our comps endpoint docs warn that in a non-disclosure state, sale prices are not publicly recorded, which limits comp data. Their example names Missouri.
So report coverage next to any figure you compute, as sales with a price out of all sales counted. The dom field also comes back null when listing dates are missing.
A real example from a Homesage.ai API call
We ran both calls on 2026-11-07 for one Denver, Colorado ZIP code. The window ran from 2026-05-07 to 2026-11-07, single-family only. The count call returned 173 sales for 1 credit. We pulled the list with limit=40, which cost 2 credits.
| What the 2 calls returned | One Denver ZIP code |
|---|---|
| Window and filter | 2026-05-07 to 2026-11-07, single_family |
| count from sold/count-by-zip | 173, for 1 credit |
| Rows from sold/by-zip with limit=40 | 40, for 2 credits, in 752 ms |
| Credits to pull all 173 rows | 9, as 173 ÷ 20 rounded up |
| Months the 40 rows cover | September to November 2026 |
| Rows with a sold_price | 40 of 40 |
| Median sold_price, computed by us | $415,000 |
| Rows from $350,000 to $499,999 | 27 of 40 |
| Median dom, computed by us | 33 days |
Every one of the 40 rows carried a sold_price, so none was dropped. Their median is $415,000, and 27 of the 40 sold between $350,000 and $499,999.

The 40 rows reach back only to September, with 29 in October. A 6-month median needs all 173 rows, and that list costs 9 credits.

Common sold-data mistakes to avoid
- Reading limit=20 as a month: The limit returns the most recent sales, whatever their dates. Set start_date and end_date for a fixed window.
- Taking a median over null prices: Count only rows with a sold_price, and keep the number of rows you dropped.
- Using different filters on the 2 calls: Send the same dates and property_type to both, or the count stops describing the list.
- Mixing property types: Without property_type, the list returns every type, from single_family to mobile. A median across them blends condos with single-family sales.
- Asking for older sales: A date more than 365 days back returns a 400 that names the earliest date served. To compare with last year, store each month as you pull it.
Your account terms set where these outputs can be shown, so check them before any figure reaches your own customers.
General information. Not investment advice. Data as of 2026-11-07.
Related reading: How do I get foreclosure data for an app?, Is there a real estate listings API?.
Frequently asked questions
Is home sales data public record?
Where can I find home sales data by ZIP code?
How many homes sell in the US each year?
Why do some sales have no price?
How far back does the sold data go?
Try the call
Run sold/count-by-zip on one ZIP code first, then pull the list knowing what it costs. Parameters, fields and errors for both calls are in our API docs.
- Homesage.ai API calls to sold/count-by-zip and sold/by-zip for one Denver, Colorado ZIP code, pulled 2026-11-07.
- Homesage.ai API docs, sold-by-zip, field names and credit cost read 2026-11-07.
- Homesage.ai API docs, sold-count-by-zip, read 2026-11-07.
- Homesage.ai API docs, comps, non-disclosure warning read 2026-11-07.
- National Association of Realtors, existing-home sales for September 2026, released 2026-10-13.
- US Census Bureau and HUD, monthly new-home sales.