redfin-api

Redfin API

Redfin 在 https://www.redfin.com/stingray/ 提供非官方 JSON API。所有 请求均为 HTTP GET。有效 JSON 前会添加 {}& （4 个字节）作为前缀——解析前务必去掉此前缀。

身份验证与标头

• 必须提供 User-Agent 标头（使用当前版本的 Chrome UA 字符串）
• 经过身份验证的访问可选择使用以下 Cookie：
  • RF_ACCESS_LEVEL、RF_AUTH、RF_W_AUTH、RF_SECURE_AUTH、RF_PARTY_ID
• 在请求之间添加限速延迟，以免被封禁

响应格式

每个端点都会返回以下封装格式：

{
  "version": 1,
  "errorMessage": "Success",
  "resultCode": 0,
  "payload": { ... }
}

resultCode == 0 且 errorMessage == "Success" 表示成功。payload 的结构因端点而异。

核心工作流

1. 按邮政编码 / 位置搜索房源

步骤 1：位置自动补全，获取区域 ID。

GET /stingray/do/location-autocomplete?location={query}&v=2

响应 payload：

{
  "sections": [{ "rows": [{ "id": "2_12345", "type": "2", "name": "92708", ... }] }],
  "exactMatch": { "id": "2_12345", ... }
}

id 字段的格式为 {region_type}_{region_id}。按 _ 拆分以提取两部分。

步骤 2：下载 GIS CSV，获取该区域的房源信息。

GET /stingray/api/gis-csv?region_id={id}&region_type={type}&...

返回 CSV 数据（不是 JSON——没有 {}& 前缀）。CSV 包含：

• 第 0 行：标头（查找 URL 列）
• 第 1 行：MLS 免责声明文本（“In accordance with local MLS rules...”）
• 第 2 行及之后：房源数据

提取 URL 列，即可获取 Redfin 房产 URL，用于后续查询。

2. 从 URL 获取房产 ID

GET /stingray/api/home/details/initialInfo?path={redfin_path}

其中 path 为 URL 的路径部分（例如，/CA/Fountain-Valley/12345-Main-St-92708/home/12345678）。

Payload：

{
  "propertyId": 12345678,
  "listingId": 234567890,
  "latLong": { "latitude": 33.71, "longitude": -117.95 }
}

3. 获取房产详情

大多数详情端点位于 /stingray/api/home/details/ 下。有些只需要 propertyId，另一些则需要同时提供 propertyId 和 listingId。

对于仅针对房产的端点，请添加 accessLevel=1，并可选择添加 pageType=3。

端点参考

基于 URL（传入 path 参数）

端点	路径
初始信息	api/home/details/initialInfo
页面标签	api/home/details/v1/pagetagsinfo
主要区域	api/home/details/primaryRegionInfo

搜索

端点	路径	关键参数
位置自动补全	do/location-autocomplete	location、v=2
GIS CSV	api/gis-csv	region_id、region_type、筛选条件（见下文）

仅需房产 ID（propertyId 参数）

端点	路径	页面类型
首屏以下内容（MLS）	api/home/details/belowTheFold	3
社区照片	api/home/details/hood-photos	—
更多资源	api/home/details/moreResourcesInfo	—
页面标题	api/home/details/homeDetailsPageHeaderInfo	—
房产评论	api/v1/home/details/propertyCommentsInfo	—
建筑详情	api/building/details-page/v1	—
业主估价	api/home/details/owner-estimate	—
已认领卖家数据	api/home/details/claimedHomeSellerData	—
持有成本	do/api/costOfHomeOwnershipDetails	—

仅需房源 ID（listingId 参数）

端点	路径
户型图	api/home/details/listing/floorplans
看房日期选择器	do/tourlist/getDatePickerData

表格 ID（tableId 参数）

端点	路径	额外参数
共享区域	api/region/shared-region-info	regionTypeId=2、mapPageTypeId=1

完整房产详情（propertyId + listingId 参数）

接口	路径	页面类型
类似挂牌房源	api/home/details/similars/listings	—
类似已售房源	api/home/details/similars/solds	—
附近房屋	api/home/details/nearbyhomes	—
首屏内容	api/home/details/aboveTheFold	—
房产地块	api/home/details/propertyParcelInfo	3
活动/历史记录	api/home/details/activityInfo	—
非挂牌信息	api/home/details/customerConversionInfo/offMarket	3
租金估算	api/home/details/rental-estimate	—
AVM 历史记录	api/home/details/avmHistoricalData	—
信息面板	api/home/details/mainHouseInfoPanelInfo	—
描述	api/home/details/descriptiveParagraph	—
AVM 详情	api/home/details/avm	—
看房洞察	api/home/details/tourInsights	3
统计数据	api/home/details/stats	还需要 regionId

GISCSV 默认参数

这些默认值会返回指定区域内的大量挂牌房源。每次搜索时，请覆盖 region_id 和 region_type。

DEFAULT_GISCSV_PARAMS = {
    "al": "3",
    "num_homes": "350",
    "ord": "redfin-recommended-asc",
    "page_number": "1",
    "region_id": "",          # required — from location autocomplete
    "region_type": "2",       # 2 = zipcode
    "sf": "1,2,5,6,7",       # property sub-filters
    "status": "9",            # 9 = all statuses
    "uipt": "1,2,3,4,5,6,7,8",  # all property types
    "v": "8",
    # boolean filters (all false for broadest results)
    "has_pool": "false",
    "has_parking": "false",
    "has_laundry_facility": "false",
    "has_laundry_hookups": "false",
    "has_dishwasher": "false",
    "has_att_fiber": "false",
    "has_deal": "false",
    "has_short_term_lease": "false",
    "include_pending_homes": "false",
    "isRentals": "false",
    "is_furnished": "false",
    "is_income_restricted": "false",
    "is_senior_living": "false",
    "pool": "false",
    "travel_with_traffic": "false",
    "travel_within_region": "false",
    "utilities_included": "false",
}

仅筛选独栋住宅

若要仅筛选独栋住宅（与本项目相关）：

• 设置 uipt=1（仅独栋住宅，而非 1,2,3,4,5,6,7,8）
• 设置 sf=1,2,5,6,7（保留默认子筛选项）

房产类型代码（uipt）

代码	类型
1	独栋住宅
2	公寓
3	联排住宅
4	多户住宅
5	土地
6	移动式/预制住宅
7	合作公寓
8	其他

解析响应负载

Redfin 负载嵌套层级很深。使用 JMESPath 表达式（或等效的字典遍历方法）提取数据。

从 InitialInfo 负载中提取

字段	JMESPath
房产 ID	propertyId
挂牌 ID	listingId
纬度	latLong.latitude
经度	latLong.longitude

从 BelowTheFold（MLS）负载中提取

字段	JMESPath
邮政编码	publicRecordsInfo.addressInfo.zip
城市	publicRecordsInfo.addressInfo.city
州	publicRecordsInfo.addressInfo.state
图片 URL	propertyHistoryInfo.mediaBrowserInfoBySourceId.*.photos[].photoUrls.nonFullScreenPhotoUrlCompressed
缩略图 URL	propertyHistoryInfo.mediaBrowserInfoBySourceId.*.photos[].thumbnailData.thumbnailUrl
房产经纪人署名	propertyHistoryInfo.mediaBrowserInfoBySourceId.*.photoAttribution | [0]
事件数量	length(propertyHistoryInfo.events)
事件价格	propertyHistoryInfo.events[N].price
事件描述	propertyHistoryInfo.events[N].eventDescription
事件来源	propertyHistoryInfo.events[N].source
事件来源 ID	propertyHistoryInfo.events[N].sourceId
事件日期	propertyHistoryInfo.events[N].eventDate（Unix 毫秒）

解析房产经纪人姓名

photoAttribution 字段的格式类似 "Listed by Jane Smith • Acme Realty."。 按 • 分割，去除空白，然后从第 0 部分移除 "Listed by " 前缀，并从第 1 部分移除 末尾的 .。

处理事件日期

事件日期是以毫秒为单位的 Unix 时间戳。转换方式： datetime.fromtimestamp(event_date / 1000)（Python）或 time.Unix(0, event_date * int64(time.Millisecond))（Go）。

购房最实用的接口

评估房产时，这三个接口最有用：

1. InitialInfo — 房产/挂牌 ID、纬度/经度
2. BelowTheFold — 地址、房产历史（价格变动）、图片、房产经纪人信息
3. AVMDetails — Redfin 自动估值模型估算值

其他高价值接口：

• SimilarSold — 近期可比成交房源
• SimilarListings — 竞争挂牌房源
• CostOfHomeOwnership — 预计月度费用明细
• Activity — 看房活动、收藏、浏览量
• Stats — 区域市场统计数据

实现说明

响应前缀移除

除返回原始 CSV 的 GISCSV 外，每个响应都带有前缀 {}& （恰好 4 个字节）。在解析 JSON 前将其移除：

// Go
jsonBytes := responseBytes[4:]

# Python
data = json.loads(response.text[4:])

速率限制

在请求之间添加延迟（gredfin 项目使用可配置的间隔，通常为几秒）。Redfin 会阻止过于频繁的抓取。

错误处理

务必同时检查 HTTP 状态码以及 JSON 响应中的 resultCode/errorMessage 字段。即使 HTTP 状态码为 200，Redfin 响应正文仍可能包含错误。

基于哈希的去重

随着时间推移轮询房源时，对负载字节计算哈希（MD5）；如果与上次抓取的内容相同，则跳过重新处理。