Realtor 房源查询 API：用 Python 按美国邮编获取出租房源

发布于 2026年10月5日

做美国租房搜索、跨境搬家服务或房产研究时，常见需求是输入邮编，拿到可筛选的房源列表，再为选中的房屋补充描述和图片。Realtor 房源查询 API 提供结构化 JSON，减少手工整理地址、房源编号和挂牌信息的工作。

本文从已验证的纽约邮编 10001 出租搜索开始。这是非官方 Realtor.com 数据服务，不保证实时性、完整库存或房源仍可租，也不是正式估价或 MLS/IDX 授权数据源。

先选对接口

以下操作均使用 GET；完整参数见 Realtor API 文档。

操作	主要输入	用途与已验证范围
`property-search-rent`	`location`	按城市或邮编查出租广告，已验证 `10001`
`property-search-buy`	`location`	查询在售房源，已验证纽约城市示例
`property-search-sold`	`location`	查询已售记录，已验证奥斯汀示例
`property-auto-complete`	`location`	获取地点候选与搜索 ID，已验证纽约及无匹配情况
`property-v2-detail`	`query`	获取详情，已验证从在售搜索取得的房产 ID

价格、卧室、浴室等可选筛选有参数文档，但未逐项验证过滤效果。先检查样本是否符合条件，再把筛选能力承诺给用户。

用 curl 按邮编查询

在控制台取得自己有权使用的 API Key，确认账户可调用该项目。下面使用安全的公开地点示例，无需房产网站账号、会话或 Cookie。把占位符换成自己的 Key 后才运行；实际调用可能消耗额度，复制代码或阅读文档不会发起数据请求。

curl --get 'https://api.opendata-api.com/api/project/realtor/property-search-rent?key=YOUR_API_KEY' \
  --data-urlencode 'location=10001' \
  --data-urlencode 'sort=newest' \
  --data-urlencode 'page=1'

邮编按字符串保存，避免丢失前导零。城市可用类似 New York, NY 的形式；需要消歧时先查地点候选，不要自行拼造地点 ID。

Python 示例：同时检查 HTTP 与业务状态

需要 Python 3 和 requests。将自己的 Key 注入服务端环境变量 OPENDATA_API_KEY，不要写进网页、仓库或共享笔记。查询参数里的 Key 也可能进入访问日志，应做脱敏；不要直接记录完整请求 URL 或异常对象。

import json
import os

import requests

key = os.environ["OPENDATA_API_KEY"].strip()
if not key:
    raise RuntimeError("Missing API key")

url = "https://api.opendata-api.com/api/project/realtor/property-search-rent"
try:
    response = requests.get(
        url,
        params={"key": key, "location": "10001", "sort": "newest", "page": 1},
        timeout=30,
    )
except requests.RequestException:
    raise RuntimeError("Network request failed") from None

if not response.ok:
    raise RuntimeError(f"HTTP {response.status_code}")

envelope = response.json()
if not isinstance(envelope, dict) or str(envelope.get("code")) != "200":
    raise RuntimeError("Platform rejected request; inspect a redacted response")

payload = envelope.get("data")
if isinstance(payload, str):
    payload = json.loads(payload)
if not isinstance(payload, dict) or payload.get("status") is not True:
    raise RuntimeError("Search not successful; inspect a redacted message")

rows = payload.get("data")
if not isinstance(rows, list):
    raise RuntimeError("Unexpected listing schema")

print("Returned rows:", len(rows))
for row in rows:
    address = (row.get("location") or {}).get("address") or {}
    print(row.get("property_id"), address.get("postal_code"), row.get("list_price"))

平台外层包含 code/message/data；取出内层后，出租搜索还要检查 status/message/data。上面的代码不会把 HTTP 200 当作找到房源，也不会将缺失租金变成零。出现失败时，先检查脱敏后的业务消息；不要因“分页错误”就无限重试，已观察到无匹配的在售搜索也会返回这种消息。

返回字段与详情衔接

搜索结果的内层 data 是房源数组，不是详情对象。常用字段如下，均应允许缺失或为空。

字段	展示与存储建议
`property_id`、`listing_id`	分别保存房产身份与本次挂牌身份，保持字符串形式
`location.address`	展示地址并核对 `postal_code`
`list_price`、`list_price_min`、`list_price_max`	展示可用租金或区间，缺失时显示“价格未提供”
`description`	读取卧室、浴室等；出租记录可能使用最小值、最大值
`primary_photo.href`、`photos[].href`	可用图片链接不等于图片使用授权
`list_date`	挂牌日期，不是签约日期或数据采集时间

需要详情时，把当前搜索返回的 property_id 填入下面的占位符。详情验证来自在售样本，不能据此保证每条出租广告都可补全。

curl --get 'https://api.opendata-api.com/api/project/realtor/property-v2-detail?key=YOUR_API_KEY' \
  --data-urlencode 'query=PROPERTY_ID_FROM_SEARCH'

详情的内层 data 是对象，可包含 description.text、photos[].href、房屋属性、历史记录与 last_update_date。核对返回身份，并另存本次采集时间；房源可能变化或下架，不要把更新日期当作实时保证。

适合怎样的业务流程

搬家选房工具：按邮编发现候选，用户选择后再取详情，避免预加载所有房屋。
租金样本研究：保留采集时间、请求地区和空价格比例，仅对可用数值统计，不声称覆盖整个市场。
房产 CRM：保存匹配的房产与挂牌编号，人工核对状态，避免把同一房屋的不同挂牌混为一条。

常见问题

如何用 Python 按美国邮编查询出租房源？

调用 property-search-rent，将 ZIP Code 放入 location；先用本文的 10001、newest、第一页复现请求，再更换目标地区。代码仅展示请求与解析，不预设一定成功。

这是 Realtor.com 官方接口吗？

不是官方集成，也不保证与网站结果完全一致。适合房源发现与研究，交易前仍需核实可用性和信息时效。

拿到 property_id 后如何获取详情和图片？

优先用 property-v2-detail 的 query，检查业务状态后读取详情中的图片。独立的 property-photos 支持文档所列查询形式，但未实测，不能假定它的返回结构与详情相同。

城市 ID、property_id、listing_id 有什么区别？

地点补全返回的 id 用于搜索地区；property_id 标识房产；listing_id 标识挂牌。三者不能互换，需要成对编号的操作应使用同一搜索结果里的值。

为什么 pageSize=8 仍返回 30 条？

这是已观察到的行为，请求页大小不是可靠上限。使用实际数组长度，逐页核对并按房产、挂牌身份去重；不要假设 resultsPerPage、totalResultCount、totalPages 与行数完全一致。

价格或 last_sold_price 为空代表什么？

表示该字段未提供可用数值，不代表免费、零成交价或房源无效。保留空值；租金区间也可能全空，日期缺失则不能推算成交时间。

已售房源 newest 等于按成交日期排序吗？

不等于。应检查可用的 last_sold_date，对已取得样本本地排序；这仍不是完整成交历史，minSoldDate 的过滤效果也需验证。

挂牌售价、挂牌租金和成交价怎么区分？

结合 status 解读：在售的 list_price 是要价，出租的是广告租金，不是已签租约价格；已售记录另看 last_sold_price 和成交日期，不要混算市场指标。

能替代 MLS/IDX 授权或直接转载吗？

不能。获取数据不自动获得再分发权，图片和描述尤其需要单独确认授权、展示限制与署名要求。

经纪人、经纬度搜索和房贷工具都已实测吗？

没有。这些支持接口仍需逐项验证，地点补全也不能套用搜索的 status 校验：其成功结构仅含 data，空数组是有效无匹配结果。房贷计算还需核实利率单位、税费与保险周期，结果只作预算估算，不是报价或贷款预批。

下一步查看出租查询参考与详情参考。如需 Zillow、Redfin 等类似平台的数据接口，或私有化源码部署，可通过联系页面说明需求。