搜索美国在售、出租或已售住宅房源

查看 美国房产与房贷数据 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 功能

按州与挂牌状态检索房源 成功调用已验证 state_code 为 CA、status 为 ["for_sale"] 的组合。文档用途涵盖在售、出租和已售查询,但其他状态的具体取值尚未验证。
分别读取当前页数量与匹配总数 已观察到的 data.home_search 结构以 count 和 results 表示当前页结果,以 total 表示符合条件的总数;样本从 161224 条匹配中返回了三条。
按挂牌日期排序并使用偏移分页 已验证的请求设置 limit=3、offset=0,并按 list_date 降序排列,可获取较小的第一页;这不代表分页快照固定或单页数量不受限制。
同时保留房产与挂牌两类标识 已观察到的房源记录同时包含 property_id 和 listing_id,以及挂牌价、挂牌日期、地址和住宅属性,便于先筛选记录,再发起详情查询。
提供多种类型的可选筛选字段 请求体支持对象类型的价格、卧室和卫浴间筛选、数组类型的住宅类型筛选,以及布尔类型的猫狗政策筛选;详细结构与未经测试的行为仍需验证。

在线 API 演示

POST /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>'
📢
需要帮助?
如遇接口异常,或需要其他接口需求,可联系我们
联系我们

使用场景

常见问题

哪组房源搜索条件已经成功测试?

一次返回 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 值,但单个成功返回的页面不能证明市场覆盖完整、更新时效有保证,或翻页期间结果保持稳定。

相关接口

相关指南

查看订阅方案 →