用 Python 把 Zillow 房源搜索接到 Zestimate:先留 zpid

发布于 2026年10月8日 · 更新于2026年10月16日

搜索卡片上已经有挂牌价、户型,往往还有 zestimate,于是很容易把「按城市搜房源」当成估价接口:扫一遍市场,把卡片上的数字写进估值表,晚上再跑同一条搜索当净值刷新。这个切法是错的。搜索返回的是库存快照——地址、挂牌价、卧室、照片、在架天数和一个 zpid。卡片上的数字方便排序,却不是定时刷新的点估价,更不是 HOA、车位、家电那张事实表。挂牌价和估价并排出现,并不等于二者可以互相替代。

正确链路是:先筛市场,留下 zpid,再取房产事实,最后才调 Zestimate。Zillow 房产数据 API 覆盖美国与加拿大的在售、出租与近期已售库存,但是非官方只读 JSON 服务,不是评估报告,也不是完整历史库。官方公开接口早已停用,本流程不负责「恢复官方 API」,也不提供爬虫、代理池或 Cookie。文档里洛杉矶示例曾在第 1 页返回 41 条房源,不代表今天同样有货、字段齐全或估价非空。

搜索结果不是估价

search 回答「这里挂着什么」。location 可以是城市、县、社区或邮编,再叠加价格、卧室、面积、HOA、home_status 这类门户筛选。search-by-coordinates 只是换了入口:lat、long 加可选英里直径,卡片结构相同。需要学区、水线或不规则社区轮廓时,再用 search-by-polygon(顶点按「经度 纬度」逗号分隔,末点不必重复首点)。三条都是发现层,都不是投资组合估值。卡片上的 zestimate、rentZestimate 只适合做短名单排序,不能当成「已经估过了」。

用户真正点开的房子,才走 property-details(resoFacts:户型拆分、家电、协会名称与费用、停车)。property-zestimate 才是点估价,输入仍是 zpid 或详情页 url,载荷刻意很小,适合对已持有的标识做定时刷新。表单、直邮名单或贷款预审表里只有街道地址时,用 property-by-address 跳过搜索拿同一张事实表——它同样不是估价接口。经纪人目录 agent-search 按城市翻页(每页约 15 条,带评分与近 12 个月销量),稳定标识是 encodedZuid,和房源 zpid 不是一回事,不要塞进这条估价流水线。

在控制台取你有权使用的平台 Key。Python 从服务端环境变量 OPENDATA_API_KEY 读取;示例 URL 里的 YOUR_API_KEY 只是占位符。不需要 Zillow 账号、Cookie 或会话。查询串带着 Key,生产请求放服务端,访问日志、异常堆栈和截图都要脱敏,不要把真实 Key 写进仓库或前端。打开本文、展开说明或复制代码不会发请求;你主动跑脚本才会消耗额度。

判断失败时分三层,不要合成一个布尔值:先看 HTTP 是否 2xx,再看网关 {code, message, data}(code 为 200 才是平台业务成功,额度不足或 Key 无效通常停在这一层),搜索载荷还有内层 status(OK 或 ERROR,无法识别的地点会给出明确的 Invalid location)。HTTP 200 不等于搜到了房,也不等于有估价。排查时只保留脱敏后的 code 与 message,不要把整段响应写进监控。

先筛市场,留下 zpid

文档示例地点是 Los Angeles, CA。home_status 在 FOR_SALE、FOR_RENT、RECENTLY_SOLD 之间切换。价格和卧室筛选不保证有匹配。先安装 requests,在服务器上注入环境变量再运行。

import os
import requests

BASE = "https://api.opendata-api.com/api/project/zillow"
API_KEY = os.environ["OPENDATA_API_KEY"]
PAGE_SIZE = 41
MAX_PAGES = 3


def call(operation, **params):
    try:
        response = requests.get(
            f"{BASE}/{operation}",
            params={**params, "key": API_KEY},
            timeout=30,
        )
    except requests.RequestException:
        raise RuntimeError("Request failed; use redacted diagnostics") from None
    if not response.ok:
        raise RuntimeError(f"HTTP {response.status_code}")
    gateway = response.json()
    if not isinstance(gateway, dict) or gateway.get("code") != 200:
        raise RuntimeError("Gateway business failure; inspect code/message safely")
    payload = gateway.get("data")
    if not isinstance(payload, dict):
        raise RuntimeError("Unexpected operation payload")
    if payload.get("status") == "ERROR":
        raise RuntimeError("Operation error; inspect message safely")
    return payload.get("data")


def search_market(location, max_pages=MAX_PAGES, **filters):
    listings = []
    for page in range(1, max_pages + 1):
        rows = call("search", location=location, page=page, **filters)
        if rows is None:
            break
        if not isinstance(rows, list):
            raise RuntimeError("Expected a listing array")
        listings.extend(rows)
        if len(rows) < PAGE_SIZE:
            break
    return listings


homes = search_market(
    "Los Angeles, CA",
    home_status="FOR_SALE",
    min_price=300000,
    max_price=850000,
    min_bedrooms=2,
    sort="NEWEST",
)
print(f"{len(homes)} listings collected")

zpid 保持字符串,不要转成整数或浮点——后面详情和估价都靠它拼接。卡片上的 price、currency、户型、面积、daysOnZillow、homeType、statusType、imgSrc、detailUrl 以及 streetAddress / city / state / zipcode 够做短名单。夜间盯新盘可以固定邮编加 sort=NEWEST,但每次轮询仍只是在收集标识,不是在刷新估值。不要给每一条都取详情。

半径搜索把同一辅助函数换成 search-by-coordinates,文档点位是圣莫尼卡 34.01822, -118.504744,直径默认 1.0 英里、范围大约 0.1–100,现货不保证。多边形搜索同样只产出卡片。这一阶段结束时手里应是去重后的 zpid 列表,不是估完的价。

房产事实之后才是 Zestimate

只充实用户点开的、进了核保表的、或夜间任务标记要刷新的房子。卡片里的示例 zpid 是 20171939,也可以贴详情页 url。

if homes:
    zpid = homes[0].get("zpid")
    details = call("property-details", zpid=zpid) or {}
    if not isinstance(details, dict):
        raise RuntimeError("Expected a property object")
    facts = details.get("resoFacts") or {}
    raw_estimate = call("property-zestimate", zpid=zpid)
    zestimate = (
        raw_estimate.get("zestimate")
        if isinstance(raw_estimate, dict)
        else raw_estimate
    )
    print({
        "zpid": zpid,
        "address": details.get("streetAddress"),
        "bedrooms": facts.get("bedrooms"),
        "bathrooms": facts.get("bathrooms"),
        "hoa_fee": facts.get("associationFee"),
        "list_price": details.get("price"),
        "zestimate": zestimate,
    })

字段随房源而异:有的协会费、停车、家电是空的,有的浴室会拆成全卫/半卫。空值保留,不要补零或编造建造年份。曾有一次核对:点查估价与同一 zpid 搜索卡片上的数字一致——那只说明两条操作当时对齐,不是鉴定结论,也不能保证隔夜仍相等。核保、报价或对外展示前仍要人工核对。

输入若是 1443 Bellevue Ave Los Angeles, CA 90026,用 property-by-address 直接取事实,适合名单逐条处理。之后若要 Zestimate,仍需响应里真实出现的 zpid 或详情 url,不要把地址解析当成估价,也不要补一个没有返回的 ID。租金侧优先读卡片上的 rentZestimate;售价刷新才走 property-zestimate。按请求计费:一页最多 41 条只算一次搜索,每条都取详情则不是。搜索用来发现,详情用来充实被点开的对象,估价用来刷新已持有的标识,三层不要打平。费率见定价。

空结果和翻页会出在哪

页码 1–100,每页最多 41 条。短页表示这个筛选条件下库存见底,不是接口坏了,下一页也不该再要。生产环境要限制 max_pages;翻满 100 页是预算选择,不是「这个城市搜全了」的证明。重叠筛选、半径和城市对打、或反复按 NEWEST 轮询时,按 zpid 去重,避免同一套房被充实两次。

三种「看起来像没数据」必须分开写分支。条件合理但没有匹配:HTTP 200、内层 OK、data: []——这是空市场,记下地点和筛选后停下,不要当成 Key 无效去重试。地点无法识别会返回明确的 Invalid location,不要偷偷换成另一座城市或默认洛杉矶。价格范围要合理;离谱下限(例如万亿美元级)可能打出临时 503 而不是空数组,应退避重试,不要把 503 解释成「没有房子」,更不要据此清空投资组合。

这些状态都还不是估价。搜索为空就没有可交接的 zpid,点查缺字段也不要把缺失估价当成 0 再去平均或画趋势。空数组、业务 ERROR、网关非 200、传输失败,四条路不要收成同一个 except。

把搜索当估价时最容易踩的坑

把 search 当成 property-zestimate。用卡片快照排序可以,把它当夜间净值不行。

给每条房源都调 property-details。41 张卡片仍是一次搜索;详情只留给被选中的房子。

丢掉 zpid,或把它转成浮点数,后面的事实和估价就对不上。

把空数组、ERROR 和 HTTP 503 收成同一种失败。无匹配、地点非法、筛选过激,分支不同。

看见 HTTP 200 就跳过网关 code。传输成功不是业务成功。

调完 property-by-address 就以为估完了。先事实,后 Zestimate,而且必须有真实 zpid 或详情 url。

把这篇文章当成一次已发出的查询。复制示例不会打到接口;带上你的 Key 运行才会。可从搜索、按地址查询、估价或项目页继续。