用 Python 按邮编搜 Realtor 出租房源:先留下 property_id
纽约邮编 10001 本身就是一份很小的样本:一个五位数、一页出租广告、若干行卡片。卡片上也许有挂牌租金,也许没有;真正能带去下一跳的,只有搜索返回的 property_id。没有这个 id,详情接口无处可去。把邮编直接当房产编号、或拿地点补全的区域 id 去调详情,都接不上。本文就从这份小样本起步,而不是从全国库存或编造的房源响应写起。
Realtor 房源数据 API 是非官方只读 JSON 服务,不是 Realtor.com 官方产品,也不是 MLS/IDX 授权源、估价模型或“现在仍可租”的证明。房源会下架,字段会空。打开本页或复制代码不会发请求。
一个邮编就够起步
property-search-rent 的 location 可以直接填 ZIP。不必先拼城市名,也不必先拿地点补全的 id。邮编按字符串保存,避免前导零被吃掉。已验证示例是 location=10001、sort=newest、page=1。搬家短名单、跨境选房、按邮编抽租金样本,第一步都是同一件事:先把这个五位数变成一页卡片,而不是立刻去充实整栋楼。
在控制台取你有权使用的平台 Key(需先登录)。Python 从服务端环境变量 OPENDATA_API_KEY 读取;示例里的 YOUR_API_KEY 只是占位。不需要房产网站账号或 Cookie。Key 走查询串,生产请求放服务端,日志和截图都要脱敏。额度按请求计,复制文档不会消耗。
用户只打了城市名、需要消歧时,再走 property-auto-complete。纽约示例会给出类似 city:New York, NY 的地点 id——它选的是搜索区域,不是房子。把区域 id 填进详情的 query,等于拿地图图钉去问一间公寓。不能自己编一个,也不能拿补全结果里偶尔出现、可空的 propertyId 当搜索行身份。无匹配时载荷就是 {"data":[]},没有 status 字段,这是合法空结果,不要改成另一个城市重试。
在售、已售是另外的操作:property-search-buy 验证过 New York, NY,property-search-sold 验证过 Austin, TX。出租邮编搜索不会顺便带回这两类库存,三类搜索各自交出自己的 property_id,不要混进同一条补全流水线。
搜索给的是行,不是房子
判断成败要分三层,不要合成一个布尔值。先看 HTTP 是否 2xx,再看网关 {code, message, data}(code 为 200 才是平台业务成功;Key 无效或额度不足通常停在这一层),出租搜索的内层还有 status / message / data。内层 data 是扁平数组,路径在 gateway.data.data,不是套在 results 里的对象。每一项是列表卡片,不是详情对象。排查时只留脱敏后的 code 与 message,不要把带 Key 的完整 URL 写进监控。
曾有一次不可能的在售地点:HTTP 200、status=false、data=null,外加一条像分页出错的业务消息。那是搜索失败,不是“这一页刚好没房”。不要按页码去重试,也不要把这种失败当成空库存去画租金分布。
行里常见 property_id、listing_id、status=for_rent、location.address(含 postal_code)、list_date,以及可空的 list_price / list_price_min / list_price_max。description 里可能是卧室浴室的单值,也可能是区间。挂牌租金是广告价,不是已签租约。list_price 为空表示未提供,不是零租金;只有区间时就展示区间,不要合成一个数。统计样本时把空价单独记账,别把缺失揉进均值。
这些字段够做短名单。叙事、税史、图片使用权都不在这一层。给每一行取详情是额度选择,不是搜索的必做步骤。用户还没点开的房子,身份先存着就够。
必须留下的 id
property-v2-detail 不接受邮编。必填 query 必须是搜索已经返回的标识——已验证路径用的是 property_id。文档还写了 URL、完整地址等写法,但现场只核过搜索得来的房产编号;本文不拿没返回的地址去试。不能从 ZIP 推出来,也不能用地点补全的 id 顶替。搜索行里没有 property_id,就没有下一跳。
property_id 标识房产,listing_id 标识这一次挂牌,二者不是同一个东西。同一套房可能换挂牌,编号会变。两者都保持字符串,并且成对来自同一行。详情只把 property_id 放进 query。需要两个键的其它路由,也必须取自同一行,禁止交叉拼接。地点 id 永远不能冒充房产身份。
先安装 requests,在服务器注入环境变量再跑。脚本本地只展示最多八张卡片,并不声称服务端只返回八行;没有收集到 id 之前,不会调用详情。这就是身份交接:搜索负责发现,详情只接收已经留下的键。
import os
import requests
BASE = "https://api.opendata-api.com/api/project/realtor"
API_KEY = os.environ["OPENDATA_API_KEY"]
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 ValueError("Unexpected operation payload")
if "status" in payload and payload["status"] is not True:
raise RuntimeError("Operation business failure; inspect status/message safely")
return payload
search = call("property-search-rent", location="10001", sort="newest", page=1)
rows = search.get("data")
if not isinstance(rows, list):
raise ValueError("Expected a flat listing array")
# Identity handoff: collect property_id values before any detail call.
kept = []
print("Actual rows:", len(rows), "Reported page:", search.get("currentPage"))
for row in rows[:8]:
property_id = row.get("property_id")
address = (row.get("location") or {}).get("address") or {}
price = row.get("list_price")
rent = "Advertised rent unavailable" if price is None else f"Advertised rent: {price}"
print(property_id, address.get("postal_code"), rent)
if property_id:
kept.append(str(property_id))
if not kept:
print("No property ID available for enrichment")
else:
selected = kept[0]
detail = call("property-v2-detail", query=selected)
home = detail.get("data")
if not isinstance(home, dict):
raise ValueError("Expected a detail object")
if str(home.get("property_id")) != selected:
raise ValueError("Detail identity differs from the selected property")
print(home.get("property_id"), home.get("last_update_date"))
详情的现场核对用的是在售搜索拿到的房产 id,地址和要价对得上。出租搜索新拿到的 property_id 只是补全候选,不保证详情一定有货。入库前核对返回身份;空值保留;另存采集时间。last_update_date 不是实时在架证明。
邮编搜索覆盖不到什么
这条链路给不了完整邮编库存、历史租金账、业主联系方式,也给不了图片和文案的再分发权。能调接口不等于拿到 MLS/IDX 许可,使用权要另行确认。list_date 是挂牌日,不是签约日,更不是你采集的时间。
实测里 pageSize=8 仍返回 30 行。以实际数组长度为准,不要信 resultsPerPage、totalResultCount、totalPages 能对上。跨页按 property_id/listing_id 成对去重,空页或重复页就停,并给翻页加预算上限。地点补全 limit=5 也曾返回十条,展示上限放在客户端。请求页大小不是强制上限,也不要向用户承诺“每页正好八条”。
已售是另一条身份流:奥斯汀样本里有 last_sold_date 和可空的 last_sold_price。成交价缺失不是零元过户,list_price 仍是挂牌要价,newest 也不等于按成交日排序。宠物、入住日、价格带等可选筛选,以及详情的地址/URL 写法,都未逐项验证。经纪人、经纬度、通勤、独立照片和房贷路由仍是待评估能力;出现的融资数字只是估算,不是批贷。
邮编换来的是行。行里才能抽出 id。只有这个 id,详情调用才接得上。