前言
在品牌渠道管控、二手竞品调研、货源采购、知识产权打假等业务中，闲鱼是不可或缺的数据来源。手动翻阅平台页面效率极低，自研爬虫又要频繁应对反爬、协议变更、设备环境等难题，开发成本居高不下。
一、三大接口功能与参数梳理
1. goodfish.item_search｜关键词商品搜索
作用：通过自定义关键词分页搜索全平台商品，批量获取商品 ID、售价、标题、卖家、地区等基础信息，是全量数据入口。
请求地址：
https://api-gw.onebound.cn/goodfish/item_search核心入参：
q(搜索词)、page(页码)；公共参数 key/secret/api_name 固定配置关键返回：商品
num_iid(单品ID)、售价、主图、卖家昵称、所在地区、分页总数
2. goodfish.item_get｜单品详情查询
作用：依托item_search返回的num_iid，调取商品完整详情数据，包含商品描述、原价、SKU 规格、发布时间、卖家信用、详情图片等深度字段。
核心入参：
num_iid（商品唯一ID）适用：单品资质核验、价格溯源、侵权取证、详情内容解析
3. goodfish.item_search_shop｜店铺全商品遍历
作用：根据商品详情内提取的shop_id，分页拉取目标店铺全部在售商品，实现竞品店铺全量盘点。
核心入参：
shop_id(店铺ID)、page(分页)适用：竞品上新监控、全店低价窜货筛查
链路逻辑：关键词搜索 (item_search)→获取商品 ID→查单品详情 ( item_get )→提取店铺 ID→抓取整店商品 ( item_search_shop )，一站式完成「全平台关键词→单品→店铺」三层数据采集。
二、Python 串联调用示例（可直接运行）
python
运行
import requestsBASE_URL = "https://api-gw.onebound.cn/goodfish"KEY = "xxx"SECRET = "xxx"# 1、关键词搜索商品def search_item(keyword, page=1): params = { "key": KEY, "secret": SECRET, "api_name": "goodfish.item_search", "q": keyword, "page": page } res = requests.get(f"{BASE_URL}/item_search", params=params).json() return res# 2、根据商品ID获取详情def get_item_detail(num_iid): params = { "key": KEY, "secret": SECRET, "api_name": "goodfish.item_get", "num_iid": num_iid } res = requests.get(f"{BASE_URL}/item_get", params=params).json() return res# 3、根据店铺ID抓取全店商品def get_shop_goods(shop_id, page=1): params = { "key": KEY, "secret": SECRET, "api_name": "goodfish.item_search_shop", "shop_id": shop_id, "page": page } res = requests.get(f"{BASE_URL}/item_search_shop", params=params).json() return resif __name__ == "__main__": # 链路演示 search_res = search_item("品牌蓝牙耳机") if search_res["error_code"] == "0000": first_goods = search_res["items"]["item"][0] goods_id = first_goods["num_iid"] detail = get_item_detail(goods_id) shop_id = detail["item"]["shop_id"] shop_data = get_shop_goods(shop_id) print("店铺在售商品：", shop_data)三、四大商业化落地应用场景
场景 1：品牌渠道控价 & 窜货监控
配置品牌 + 产品关键词，定时调用item_search全平台巡检，抓取售价、发货地；低于指导价、异地违规铺货商品自动标记，通过item_get调取详情留存链接、卖家信息，再用item_search_shop排查违规店铺全店商品，实现窜货精准溯源。
场景 2：竞品全维度行情监测
录入竞品品牌词，定期抓取竞品在售商品，统计均价、上新频率；针对头部竞品店铺，用店铺接口全量拉取货品，分析竞品定价策略、库存变化、清仓活动，辅助自家产品定价与备货。
场景 3：知识产权假货巡检取证
输入品牌名 + 假货关键词（高仿、山寨等），批量检索违规商品，通过单品接口保存商品详情页、图片、卖家资料，形成投诉取证素材，配合平台投诉下架侵权商品。
场景 4：二手货源数据分析
采集类目全量商品数据，汇总各品类价格区间、热门货源地域、热销单品，为二手商贩、回收企业提供货源选址、选品的数据参考。
四、中小型数据采集系统架构
plaintext
业务配置(关键词/店铺清单) ↓API采集服务（三合一接口封装+分页循环+限流控制） ↓Redis（缓存去重、接口缓存cache配置） ↓MySQL/Elasticsearch（商品数据落地存储） ↓统计&可视化模块（价格看板、低价告警、竞品报表）
轻量化部署：小团队直接采集入库 MySQL 即可；中大型业务接入 ES 做全文检索、时序价格统计。
五、开发避坑实战总结
缓存优化：接口支持
cache=yes参数，非实时场景开启缓存，减少调用成本、提升响应速度；分页逻辑：
item_search与店铺接口依靠 page 分页，循环遍历需判断总条数避免无效请求；限流管控：控制 QPS，高频调用会返回 4008 限流错误，采用分时采集、队列削峰；
链路容错：单品不存在、店铺注销会返回 2000 错误码，代码增加异常捕获跳过无效数据。
六、总结
goodfish三款接口覆盖闲鱼从全网搜品→单品深挖→整店盘点全链路数据需求，规避自研爬虫的反爬、迭代维护成本，开发人员仅需数小时即可完成基础采集服务搭建。无论是品牌风控系统、二手电商数据分析工具、打假平台，都能基于这套 API 快速落地业务，低成本实现闲鱼数据自动化监控。
#API #闲鱼爬虫 #数据分析 #品牌控价 #后端开发
