如何使用实时Zillow数据API

您需要发布一个房地产功能，以在城市中查找活动列表，按半径或自定义多边形边界——并且您需要在本周内完成。通过本指南，您将能够使用Zyla API Hub上的实时Zillow数据API按位置、坐标和多边形搜索实时物业数据，解析您关心的响应字段（zpid、价格、地址、zestimate、卧室、浴室），并将其连接到您的应用程序或AI代理工作流中。

此API的功能及使用时机

实时Zillow数据API提供对Zillow列表的程序化搜索。您可以：

• 按位置（城市、县、社区或邮政编码）进行搜索，并带有分页和状态过滤器。
• 围绕一个经纬度点进行搜索，带有直径（未在中心文档中指定英里或公里；将其视为抽象的“搜索半径”）。
• 在任意多边形内搜索，以获得细粒度的地理边界。

典型的集成包括物业搜索用户界面、基于列表地理围栏的线索路由、每日比较刷新作业，以及在新“待售”列表出现在多边形内时触发的警报系统。

此API可在Zyla API Hub上获得，这是一个拥有超过10,000个公共API的市场，您只需一个帐户、一个API密钥和一个订阅模型。

在Zyla API Hub上开始

要获取API密钥：

1. 打开实时Zillow数据API页面并开始试用：开始7天试用实时Zillow数据API。
2. 点击订阅（或在可用时开始免费试用）并获取您的API密钥。
3. 在Authorization头中使用密钥，格式为：Authorization: Bearer YOUR_API_KEY。

Zyla的计费是订阅+配额（不是按调用计费）。请查看API页面以获取当前访问选项和定价。

您今天可以调用的端点

所有请求都是对Zyla Hub URL的GET请求，必须包含您的Authorization头。以下是三个可用端点及其确切URL和参数。

1）按城市/县/社区/邮政编码搜索

方法：GET

URL：https://zylalabs.com/api/7341/real-time-zillow-data-api/11667/search

参数：

• location（字符串，必需）：例如，洛杉矶，加州
• page（字符串，可选）：例如，2
• home_status（字符串，可选）：例如，FOR_SALE

官方curl（复制/粘贴）：

curl -s -X GET "https://zylalabs.com/api/7341/real-time-zillow-data-api/11667/search?location=Los+Angeles%2C+CA&page=2&home_status=FOR_SALE"
-H "Authorization: Bearer YOUR_API_KEY"

官方示例响应：

{
"status": "OK",
"request_id": "81fc95df-86f3-44b7-a3dc-1d81abcd7a97",
"parameters": {
"page": 2,
"home_status": "FOR_SALE",
"sort": "DEFAULT",
"listing_type": "BY_AGENT",
"location": "Los Angeles, CA"
},
"data": [
{
"zpid": "136702358",
"homeStatus": "FOR_SALE",
"detailUrl": "https://www.zillow.com/homedetails/24425-Woolsey-Canyon-Rd-SPC-39-Canoga-Park-CA-91304/136702358_zpid/",
"address": "24425 Woolsey Canyon Rd Spc 39, Canoga Park, CA 91304",
"streetAddress": "24425 Woolsey Canyon Rd Spc 39",
"city": "Canoga Park",
"state": "CA",
"country": "USA",
"zipcode": "91304",
"latitude": 34.235462,
"longitude": -118.661224,
"homeType": "MANUFACTURED",
"price": 99500,
"currency": "USD",
"zestimate": 178100,
"rentZestimate": 3439,
"taxAssessedValue": 21901,
"bathrooms": 2,
"bedrooms": 4,
"livingArea": 1818,
"daysOnZillow": 5,
"isFeatured": false,
"isPreforeclosureAuction": false,
"timeOnZillow": 498172000,
"isNonOwnerOccupied": true,
"isPremierBuilder": false,
"isZillowOwned": false,
"unit": "Spc 39",
"isShowcaseListing": false,
"listingSubType": {
"is_FSBA": true
},
"palsId": "3007_SR26162189",
"id": "136702358",
"rawHomeStatusCd": "ForSale",
"marketingStatusSimplifiedCd": "For Sale by Agent",
"imgSrc": "https://photos.zillowstatic.com/fp/1d8602169bd359c27caa6d6e25cdf662-p_e.jpg",
"hasImage": true,
"statusType": "FOR_SALE",
"statusText": "待售房屋",
"countryCurrency": "$",
"unformattedPrice": 99500,
"addressStreet": "24425 Woolsey Canyon Rd Spc 39",
"addressCity": "Canoga Park",
"addressState": "CA",
"addressZipcode": "91304",
"isUndisclosedAddress": false,
"shouldShowRequestOnPrice": false,
"beds": 4,
"baths": 2,
"area": 1818,
"latLong": {
"latitude": 34.235462,
"longitude": -118.661224
},
"flexFieldText": "5 days on…

您通常可以从数据中的每个项目读取的信息：

• zpid：您可以存储在数据库中的唯一列表标识符，并用作幂等键。
• 价格和货币：数字要价及其货币（例如，USD）。
• 地址、城市、州、邮政编码：用于用户界面的显示和地理编码信息。
• 卧室、浴室、居住面积：用于过滤器和徽章的核心规格。
• 纬度、经度（和latLong）：地图位置和接近计算。
• zestimate和rentZestimate：定价上下文的参考值。
• homeStatus（例如，FOR_SALE）和daysOnZillow：状态和时效性。

分页：使用page参数逐步浏览结果页面。响应回显输入页面。根据您的应用逻辑构建分页用户界面/工作者，直到您的停止条件（例如没有更多结果）。

2）按坐标搜索（中心点+直径）

方法：GET

URL：https://zylalabs.com/api/7341/real-time-zillow-data-api/11668/search-by-coordinates

参数：

• long（字符串，必需）：例如，-118.504744
• lat（字符串，必需）：例如，34.01822
• diameter（字符串，可选）：例如，2

官方curl（复制/粘贴）：

示例响应（由中心列表提供的摘录）：

当用户在中心点周围移动地图时，或当您在商店、学校或交通站周围设置地理围栏时使用此功能。响应包括与搜索端点相同的核心字段。

3）按多边形搜索（任意地理围栏）

方法：GET

URL：https://zylalabs.com/api/7341/real-time-zillow-data-api/11669/search-by-polygon

参数：

• polygon（字符串，必需）：以空格分隔的经纬度坐标对（按此顺序），用逗号分隔。下面提供示例。

官方curl（复制/粘贴）：

示例响应（由中心列表提供的摘录）：

用于社区形状的搜索、学校入学区域、洪泛区或其他非标准边界。polygon参数是一个单一字符串；确保您像示例curl中那样对其进行URL编码。

身份验证和头信息

• 头信息：Authorization: Bearer YOUR_API_KEY
• 中心文档中不需要其他头信息。
• 以下所有示例都准确指向zylalabs.com上的中心URL。

最小Python示例：搜索洛杉矶“待售”列表（第2页）

此示例调用搜索端点并提取典型列表卡所需的核心字段。它反映了官方curl的参数。

import os
import requests

API_KEY = os.getenv("ZYLA_API_KEY", "YOUR_API_KEY")
url = "https://zylalabs.com/api/7341/real-time-zillow-data-api/11667/search"
params = {
"location": "Los Angeles, CA",
"page": "2",
"home_status": "FOR_SALE"
}
headers = {
"Authorization": f"Bearer {API_KEY}"
}

resp = requests.get(url, params=params, headers=headers, timeout=30)
resp.raise_for_status()
payload = resp.json()

print("状态:", payload.get("status"))
print("请求ID:", payload.get("request_id"))
for item in payload.get("data", []):
listing = {
"zpid": item.get("zpid"),
"status": item.get("homeStatus") or item.get("statusType"),
"price": item.get("price"),
"currency": item.get("currency"),
"address": item.get("address"),
"city": item.get("city") or item.get("addressCity"),
"state": item.get("state") or item.get("addressState"),
"zipcode": item.get("zipcode") or item.get("addressZipcode"),
"bedrooms": item.get("bedrooms") or item.get("beds"),
"bathrooms": item.get("bathrooms") or item.get("baths"),
"livingArea": item.get("livingArea") or item.get("area"),
"latitude": item.get("latitude") or (item.get("latLong") or {}).get("latitude"),
"longitude": item.get("longitude") or (item.get("latLong") or {}).get("longitude"),
"zestimate": item.get("zestimate"),
"rentZestimate": item.get("rentZestimate"),
"detailUrl": item.get("detailUrl"),
"imgSrc": item.get("imgSrc"),
"daysOnZillow": item.get("daysOnZillow")
}
print(listing)

注意：

• 响应包括标准化字段（例如，卧室、浴室）和有时的替代名称（床、浴室、面积）。上面的示例检查了两者。
• 纬度/经度可能同时出现在顶层和latLong内部。如果需要，代码片段会回退。
• 使用request_id进行日志记录和重试之间的关联。

实际实施细节

• 分页：page参数是中心接口中的字符串。将其作为字符串递增（“1”、“2”、“3”、……）。当您的应用程序决定没有更多相关结果时停止。
• 按状态过滤：home_status接受像FOR_SALE（如所示）的值。保持您的用户界面过滤器与您传递的允许值对齐。
• 位置查询：location接受人类可读的输入，例如“洛杉矶，加州”。对于邮政编码或社区查询，直接在位置中传递这些名称。
• 坐标与多边形：对于简单的圆形搜索（例如，“在此点2个单位内”），优先使用坐标+直径。对于围绕社区、学校区域或自定义边界的准确形状，使用多边形。
• 缓存和轮询：如果您定期刷新，请在数据库中存储zpid和更新时间戳以去重。响应包括状态和zestimate字段，有助于变更检测。
• 单位和货币：示例中的价格以“USD”货币显示。某些响应中的地块面积单位可能为“平方英尺”。为清晰起见，按原样显示响应中的值。

您本周可以发布的实际用例

• 城市搜索页面：使用带有位置的搜索端点来呈现卡片。添加带有page=2,3,…的分页。
• “附近我”搜索：使用以用户设备位置为中心的坐标搜索。调整直径以匹配您的用户体验（例如，滑块）。
• 多边形警报：存储用户定义的多边形以进行“监视区域”。按计划运行多边形搜索，并在出现新的待售列表时通过电子邮件或推送通知（按zpid比较）。
• 地图绘制工具：让用户在地图上绘制形状并转换为多边形参数字符串（经纬度对）。调用按多边形搜索并将结果显示为图钉。
• 线索路由：获取结果并根据列表城市或多边形成员资格路由到代理。

通过MCP从AI代理调用此API

Zyla上的每个API都可以通过与MCP兼容的客户端（Claude Code、Cursor、Windsurf等）通过MCP端点调用。通过MCP URL查询字符串提供您的密钥，并发出与您在本文中看到的相同中心端点和参数相匹配的工具调用。有关详细信息，请参见MCP。典型流程：

1. 使用MCP端点和您的密钥配置您的MCP客户端。
2. 指示代理使用本文中显示的确切中心URL和参数调用搜索或地理空间端点。
3. 解析相同的JSON字段（zpid、价格、地址、zestimate、纬度/经度）以进行下游任务，例如起草物业摘要或更新您的CRM。

每种搜索样式的端到端示例

城市/邮政编码搜索

当您有用户输入的城市或邮政编码时使用。

解析data[].zpid、data[].price、data[].address、data[].bedrooms、data[].bathrooms、data[].livingArea以用于用户界面卡片。

地理围栏半径（地图中心）

在用户平移/缩放地图后使用，或覆盖以POI为中心的半径。

使用纬度/经度显示图钉，并在点击图钉时显示detailUrl。

多边形边界

用于学校区域、HOA边界或任何自定义绘制在地图上的工作流。编码“经纬度”对，用逗号分隔，并对字符串进行URL转义。

操作关注点

• 错误处理：记录状态和request_id以进行调试。当发生传输错误时，根据您的应用标准实现回退和重试。
• 配额：您的订阅管理每月配额。在您的Zyla仪表板中监控使用情况。这里没有按调用计费；它是订阅+配额。
• 数据新鲜度：根据用户的期望设计同步节奏。如果您需要接近实时的更新，请更频繁地轮询较小的地理块。
• 标准化：在您的数据库中持久化派生模式，包含用户界面所需的字段，以zpid为键，并维护一个源JSON列以便审计。

接下来该去哪里

• 浏览并在Zyla上订阅：Zyla API Hub。
• 立即集成实时Zillow数据API：开始7天试用实时Zillow数据API。

常见问题

Q1：我需要什么头信息来进行身份验证？
A1：使用Authorization: Bearer YOUR_API_KEY。在Zyla的API页面上获取您的密钥。

Q2：我可以仅过滤活动列表吗？
A2：可以。在支持的地方传递home_status=FOR_SALE（例如，搜索端点）。响应回显您的参数，以便您可以验证应用的过滤器。

Q3：我该如何处理分页？
A3：将page参数用作字符串并为后续页面递增。响应的参数.page回显当前页面。

Q4：坐标搜索和多边形搜索有什么区别？
A4：坐标+直径在单个点周围创建圆形搜索。多边形搜索接受任意边界（经纬度对）以进行精确的地理围栏。

Q5：有没有免费计划？
A5：没有免费计划。您可以从API的列表中开始试用。请查看API页面以获取当前访问选项和定价。

准备好实施了吗？打开市场列表并开始试用以获取API密钥：实时Zillow数据API。在Zyla API Hub上使用一个帐户，您可以在单个密钥下调用此API和成千上万其他房地产和住房API。