
What a real estate listings API returns
A CTO at a deal-finder startup needs one feed of for-sale properties, filtered by area and price, inside the app. A real estate listings API answers that query for code. You send a location, a listing status and at least one filter, and it returns the matching properties.
Ours searches by city, county or ZIP code. It never searches a whole state, because a state-wide query times out before it returns.
Resolve each area with GET /api/area/autocomplete/ rather than typing the object by hand. Our docs say this keeps the city name, state_code and county name matched to the database.
- Location: a JSON-encoded array of area objects, each a city, a county or a ZIP code.
- Status: active and pending search properties for sale, sold searches past sales and any covers active plus pending.
- Filters: at least one, such as a price range, a property type or a property condition. Setting allow_location_only to true waives this rule.
- Results: each matching property, with its list price, property condition and our estimated value.
Filters a builder can send
In our real estate listings API, the count call and the search take the same filters. Send the exact set you previewed, so the charge matches the cost you saw.
| Parameter | What it filters |
|---|---|
| price_min, price_max | List price in USD for a for-sale search, sold price for a sold search |
| property_type | detached, townhouse, apartment, multi family or other, joined with a pipe |
| property_condition | Property condition, from excellent down to very poor |
| monthly_rent_min, monthly_rent_max | Estimated monthly rent in whole USD |
| dom | A days-on-market ceiling, for-sale only |
| from, to | Sold dates in YYYY-MM-DD form, sold search only |
A search with only a location and a status returns a 400, and its missing array names the gap. Setting allow_location_only to true skips that rule, so check the count first. A location-only search in a dense metro can match thousands of properties.
The count call is GET /api/workspace/search/count/. It returns 2 fields, count and cost, and our docs say it never charges credits. The location value is JSON inside a query string, so let curl encode it with --data-urlencode.
curl -G 'https://api.homesage.ai/api/workspace/search/count/' \ -H "Authorization: Bearer $HOMESAGE_API_KEY" \ --data-urlencode 'location=[{"type":"city","city":"Tampa","state_code":"FL"}]' \ --data-urlencode 'property_status=active' \ --data-urlencode 'property_type=detached' \ --data-urlencode 'price_min=250000' \ --data-urlencode 'price_max=400000' \ --data-urlencode 'property_condition=outdated|poor' \ --data-urlencode 'monthly_rent_min=3000' The search is POST /api/workspace/search/ with the same filters in a JSON body. Its response carries count, charged and credits_left. It also returns a search_id and a data array of properties.
{ "count": 3, "charged": 3, "credits_left": <new balance>, "search_id": "<id>", "data": [ <1 object per property> ] } A real example from a Homesage.ai API call
We searched active single-family properties for sale in Tampa, Florida, on 2026-11-07. We sent the 7 filters in the curl sample above. Four count calls narrowed the set at 0 credits, and the search returned 3 properties for 3 credits.

Each filter cut the set before any credit moved. The price band took 1,422 matches to 488, property condition took them to 182 and a $3,000 rent floor left 3.
| What the search returned | Property 1 | Property 2 | Property 3 |
|---|---|---|---|
| Property condition | Poor | Outdated | Outdated |
| Type of sale | Foreclosure | Standard | Standard |
| List price | $349,900 | $389,000 | $375,000 |
| Estimated value | $603,040 | $396,105 | $409,614 |
| Verified monthly rent | $3,504 | $3,904 | $3,200 |
| Monthly rent ÷ list price | 1.00% | 1.00% | 0.85% |
Verified rent here means the rent advertised on a recent rental listing for each property, checked in our listing data. No lease stands behind it.

Property 2 and Property 3 list 2% and 8% under their estimated values. Property 1 is a foreclosure in poor condition, and its estimate sits far above its price. Inspect a property with a gap that size before you trust the estimate.
In Tampa, 4 count calls took 1,422 single-family properties for sale down to 3 before the search charged a credit.
How to run a listings search

- Resolve the area. GET /api/area/autocomplete/ turns a place name into the city, county or ZIP object that the location filter expects. It costs 0 credits.
- Preview the count. Send your filters to the count call and read count and cost.
- Tighten the filters. The search takes no result limit in our API spec, so narrow the price band, type or condition until the cost fits.
- Run the same filters. Send the exact set you previewed to POST /api/workspace/search/, which charges 1 credit per property returned.
- Handle a 402. If the balance cannot cover the whole set, nothing is charged, and the body carries credits_left and required.
What changes the result and the charge
Charging is all or nothing. A search that matches 1,200 properties costs 1,200 credits, according to our API docs. A balance that falls short returns a 402 and charges nothing.
Some filters only work on properties for sale. Days on market is one of them, so leave it out of a sold search and send from and to dates instead.
A rent filter narrows the set more than it looks. The monthly_rent_min filter drops every property with no rent estimate, so even a low floor removes properties.
Results also come with terms of use. Section 5.2 of our terms of service makes Internal Use the default tier for every account. Showing results to your customers or the public needs a Client Delivery or Redistribution tier named in your order.
Common listings API mistakes to avoid
- Running the search before the count: The search charges 1 credit per property returned. Preview first, since the count call never charges.
- Searching a whole state: A state-wide area times out, the count call included. Send 2 or more cities, counties or ZIP codes in one location array instead.
- Pairing sold with for-sale filters: Days on market works on properties for sale only. For past sales, set property_status to sold and filter by from and to dates.
- Reading a missing rent as zero: Rent filters drop properties that have no rent estimate. Run the count with and without the rent filter to see the number you lose.
Estimated values. Not investment advice. Data as of 2026-11-07.
Related reading: How do I turn a typed address into the right property record?.
Frequently asked questions
What does a listings API search cost?
Can a listings API search sold properties?
What filters does a listings API take?
Can I show listings API results publicly?
Can a listings API search a whole state?
Try the count call
Our API docs list every search filter with its type, and the credits each call costs.
- Homesage.ai API count calls and 1 search for single-family properties for sale in Tampa, Florida, pulled 2026-11-07.
- Homesage.ai API docs, search count and search, read 2026-11-07.
- Homesage.ai terms of service, sections 5.2 and 7.1, read 2026-11-07.