Zillow 美国房产与市场数据 API

在 location 中填写城市、邮编或地址，再按房源状态、价格、卧室、卫浴、房型、设施及可负担性筛选。status 支持 for_sale、for_rent、sold；result_type 支持 list、map。page 从 1 开始，文档上限为 1000；也可使用 cursor 续查。同一搜索翻页时保持筛选条件不变，并限制总请求数。 已保存的 Seattle 列表响应含 success、data.results、data.total_count，另有与 data 并列的 pagination，内含 result_count、current_page、has_next、next_cursor。房源字段包括 zpid、地址、城市、州、邮编、价格、卧室、卫浴、面积、房型、状态、房价及租金估值、经纬度与图片和详情链接。page_size=3 时返回了 3 条；字段与估值可能为空，样本还出现负数 days_on_zillow，不应当作可靠的挂牌天数。 无法识别的地点曾返回 HTTP 200，但 success:false、error.code:INVALID_LOCATION、error.param:location，且无房产数据。应与有效地点没有符合条件的房源区分。仅所述列表首屏已实测，全部筛选组合、地图输出及后续分页未逐一验证。

query 至少输入 2 个字符；limit 可选，默认 10。此只读查询用于在房源或市场研究前展示地点选择器，不应自动采用第一条文本匹配。 已保存的 Seattle、limit=3 请求返回 success:true 和 data.suggestions 中的 3 条建议。每条含 type、region_type、display、region_id、sub_type、city、state、county、latitude、longitude，响应另有 meta。Seattle, WA 为 city，region_id 为 16037；West Seattle 为 flex_region，Capitol Hill 为 neighborhood，建议中的两项坐标均为空。请把所选区域类型、显示名称与 ID 保存为请求来源；后续市场响应仍可能区域身份为空，地点补全并不证明市场数据已确认该地区。

用十进制度数填写 north、south、east、west 四条边界。虽然模式分别将字段标为可选，要表达明确的矩形范围仍需四者齐全；此接口不是中心经纬度加半径查询。zoom 默认 13，可叠加状态、价格、卧室、卫浴、房型、设施和可负担性筛选，并用 page 或 cursor 续查。 文档描述为返回指定边界内的房源搜索集合，result_type 选择 list 或 map。此路由没有已保存的实测响应，精确集合字段、筛选执行及续查行为均未验证。导入前先检查业务结果和资源身份；相邻或重叠范围可在客户端按实际返回的房产 ID 去重，不能把范围内的结果当成全部住房清单。

url 必须为完整 Zillow 链接。文档支持搜索链接、含 zpid 的房产链接及含楼宇标识的楼宇链接，分别返回相应资源；它不是统一的房源列表响应。 cursor 仅用于搜索链接续查。include 仅适用于房产链接，使用逗号分隔的 photos、similar、nearby、schools、history、agent、affordability 或 zestimate_history；这些不是搜索筛选条件，也不是楼宇附件。此链接路由未实测，解析前应检查资源类型与身份，不能保证所有链接可解析或附件都有数据。

body 为 JSON 对象，包含 1–10 个查询对象组成的 searches 数组。每项保存各自的 location 和所支持的筛选条件，例如 status、page、page_size。应用端应保留每组原始查询与处理结果的关联。 文档允许 HTTP 200 下部分失败，每组搜索各有成功或错误结果。此批量路由未实测，精确响应键和返回顺序尚未观察。不能将 HTTP 成功视为所有搜索成功，也不能把失败与有效但无结果的区域混在一起。先检查原因，再在客户端请求预算内选择性重试。

传入从搜索结果或其他可信公开房产记录取得的数字 zpid。不传 include 的实测响应包含 success:true，data 内有 zpid、status、home_type、year_built、price、currency、date_posted、address、location、financials、facts、listing、features、parking、rooms、flags、description、photo_count 及周边地点集合，另有 meta。Seattle 记录与搜索所选房产的标识、地址和挂牌价一致。 financials 中观察到 zestimate、rent_zestimate、last_sold_price；facts 中有 beds、baths、sqft、lot_sqft。HOA、税费等部分字段为空。可选 include 以逗号分隔 photos、schools、similar、nearby、history、agent、affordability；这些附件组合未验证。返回文字、图片和估值不保证房屋状况、使用权或价值。 重要边界：特意构造的不存在 zpid 也曾返回 HTTP 200、success:true，但 data.zpid:null、默认 OFF_MARKET，地址、价格、坐标为空且集合为空。接纳为真实房产前，必须确认返回 zpid 非空且与请求匹配，并有可用地址和事实字段。仅 success:true 或 OFF_MARKET 不能证明存在。

address 接受完整或部分美国地址，文档描述为先解析房产再返回详情，无需预先提供 zpid。include 支持 photos、schools、similar、nearby、history、agent、affordability。需要区分楼宇、单元或同名街道时，优先提供完整地址。 地址路由未实测，不能承诺地址匹配精度、精确响应结构或未找到时的行为。保留原始输入，并在接纳前比较返回房产的身份和地址。另一个按 zpid 查询的接口曾对不存在 ID 返回空壳成功记录，因此地址导入也不应只依赖 success:true，更不能静默将歧义单元关联到另一套房产。

body 为 JSON 对象，必填 zpids 数组含 1–50 个房产 ID。可选 include 在此处是数组，不是单套房查询所用的逗号分隔字符串。文档值为 photos、schools、similar、nearby、history、agent、affordability、zestimate_history。 文档描述每套房产独立返回成功或错误，整体可在 HTTP 200 下部分失败。没有已保存的批量房产响应，精确单项键、顺序与附件结构尚未验证。请保留提交 ID 并逐项检查结果身份，不能将 HTTP 200 当成全组合成功。单套房路由的空壳成功行为提示应核对身份，但并不能证明此批量接口用同样方式报告不存在记录。

传入已知数字 zpid，查询文档所述的设施专项视图，包括室内、室外、社区设施、停车及重点标记。适合对比房屋配套，不必以获取完整房产页面为目标。 专项设施路由未实测。另一个完整房产响应虽有 features、parking、flags 分区，且含数组、布尔值与 null，但不能据此确定本接口字段。先检查实际结果再写解析器；缺失属性保留为未知，明确 false 与无数据分开。重要无障碍、装修或安全信息应另做尽调。

用已知 zpid 请求文档描述的照片专项资源，即单套房的图片 URL 与数量。适合房源轮播图或图片可用性检查，不是房屋事实查询。 照片专项响应未实测，因此不承诺精确列表和计数字段。搜索结果虽有图片链接，完整房产实测虽有 photo_count，也不能确定本接口模式。链接与图片可能变动。获取 URL 不代表拥有图片、再分发、模型训练或商业展示权；下载或展示前应先核实允许用途。

传入已知 zpid，查询文档描述的社区名称及附近城市、社区、邮编。输入仍是房产 ID，不是城市区域 ID，也不是自由文本社区名。 此专项路由未实测。完整房产响应虽出现附近城市、社区和邮编集合，部分条目含 name 与可为空的 url，但不能确定本接口精确结构。邻近信息适合提示后续研究，不足以证明行政归属、人口特征相似或市场统计可互换。

用已知 zpid 请求文档所述学校资源，包括学校记录及可用的评分、学段与距离摘要。这些是搬迁研究输入，不是权威入学决定。 没有已保存的学校接口实测响应，精确字段、评分来源、覆盖和划片准确度均未验证。学校边界、招生规则与资格可能独立于房源信息变化。缺失评分保留为未知；向买家或租客提供建议前，须向相关学区直接确认入学、项目可用性及边界。

building_key 接受文档所述字母数字楼宇标识，也可在同一路径字段传 latitude,longitude 坐标对。楼宇标识用于多单元建筑，不是房产 zpid。文档描述返回楼名、地址、设施、属性、评分与可用单元。 可选 include 用逗号分隔 photos、schools、comps、floor_plans、nearby、market、reviews。此路由没有已保存的实测响应，单元结构、附件与可用性尚未验证。不能把可用单元集合当成完整出租名册，也不能保证每个单元可租；楼宇记录应与单套房产 ID 分开。

用已知 zpid 请求文档描述的价格历史资源，包括带日期的价格事件及最低、最高与降价摘要。它用于研究单套房报告价格的变化，不代表区域房价指数走势。 此接口未实测，精确事件键、事件类型、历史跨度与摘要算法尚未观察。保留每条记录自带日期及事件含义，挂牌价调整不自动等于已成交。不要补造缺失事件、把时间空档当作没有活动，或承诺完整价格档案。

输入已知房产 zpid，请求文档所述的税务历史记录及最近、最低、最高摘要。用于持有成本尽调；若响应提供税额、评估价值和年份，应分别保存。 没有已保存的税务历史实测响应，精确记录键、司法辖区覆盖、更新时间与摘要算法均未验证。另一个完整房产实测中的税费字段为空，不能补成零。历史税额无法预测购买、重估、减免变化或地方税率调整后的实际负担；重要金额需向当地税务主管机构核实。

用已知 zpid 查询文档所述的业主协会 HOA 信息及月度、年度成本摘要。这是单套房的费用资源，不是社区平均费用估计。 独立 HOA 路由未实测，精确字段、付款周期解释与覆盖尚未确认。完整房产实测中的 hoa:null 不能证明没有协会或费用。缺失费用保留为未知，展示已给出的计费周期；买房前向协会核实当前会费、特别征费、包含服务及其他义务。

传入已知 zpid，请求文档所述的单套房租金估值；有数据时提供结合来源的综合估值与置信标签。单套房租金估值不等于反映区域租赁条件的 ZORI，两者都不是签约租金。 此接口未实测。文档将 Zillow 租金估值列为候选来源，并描述可选 HUD 租金基准；置信标签反映来源差异：差异在 10% 内为 high、25% 内或只有单一来源为 medium，其他为 low。实际来源覆盖和字段未验证，不应假设所有来源均参与，也不能虚构额外邮编租金中位估值。保留缺失来源及估值，不人为拼出综合数值；投资测算前需复核本地租赁可比案例。

用已知 zpid 请求文档所述的房产可负担性模型月度费用拆分。此路由只公开房产 ID 参数，不接受自定义首付、信用评分、利率或贷款方报价。 没有已保存的月供估算实测响应，精确分项键、模型假设和完整性未验证。保留实际给出的假设及不可用分项，并明确标为模型估算。它与房贷利率接口不同，不代表获批、资格认定、锁定利率或贷款方实际月供。

提供 location 文本或 region_id。虽然模式分别标为可选，明确的区域查询至少要有一个；可先用地点补全复核区域类型，将所选查询地区与响应实际确认的地区分开。两项同时提交的行为未验证。 已保存的 Seattle 响应含 success:true，data 内有 region、home_values、rentals、sales、listings、neighbors，另有 meta。home_values 含 zhvi、zhvi_yoy、zhvi_date、zhvi_history 及空 forecast 数组；rentals 含 zori、zori_date、zori_history、national_zori、national_zori_history。两个区域指数历史各有 100 条 date/value/change_pct 记录。sales 含 median_sale_price、median_sale_price_date、median_sale_to_list、pct_sold_above_list、pct_sold_below_list、sales_history。listings 含 median_list_price、new_listings、for_sale_inventory、median_days_to_pending、listings_date、listings_history。9 个邻近区域条目提供 region_id、name、zhvi 和相对 url；数量与覆盖可能变化。 尽管指标有值，data.region 内每个字段都为 null。请求城市或选定区域 ID 只能作为请求来源，不能补成响应已确认的地名；尚未证实发送 region_id 能修复空对象。样本 ZHVI/ZORI 日期为 2026-09-30，而成交价中位数为 2026-08-31。按指标保存各自统计日期，不用抓取时间或单一月份覆盖全部数值。ZHVI 不是成交价中位数，ZORI 不是单套房租金，区域快照也不是房产评估。

通过 state、program、loan_type、credit_score 请求参考房贷利率。文档默认值为 US、fixed_30、conventional、very_high。state 接受两位美国州代码或 US；其他方案与档位值在已保存证据中没有完整枚举或验证。 默认参数的实测返回 success:true，data.rate、data.apr 为数字，并有 program、loan_type、credit_score、state、loan_amount_bucket、loan_to_value_bucket 等回显或背景字段，另有 meta。比较观察值时，将这些假设与数值一起存储。响应没有利率观测日期，抓取时间不能证明利率属于今天或是最新。仅作参考研究，不是个性化贷款要约、锁息或信用审批。

用 program、loan_type、credit_score 请求文档所述的滚动近 30 天房贷利率历史，默认 fixed_30、conventional、very_high。与单次利率接口不同，此历史路由没有 state，也没有任意起止日期参数。 未保存历史接口实测响应，精确记录键、观测时间戳、缺失日期行为与点数均未验证。对比时保持贷款方案和档位一致，保留实际给出的日期；不承诺多年档案，也不为未观察日期补造利率。若自行积累更长历史，应标为自有采集观察记录。

提供已知公开经纪人的 screen_name，而不是显示姓名、电话或房产 ID。文档中的资料资源包含可用评分、团队、服务区域、执照、成交统计及社交链接。用户名应来自公开资料或有权使用的目录；此项目不提供经纪人搜索。 资料接口未实测，精确键和字段完整性尚未确认。未纳入项目的经纪人发现路由在已保存测试中缺少宣传的业绩指标，这不能证明本资料路由的统计有效。缺失执照与统计应保留为未知；转介或商业决策前，需独立核实专业资格。

提供公开 screen_name，选择 type:sale、rent、sold。page 从 1 开始，默认 1。include_team 默认 true，文档仅描述其影响待售与出租库存；已售房源忽略该字段。 此路由未实测。文档称返回经纪人房源，但精确集合、分页及房源字段尚未观察。每次观察保留 type 和团队范围，不将活跃库存与已成交活动混合，也不能用列出的房源推断经纪人成交总业绩。

提供 screen_name，并用 page、page_size、sort、filter 请求文档所述评价。page 默认 1，page_size 默认 10、文档上限 20。sort 支持 newest、rating_high、rating_low；filter 支持 all、buying、selling、buy_and_sell、connected、renting、no_response。 此接口没有已保存响应，精确评价键、分页总数和覆盖未验证。每个样本保留客户关系筛选及排序，不把筛选后的单页称为全部客户经历，也不因评价数量缺失就推断从未有人评价。

提供团队负责人 screen_name，请求文档描述的团队资源，包括成员、可用联系字段及汇总统计。此查询以负责人资料为起点，不是搜索所有同名经纪机构下的无关经纪人。 此路由未实测，精确成员、联系和汇总统计字段及新鲜度尚未确认。团队汇总与个人指标应分开，不能相加；名册成员身份也不证明当前雇佣关系、联系同意或执照有效。

用已知公开 screen_name 请求文档中的联系视图。可用数据可能包含 E.164 与显示格式电话、仅在公开发布时提供的邮箱、网站、社交链接、经纪办公室地址和执照。实际响应结构和字段完整性未实测。 邮箱或电话缺失时代表不可用，不可自行推断或重建。公开联系信息不等于同意接收主动营销。使用前应确认适用 TCPA、拒接来电名单及其他法律要求，尊重同意与拒绝联系偏好，专业资格另行核实。

body 为包含 screen_names 数组的 JSON 对象，填写已知公开经纪人用户名。名单应来自有权使用的目录，或为合法研究而主动选择。现有文档未提供数字批量上限，应在客户端控制规模并处理校验错误，不能自行杜撰固定限额。 文档逐项状态为 ok、not_found、error，一名经纪人失败不必导致其他项无效。此路由未实测，精确响应结构、联系字段和顺序未确定。保留每项原始输入、结果与缺失值，并遵守同意、拒接来电名单和拒绝联系要求。批量访问公开信息不代表获准发送主动营销。