Zillow 房价与租金指数 API：区域 ID、空字段与统计日期

先看一个字段：data.region.id 是 null。同一份西雅图市场响应里，ZHVI 却约为 822,572.43，ZORI 约为 2,226.62，两项指数还有历史记录。数字齐全不代表区域身份也已确认，更不代表整份响应都属于同一个统计月。

这篇指南围绕 Zillow 房产与市场数据 API 的已保存样本排查这类误读，不把城市指数改写成单套房产估价教程。

有房价、有租金，但 region 里的字段全为空

样本内层 data.region 原样如下。这不是没有返回市场数据，而是返回的区域身份字段没有值。

{
  "id": null,
  "name": null,
  "type": null,
  "parent_state": null,
  "parent_county": null
}

排查时依次看 HTTP 状态、外层网关的 code/message/data 业务结果，再看内层服务的 success 和实际数据。HTTP 200 或 success: true 都不能证明每个字段完整。这里应保留“区域身份待确认”，不能把 null 改成零，也不能为了让报表好看而补上 Seattle。

空字段还不等于空数组：样本的 forecast 是空数组，只说明没有返回预测记录，不能解释为未来涨幅为零。

查询的城市不等于响应已确认的区域

第一次只读请求使用已验证的地点补全输入：query=Seattle, WA、limit=3。以下代码均为静态示例；打开页面、切换端点、展开字段或复制示例不会发送数据请求。只有替换 YOUR_API_KEY 为你有权使用的平台密钥并主动运行，才会发出请求、消耗额度。真实密钥不要放进公开代码、浏览器页面或日志；无需额外 Cookie、Token 或会话。

curl --get 'https://api.opendata-api.com/api/project/zillow-real-estate/autocomplete-location?key=YOUR_API_KEY' \
  --data-urlencode 'query=Seattle, WA' \
  --data-urlencode 'limit=3'

已保存结果包含 Seattle, WA（city，region_id=16037）、West Seattle（flex_region）和 Capitol Hill（neighborhood）。必须让使用者核对并选择，不能自动取第一项；这些候选也不等于都会区或邮编区域。样本经纬度同样为空，地点补全不能当作保证成功的地理编码。

确认选择 Seattle 城市后，可使用已验证的地点文字查询市场：

curl --get 'https://api.opendata-api.com/api/project/zillow-real-estate/get-market-analytics?key=YOUR_API_KEY' \
  --data-urlencode 'location=Seattle, WA'

get-market-analytics 支持 location 或 region_id，应有明确的区域输入。但已验证的请求用的是地点文字，没有证据表明改传 region_id 能修复空字段，也没有验证两者同时传入时如何处理。保存所选名称、类型与 ID，是记录查询意图，不是为响应补发一张区域证明。

ZHVI、ZORI、挂牌价和单套房租金不能混用

home_values.zhvi 是区域房屋价值指标，不是成交中位价，更不是某套挂牌房的售价。rentals.zori 是区域租金指标，不是某套公寓的报价、签约租金或租金估值。用二者描述城市市场时，应连同区域口径和日期展示，不能直接据此计算一套住宅的投资收益。

成交中位价在 sales.median_sale_price，挂牌中位价在 listings.median_list_price。样本分别约为 848,333.33 和 724,666.67；它们与 ZHVI 不同，并不自动意味着数据出错，因为衡量对象、样本和统计期间并不相同。也不能用这两个汇总值相除，冒充单套房的成交折扣。

9 月指数与 8 月成交数据要分别标注日期

这份样本的 zhvi_date、zori_date 都是 2026-09-30，而 median_sale_price_date 是 2026-08-31。挂牌指标的 listings_date 则是 2026-09-30。因此可以写“9 月房价与租金指数，另附 8 月成交中位价”，不能统称为“9 月成交与租金数据”。

采集时间只说明应用何时拿到响应，不能覆盖这些统计日期。后续重抓也不意味着每个指标都已更新；比较涨跌前，要先核对指标名称、区域口径和报告月份。

样本的 ZHVI、ZORI 历史各有 100 条，条目包含 date/value/change_pct，但这不是固定长度或永久历史覆盖承诺。按记录日期排序，保留缺失的变化值，不要把 change_pct: null 当成零增长，也不要凭数组位置对齐两条序列。

按指标、统计日期和区域来源保存记录

先完成上述诊断，再做规范化。下面的 market 指已检查各层状态后的内层 {success, data, meta} 对象。代码只处理本地对象，不发送请求；输出字段是应用自己的存储结构，不是新增接口参数或响应字段。

def normalize(market, requested_geography, retrieved_at):
    data = market["data"]
    metrics = (
        ("home_values", "zhvi", "zhvi_date"),
        ("rentals", "zori", "zori_date"),
        ("sales", "median_sale_price", "median_sale_price_date"),
        ("listings", "median_list_price", "listings_date"),
    )
    rows = []
    for section, value_key, date_key in metrics:
        block = data.get(section) or {}
        rows.append({
            "metric": value_key,
            "value": block.get(value_key),
            "reporting_date": block.get(date_key),
            "requested_geography": dict(requested_geography),
            "returned_region": data.get("region"),
            "retrieved_at": retrieved_at,
        })
    return rows


requested_geography = {
    "location": "Seattle, WA",
    "selected_region_id": 16037,
    "selected_region_type": "city",
    "selected_display": "Seattle, WA",
}

这里的选择记录以人工确认 Seattle 为前提，不能由候选列表的第一项自动生成。调用函数时，另传实际获取时间；返回区域仍保留原始空字段，日期缺失时仍为空，不回填当前日期。这样查询来源、响应区域和获取时间可以分别审计，换城市重跑时也不会误沿用旧标签。

样本还有九个邻区条目，带各自名称和 ID；这些信息不能回填主区域，也不能在没有日期的情况下把主指数月份套给邻区。需要比较时，应逐项确认区域层级与日期是否可比。

房贷利率没有观测日期，就不能称为今日最新

get-mortgage-rates 的已保存样本返回 rate=7.23、apr=7.238。条件是 state=US、program=fixed_30、loan_type=conventional、credit_score=very_high，不是西雅图专属报价。利率与 APR 应分别保留，融资假设和返回的贷款分组也要随记录保存。

关键限制是没有利率观测日期。即使刚刚获取，也只能标注“本次获取的参考值，观测日期未知”，不能称为“今日最新利率”。它不代表个性化贷款方案、锁息或授信批准，更不能因为旁边有 9 月房价指数，就给利率补上同一日期。

城市市场快照不能替代单套房产尽调

这份快照支持观察区域趋势，却不能证明某套房子的合理买价、可出租金额、实际成交条件或贷款可得性。区域身份为空、指标月份不同、预测缺失，都是需要对读者保留的边界，不是清洗时应隐藏的噪声。

对外发布摘要时，把“请求的地区”和“响应确认的地区”分开，把统计日期贴在每项指标旁；单套房决策仍需核实房产事实、成交依据与实际融资条款。独立数据接口的汇总结果不是官方评估报告，也不是完整市场记录。