wiki/skills/jd-fapai-scrape/SKILL.md

name, description

name	description
jd-fapai-scrape	抓取京东法拍房搜索结果并支持增量更新。通过 Playwright 渲染京东法拍 H5 页面，拦截 API 响应，提取完整房源数据。支持项目链接、拍卖轮次、智能增量更新（遇到已知数据即停止，不全量下载）。

京东法拍房源抓取

用途

从京东司法拍卖频道搜索结果页抓取全部房源信息：

• 房源标题与地址（完整不截断）
• 项目链接（https://m.jd.com/product/{skuId}.html）
• 起拍价 / 当前价 / 均价
• 户型 / 面积 / 用途 / 小区名称
• 拍卖轮次（一拍/二拍/变卖，从 API 标签或折扣率推断）
• 拍卖状态 / 出价次数 / 围观人数
• 拍卖开始与结束时间
• 增量追踪字段（_first_seen / _last_seen）

前置条件

pip install playwright
python3 -m playwright install chromium
# 或 apt install chromium-browser

使用方法

首次抓取

# 默认抓取塘厦镇
python3 skills/jd-fapai-scrape/scrape.py

# 抓取东莞市全部法拍房（~4000 条，约 3 分钟）
python3 skills/jd-fapai-scrape/scrape.py --keyword 东莞市 --output-dir ../法拍/data

# 自定义参数
python3 skills/jd-fapai-scrape/scrape.py --keyword 长安 --sort-field 11 --cate-id 15

增量更新

# 加 -i 标志，只下载新房源，遇到已知 paimaiId 即停止
python3 skills/jd-fapai-scrape/scrape.py --keyword 东莞市 --output-dir ../法拍/data -i

增量模式的智能行为：

• 读取已有 {keyword}_法拍房源.json 中的所有 paimaiId
• 按最新发布排序加载（spo_sortField=11）
• 每加载一批（~40 条）检查是否全部已知，如果是则立即停止
• 典型增量更新只需加载 1-2 批（~30 秒），而非全量下载 100 批（~3 分钟）
• 新房源添加 _first_seen 和 _last_seen 时间戳
• 已有房源更新可变字段（当前价、状态、出价次数等）并刷新 _last_seen

去重机制

去重 key = paimaiId（拍卖ID）

• 每次拍卖有唯一的 paimaiId，同一房产的一拍和二拍是不同的 paimaiId，各自保留
• 不会因为标题相同而合并不同拍卖轮次
• paimaiId 对应唯一的详情页 URL（https://m.jd.com/product/{skuId}.html），等价于按 URL 去重

命令行参数

参数	默认值	说明
--keyword	塘厦	搜索关键词
--cate-id	15	类目 ID（15=法拍房）
--sort-field	11	排序（11=最新发布）
--max-scrolls	100	最大滚动次数
--output-dir	.	输出目录
--incremental / -i	false	增量更新模式

输出文件

文件	内容
{keyword}_法拍房源.csv	CSV 表格（26 列，最新发布在前）
{keyword}_法拍房源.json	完整原始 JSON（含增量追踪字段）
{keyword}_增量日志.log	每次增量更新的新增/变更记录（仅增量模式）

CSV 列说明

列	说明
序号 / 拍卖ID / SKU ID	唯一标识
标题	完整房产标题
项目链接	https://m.jd.com/product/{skuId}.html
位置 / 用途 / 户型 / 面积(㎡) / 小区 / 均价	房产属性
起拍价 / 当前价 / 折扣率	价格信息
拍卖轮次	一拍/二拍/变卖（API 标签或折扣率推断）
标签	全部标签（诉讼资产、低于评估价等）
状态 / 出价次数 / 围观人数	拍卖状态
开始时间 / 结束时间	拍卖时间
拍卖类型	司法拍卖等
首次发现 / 最后更新	增量追踪时间戳

工作原理

1. Playwright 渲染：headless Chromium 打开京东法拍 H5 页面
2. SSR 数据提取：页面加载后从 <script> 标签中解析内嵌的 page 1 数据（约 40 条）
3. API 拦截：监听 api.m.jd.com 响应，捕获三个 API：
   • getSearchData（appid=paimai）→ 房源列表 page 2+（标题、价格、户型、面积等）
   • getPaimaiCurrentInfoByIdsForApi → 实时拍卖状态（当前价、出价、围观）
   • getAuctionLabelConfigs → 拍卖标签（一拍/二拍/变卖等）
4. 无限滚动：自动滚动触发加载更多
5. 智能停止：增量模式下，检测到一批数据全部已知即停止（SSR page 1 和 API 各批都检查）
6. 拍卖轮次推断：优先用 API 标签，无标签时从折扣率推断（7折≈一拍, 5.6折≈二拍/变卖）
7. 排序：保持 API 返回顺序（spo_sortField=11 已按发布时间降序），不重新排序
8. 增量合并：按 paimaiId 去重合并，新数据在前，旧数据在后

历史数据抓取（sortField=2）

默认的 sortField=11（最新发布）只返回近期上架的房源。京东平台实际保留了从 2017年7月 至今的全部历史成交数据，但需要用 sortField=2（按结束时间升序）才能获取。

⚠️ 4000条数据上限

京东法拍无限滚动有 ~4000条硬性上限（约100次滚动后API停止返回新数据），无论排序方式如何。这意味着：

• sortField=11（最新发布）：返回最近~4000条（约覆盖最近10个月）
• sortField=2（结束时间升序）：返回最早的4000条（约覆盖2017-07至2022）

无法通过一次搜索获取全量历史数据。 对于总量超过4000条的城市（如东莞市住宅~20,276条），需要按镇/区分区域抓取。

按镇/区分区域抓取（推荐）

# 单个镇（数据量通常<4000，可一次抓全）
python3 skills/jd-fapai-scrape/scrape_history.py \
  --keyword 樟木头 --batch-label 樟木头_all \
  --max-scrolls 200 --output-dir "output/法拍"

# 批量抓取所有镇（shell脚本循环）
for town in 莞城 东城 南城 万江 ... ; do
    python3 skills/jd-fapai-scrape/scrape_history.py \
        --keyword "$town" --batch-label "${town}_all" \
        --max-scrolls 200 --output-dir "output/法拍"
done

合并时用 analyze_trends.py 按 paimaiId 去重：

python3 skills/jd-fapai-scrape/analyze_trends.py

大镇的数据缺口

部分大镇（如东城3998条、南城3780条）会接近4000条上限，sortField=2 的数据覆盖到~2025年。2025年末至2026年的近期数据可通过原始 scrape.py（sortField=11）补充，中间有约1年缺口。

数据量参考

关键词	类目	总记录数	sortField=2 实际获取
东莞市	住宅（cate_id=15）	~20,276	3,995（2017至2022）
樟木头	住宅	~558	558（2018至2026，全覆盖）
东城	住宅	~3,998	3,998（2017至~2025，触顶）
南城	住宅	~3,780	3,780（2018至~2025，触顶）

每页约40条，上限约100次滚动≈4000条。单个镇通常1-3分钟完成。

注意事项

• 京东法拍 API 有风控验证，必须通过浏览器渲染，无法直接调用 API
• 页面是 JS SPA，但第一页数据通过 SSR 内嵌在 HTML <script> 标签中，需单独提取
• API 只返回 page 2+，只拦截 API 会漏掉 page 1（包括最新发布的房源）
• URL 中的位置参数（tttparams、spo_lat、spo_lng）影响搜索结果范围
• API 每页约 40 条，无限滚动约 100 次后停止返回新数据（~4000 条硬性上限），非滚动次数限制
• 历史数据（sortField=2）最早到 2017年7月，更早的数据平台已下架
• 京东法拍无独立"已结束"tab，sortField=2 是获取历史成交的唯一方式
• 大城市（如东莞市）总量超过4000条，需按镇/区分区域抓取才能获取全量历史数据
• scrape_history.py 的 getPaimaiCurrentInfoByIdsForApi 响应捕获需要足够等待时间（初始5秒、滚动间隔3秒），否则结束时间等字段可能为空
• 拍卖标签（一拍/二拍）仅对部分数据能从 API 获取，其余从折扣率推断
• 同一房产的多次拍卖（一拍流拍后二拍）有不同的 paimaiId，各自独立保留