# Homes.com Search API Documentation
Homes.com Search API returns US homes for sale, for rent or sold as JSON. Pass a location text or a location_id from autocomplete. Filter by price, bedrooms, bathrooms, living area, year built, property type, status and open houses, sort, and page through the results. Every item has the price (with a rent range for apartments), address with coordinates, beds, baths, size, lot, year built, property type, status, photos and the listing agent. Item ids work in the listing route and agent_id works in the agent route.
Result cap. Homes.com returns at most the first 700 matches of a query. pagination.total is the full count and pagination.reachable_total is what you can page through. A page beyond that returns a 422 error and is never filled with other data. To go deeper, narrow the search with a bounding_box inside the area, or set facets=true to get listing counts per price band and split the search by price.
Rent. Apartment buildings show a rent range (rent_min to rent_max). A range can overlap the price filter band. Bathroom filters count full bathrooms: match them with baths_min and baths_max (baths adds half baths). Filters are never ignored: values that Homes.com does not honour are rejected with a 422 error. Failed requests are not billed.
- **Documentation:** [https://scrappa.co/docs/homes-com-api/homes_com_search](https://scrappa.co/docs/homes-com-api/homes_com_search)
- **API group:** Homes.com API
- **Endpoint:** `GET https://scrappa.co/api/homes-com/search`
## Authentication
Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.
## Parameters
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `location` | string | No | City, ZIP, neighborhood or address text. Send location or location_id. Example: Austin, TX. |
| `location_id` | string | No | Area id from the autocomplete route. Example: 2.f5xx96v6x6171. |
| `bounding_box` | string | No | north,east,south,west inside the area. Splits a large search. Example: 30.4,-97.7,30.3,-97.8. |
| `listing_type` | string | No | sale (default) or rent. |
| `status` | string | No | active (default) or sold. Sold needs listing_type sale. |
| `open_houses` | boolean | No | true to return only homes with an open house. |
| `min_price` | integer | No | Minimum price in USD (rent: per month). |
| `max_price` | integer | No | Maximum price in USD. |
| `min_beds` | integer | No | Minimum bedrooms. |
| `max_beds` | integer | No | Maximum bedrooms. |
| `min_baths` | integer | No | Minimum full bathrooms (a half bath does not count). |
| `max_baths` | integer | No | Maximum full bathrooms (a half bath does not count). |
| `min_sqft` | integer | No | Minimum living area in square feet. |
| `max_sqft` | integer | No | Maximum living area in square feet. |
| `min_year_built` | integer | No | Earliest year built. |
| `max_year_built` | integer | No | Latest year built. |
| `property_type` | string | No | Comma separated: house, townhouse, condo, multifamily. |
| `sort` | string | No | recommended (default), price_asc, price_desc, newest, beds_desc, sqft_desc or baths_desc. Rent: recommended or rent_asc. |
| `page` | integer | No | One-based page number. Default 1. |
| `per_page` | integer | No | Results per page, 1 to 25. Default 25. |
| `facets` | boolean | No | true to add listing counts per price band (one more lookup). |
## Example response
```json
{
"data": {
"items": [
{
"id": "gc95tmcstsspt",
"url": "https://www.homes.com/property/6413-jennings-dr-austin-tx/gc95tmcstsspt/",
"beds": 3,
"sqft": 1297,
"agent": {
"name": "Hiran Marin",
"phone": "(512) 413-4663",
"agency": "Monumental Realty",
"agent_id": "y9800qv",
"photo_url": null,
"agency_logo_url": null
},
"baths": 2,
"price": {
"label": "$300,000",
"value": 300000,
"currency": "USD"
},
"badges": [],
"photos": [
{
"url": "https://images.homes.com/listings/111/8452416515-295566732/6413-jennings-dr-austin-tx-primaryphoto.jpg",
"width": 1024,
"height": 768,
"caption": null
},
{
"url": "https://images.homes.com/listings/116/5552416515-295566732/6413-jennings-dr-austin-tx-buildingphoto-2.jpg?t=p",
"width": 768,
"height": 1024,
"caption": null
}
],
"status": "active",
"address": {
"city": "Austin",
"full": "6413 Jennings Dr, Austin, TX 78727",
"unit": null,
"state": "TX",
"street": "6413 Jennings Dr",
"building": null,
"coordinates": {
"latitude": 30.439204,
"longitude": -97.752399
},
"postal_code": "78727"
},
"builder": null,
"beds_max": 3,
"beds_min": 3,
"lot_sqft": null,
"rent_max": null,
"rent_min": null,
"sqft_max": 1297,
"sqft_min": 1297,
"baths_max": 2,
"baths_min": 2,
"community": null,
"list_date": "2026-10-09T00:00:00+00:00",
"lot_acres": null,
"photo_url": "https://images.homes.com/listings/111/8452416515-295566732/6413-jennings-dr-austin-tx-primaryphoto.jpg",
"sold_date": null,
"beds_label": "3 Beds",
"highlights": [],
"listing_id": "e9yrn03ft4mwl",
"year_built": 1984,
"baths_label": "2 Baths",
"description": "A great home in a wonderful area.",
"open_houses": [],
"units_count": null,
"listing_type": "sale",
"property_type": {
"code": 1,
"slug": "house",
"label": "House"
},
"days_on_market": null,
"original_price": {
"label": null,
"value": 300000,
"currency": "USD"
},
"price_per_sqft": 231,
"property_manager": null,
"available_units_count": null
}
],
"pagination": {
"page": 1,
"total": 1709,
"per_page": 25,
"total_pages": 28,
"has_next_page": true,
"reachable_total": 700
},
"location_id": "2.f5xx96v6x6171",
"applied_filters": {
"sort": "price_asc",
"min_beds": 3,
"listing_type": "sale"
}
},
"meta": {
"billable": true,
"endpoint_family": "search"
},
"success": true
}
```
## Errors
| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | A required parameter or a range is invalid, or the page is beyond the first 700 results. This response is not billable. |
| 503 | Upstream Unavailable | Homes.com could not be reached or returned data that does not match the request. This response is not billable and is retryable. |
## More Scrappa resources
- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)