用 Python 调用 Zillow 房源搜索 API：在售房源、详情与估价

做海外置业网站、投资筛选工具或估值研究时，常见链路是：按地区搜房源、为看中的房屋取详情、再定期刷新估价。Zillow 官方接口早已停止开放，本项目的 Zillow 房产数据 API 以结构化 JSON 提供美国与加拿大的实时房源、房产事实、Zestimate 估价与经纪人目录，是实用的替代方案——无需维护爬虫、无需担心封 IP。

这是非官方数据服务：字段完整度随房源而异，交易决策前仍需人工核实。

先选对接口

所有操作均为 GET；完整参数见 Zillow API 文档。

操作	主要输入	用途
search	location	按城市、邮编或社区搜索在售/出租/已售房源，已验证洛杉矶示例
search-by-coordinates	lat、long、diameter	以经纬度为中心做半径搜索（0.1–100 英里）
search-by-polygon	polygon	在自定义多边形边界内搜索（学区、社区轮廓）
property-details	zpid 或 url	按房源 ID 或详情页 URL 取完整房产事实
property-by-address	address	按纯文本街道地址直接解析房产事实
property-zestimate	zpid 或 url	取当前 Zestimate 估价，响应极小
agent-search	location（如 new-york-ny）	按城市检索经纪人目录，含评分与销量统计

用 curl 搜索在售房源

在控制台复制自己账户的 API Key。复制代码或阅读文档不会发起数据请求；换上真实 Key 后再运行，实际调用会消耗额度。

curl --get 'https://api.opendata-api.com/api/project/zillow/search?key=YOUR_API_KEY' \
  --data-urlencode 'location=Los Angeles, CA' \
  --data-urlencode 'home_status=FOR_SALE' \
  --data-urlencode 'sort=NEWEST' \
  --data-urlencode 'page=1'

home_status 取 FOR_SALE、FOR_RENT、RECENTLY_SOLD 三种库存；每页最多 41 条，页码范围 1–100。价格、卧室、浴室、面积、HOA 费等筛选参数与门户搜索表单对齐。

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

需要 Python 3 与 requests。Key 通过服务端环境变量 OPENDATA_API_KEY 注入，不要写进仓库或前端；查询串里的 Key 可能进入访问日志，日志需脱敏。

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/zillow/search"
try:
    response = requests.get(
        url,
        params={"key": key, "location": "Los Angeles, CA",
                "home_status": "FOR_SALE", "page": 1},
        timeout=30,
    )
except requests.RequestException:
    raise RuntimeError("Network request failed") from None

# HTTP layer: non-2xx means transport or gateway failure
if not response.ok:
    raise RuntimeError(f"HTTP {response.status_code}")

envelope = response.json()

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

payload = envelope.get("data")

# Business layer: inner status is "OK" or "ERROR"
if not isinstance(payload, dict) or payload.get("status") != "OK":
    raise RuntimeError("Search failed; 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:
    print(row.get("zpid"), row.get("address"), row.get("price"), row.get("zestimate"))

注意三层分别判断：HTTP 非 2xx 是网关或传输失败；外层 code 非 200 是平台拒绝（如 Key 无效、额度不足）；内层 status 为 ERROR 是业务失败。无法识别的地点会返回精确的 Invalid location 错误；而条件合理但无匹配时返回 HTTP 200 且 data 为空数组——空结果不是故障，流水线应据此区分。价格范围要保持合理，离谱的输入（如万亿美元级下限）可能触发临时 503，应退避重试而非判死。

返回字段与后续衔接

搜索结果的内层 data 是房源卡片数组，常用字段均应允许缺失或为空。

字段	说明
zpid	房源 ID，保持字符串形式，是详情与估价接口的输入
address、streetAddress、city、state、zipcode	地址组件
price、currency	挂牌价（在售）或广告租金（出租）
zestimate、rentZestimate	当前售价估价与租金估价快照
bedrooms、bathrooms、livingArea、lotAreaValue	户型与面积
daysOnZillow、homeType、statusType、latitude、longitude、imgSrc、detailUrl	在架天数、房型、状态、坐标、图片与详情页

搜索是发现层，详情是充实层：用户点开某套房时，再取深度数据。

# Full facts by ID (or pass url= a listing-page URL)
curl --get 'https://api.opendata-api.com/api/project/zillow/property-details?key=YOUR_API_KEY' \
  --data-urlencode 'zpid=ZPID_FROM_SEARCH'

# Same fact sheet straight from a street address
curl --get 'https://api.opendata-api.com/api/project/zillow/property-by-address?key=YOUR_API_KEY' \
  --data-urlencode 'address=1443 Bellevue Ave Los Angeles, CA 90026'

# Lightweight value refresh for a portfolio
curl --get 'https://api.opendata-api.com/api/project/zillow/property-zestimate?key=YOUR_API_KEY' \
  --data-urlencode 'zpid=ZPID_FROM_SEARCH'

详情内层 data 含 price、地址组件与 resoFacts 块（卧室、浴室细分、家电、HOA 名称与费用、停车位、建造年份等）；字段填充率随房源而异，保留空值，不要自行编造。估价接口只回一个数值，已验证与搜索卡片上的 zestimate 一致，适合每晚批量刷新投资组合。

使用场景

• 海外置业平台：城市/邮编搜索加筛选，用户点开后取详情，按 zpid 存候选清单。
• 投资deal筛选：每晚按目标邮编轮询 NEWEST 排序，新挂牌即推送；for_sale_is_foreclosure 等参数可盯法拍与止赎库存。
• 估值与 CMA：对持仓 zpid 列表定时调估价接口，比对挂牌价与估价的偏离度。
• 名单增强：直邮或贷款预审场景把地址列表逐条解析为结构化房产记录。
• 经纪人分析：按城市翻页经纪人目录（每页 15 条，含 total_agents），用评分、评论数与近 12 个月销量排名；保存 encodedZuid 作为稳定标识。

常见问题

Zillow 官方 API 还能用吗？有什么替代方案？

官方接口已停止开放。本项目提供覆盖美国与加拿大的实时房源、详情、估价与经纪人数据，JSON 直连，是面向开发者的替代方案，但不属于官方集成。

如何用 Python 获取房源数据？

用 requests 调 search，参考上文示例；先复现洛杉矶示例，再换目标地区，并按三层分别判断失败原因。

有没有按地址查询美国房产信息的接口？

property-by-address 一次 GET 把街道地址解析为价格、户型、HOA、建造年份等事实，适合表单、名单、表格逐条处理。

如何批量获取 Zestimate 估价？

先用搜索或地址解析取得 zpid 列表，再对每个 zpid 调 property-zestimate；单次响应只含估值，成本最低。租金估价可直接读搜索卡片的 rentZestimate。

爬虫被封怎么办？

这正是本接口解决的问题：按请求计费，无需维护爬虫、代理池与解析器。

如何用经纬度搜索附近房源？

search-by-coordinates 传 lat、long 与 diameter（英里），筛选参数与城市搜索一致；需要不规则边界时用 search-by-polygon，顶点按「经度 纬度」逗号分隔，末点不必重复首点。

房产数据接口怎么收费？

按请求计费，单次调用费用见定价；建议搜索发现与详情充实分层调用，避免为每张卡片都取详情。

如何获取经纪人的挂牌与成交数据？

agent-search 返回评分、评论数与格式化销量统计；经纪人级挂牌等更多维度请通过联系页面说明需求。

支持加拿大房源吗？

支持，搜索与详情覆盖美国与加拿大。

下一步查看搜索参考、按地址查询参考与估价参考。如需 Redfin、Realtor.com、Trulia 等类似平台的数据接口，或私有化源码部署，可通过联系页面说明需求。