搜索美国在售、出租或已售住宅房源
查看 美国房产与房贷数据 API 的全部接口 →通过 POST /properties/v3/list 搜索住宅房源,可选择提交 JSON 请求体。文档列出的字段包括字符串 state_code、数组 status 和 type、对象 list_price、beds、baths 和 sort、布尔值 cats 和 dogs,以及整数 limit 和 offset;没有请求体字段被标为必填。一次返回 HTTP 200 的成功调用使用了 state_code="CA"、status=["for_sale"]、limit=3、offset=0 和 sort={"direction":"desc","field":"list_date"}。这仅验证了该组加利福尼亚州在售房源查询条件,不代表所有州、房源状态、住宅类型或筛选组合均已验证。现有证据尚未确定 list_price、beds 和 baths 的嵌套结构、其他排序值、数组枚举值及宠物筛选行为,不应从其他接口套用邮编请求体或筛选语法。 已观察到的响应包含 data.home_search.count、total 和 results。样本中 count=3,results 也包含三条房源,而 total=161224 表示更大范围内符合条件的总数,并非当前页行数。结果中已观察到 property_id、listing_id、status、list_price、list_date、last_sold_date 和 last_sold_price;location.address 下包含 line、city、postal_code、state_code、state、country 和 coordinate。description 对象包含 type、sub_type、beds、baths、baths_full 和 sqft。primary_photo、photo_count 以及部分面积和标记字段可能为 null。后续查询时应分别保留 property_id 与 listing_id,两者不可混用。 样本地址位于加利福尼亚州,挂牌日期包含 2026-10-22,但这不能证明房源覆盖完整、数据实时更新或每条记录的字段都非空。本接口没有另附响应示例,上述响应字段均来自这次成功调用。
API 功能
在线 API 演示
未找到可用的 API Key,请前往控制台创建后刷新本页。 控制台 →
/api/project/realty-in-us/properties-v3-list API 响应 (JSON)
{} curl -X POST 'https://api.opendata-api.com/api/project/realty-in-us/properties-v3-list?key=<API_KEY>'
查询结果
使用场景
- 使用 state_code=CA、status=["for_sale"] 和 list_date 降序,按已验证的请求组合搭建加州在售房源浏览页。
- 在少量房源卡片之外单独展示匹配总数,避免把当前页的三套住宅误当成全部房源。
- 根据返回的地址、挂牌价和住宅属性建立购房候选清单,并为选中的记录保留 property_id 与 listing_id。
- 实现 limit 与 offset 分页,兼容总数变化和照片字段为空的情况,而不把结果视为完整、静态的房源库。
- 根据文档中的宠物和住宅类型筛选字段规划租房表单,在启用相关控件前验证其结构和出租状态取值。
常见问题
哪组房源搜索条件已经成功测试?
一次返回 HTTP 200 的调用使用了 JSON 请求体:state_code 为 "CA"、status 为 ["for_sale"]、limit 为 3、offset 为 0,sort 为 {"direction":"desc","field":"list_date"}。该结果仅验证了这一组合,不代表所有筛选条件均已验证。
count 是否代表全部符合条件的房源数量?
不是。在已观察到的 data.home_search 响应中,count 为 3,results 包含三条房源,而 total 为 161224。应将 count 理解为该响应的当前页数量,total 理解为符合条件的总数。
可以用哪些字段识别并展示搜索结果?
已观察到的结果包含 property_id、listing_id、list_price、list_date、status、location.address,以及带有 beds、baths、sqft 等字段的 description 对象。应同时保留两类标识,房产 ID 与挂牌 ID 不可互换。部分值可能为 null,例如已检查记录中的 primary_photo。
这里是否明确规定了价格、卧室和卫浴间的区间筛选格式?
没有。list_price、beds 和 baths 都是可选对象,但现有资料未规定其嵌套键名和区间含义,成功请求也未使用这些字段。不要自行假定使用 min/max 键,也不要直接复制其他接口的请求体。
这个接口能用于查询出租和已售房源吗?
文档说明的用途包括在售、出租和已售房源搜索,但成功调用仅验证了 status 数组 ["for_sale"]。出租和已售状态的具体取值、宠物筛选及住宅类型取值仍需验证。
较新的挂牌日期是否证明这是完整的实时房源数据源?
不能。样本中出现了加州地址和 2026-10-22 的 list_date 值,但单个成功返回的页面不能证明市场覆盖完整、更新时效有保证,或翻页期间结果保持稳定。