闲鱼商品列表API实践：基于接口实现电商竞品价格监控

摘要：二手电商业务场景下，需要批量获取同型号、同类目下大量竞品商品，完成行情摸底、价格区间统计、竞品盯盘。如果逐个录入商品 ID 监控效率很低，通过闲鱼商品列表 API 可以按关键词、类目完成批量商品拉取，再结合后续数据过滤，实现批量竞品价格监控体系。

一、业务背景

做二手 3C、潮玩、奢侈品类目时，经常有下面业务痛点：

1. 竞品数量庞大，手动一个个收集num_iid再做详情监控，工作量大，无法覆盖全市场行情；
2. 需要统计某一款机型全网二手价格分布，判断合理进货与售卖定价；
3. 希望持续发现新上架竞品，及时捕捉低价货源；
4. 单纯靠页面人工浏览，很难持续跟踪大量新增、降价、下架商品。
5. 接口名称：goodfish.item_search（闲鱼商品列表API，taobaoapi2014前往体验）
6. 请求网关： c0b.cc/R4rbK2 （HTTPS，支持 GET/POST）
7. 请求方式：GET / POST

闲鱼商品列表 API（goodfish.item_search），支持关键词、类目筛选，返回商品列表基础数据，包含商品 ID、标题、售价、成色、所在地、想要数量等，拿到num_iid之后，再配合商品详情 API 做深度数据补齐，构建完整批量竞品监控链路。

二、整体系统设计思路

业务完整流程

1. 检索条件配置：配置监控关键词、类目 ID、筛选条件（成色范围、价格区间）；
2. 调用列表接口分页拉取：循环分页获取列表商品基础数据，得到批量商品num_iid；
3. 数据去重过滤：过滤重复商品、过滤不符合成色 / 价格条件的垃圾数据；
4. 商品池入库：将新发现商品存入监控库，老商品更新列表快照；
5. 可选：详情接口补齐：对重点商品调用goodfish.item_get获取卖家信息、完整描述、规格参数；
6. 多版本数据对比：对比历史快照，识别价格变动、商品下架、热度异动；
7. 告警输出：价格大幅下跌、新品上架、商品售罄触发消息通知；
8. 数据持久化：保存列表快照，用于行情统计、价格区间分析。

列表接口可监控核心维度

• 商品标题、售价、成色
• 商品发布时间
• 想要人数（二手核心热度指标）
• 商品所在地
• 商品唯一 ID num_iid（用于关联详情接口）

注意：列表接口返回字段为轻量化数据，缺少卖家信用、完整参数、详情描述，精细化监控场景需要二次调用商品详情 API。

三、关键业务处理要点

1. 分页终止逻辑 列表接口分页返回，当返回商品数组为空，代表已经到最后一页，业务层终止分页循环，防止死循环请求。
2. 数据去重机制 同一商品可能跨页重复出现，必须使用num_iid作为唯一主键入库去重。
3. 列表与详情接口分工

• 列表 API：负责批量发现商品，快速捞取同类目 / 关键词下全部商品；
• 详情 API：负责精细化监控，只对筛选后的重点商品调用，降低接口调用量，减少限流风险。

1. 二手比价必须结合成色 同样型号，99 新和八成新价格差距巨大，不能单纯对比价格数字，告警逻辑需要带上condition成色字段做联合判断。
2. 新品识别逻辑 对比数据库，如果num_iid不存在，判定为新上架竞品，可以配置新品上架告警。