实战解析：京东关键词搜索 item_search_pro —— 按关键字搜索商品

一、接口定位

item_search_pro 并不是京东官方文档里出现的接口名，而是第三方服务商对「京东关键词搜索商品」能力的封装代号。它本质上调用的是京东联盟开放平台里的
jd.union.open.goods.search（联盟版）或routerjson下的item_search（自营版）。
理解这一点后，后面的“实战”就三件事：

1. 拿到合法调用身份（App-Key / Secret / Access-Token）

2. 按业务场景拼参数、算签名

3. 对 JSON 结果做字段裁剪与落库

二、账号与权限

1. 注册「京东联盟」或「京东开放平台」→ 创建应用 → 审核通过后会拿到
   App-Key、App-Secret；联盟版还需要备案推广位，才能回传佣金字段。

2. 沙箱测试：联盟后台提供在线调试窗，先勾选“仅看返回字段”，把必填参数跑通后再上代码。

3. 配额：免费账号默认 5000 次/天，QPS≈10；申请「数据洞察」权限可扩容到 5W 次/天。

三、签名算法（以联盟版为例）

京东采用“参数名 ASCII 升序 + 首尾拼接 Secret 再 MD5”的签名方式，伪代码如下：

sign_str = app_secret for k, v in sorted(params.items()): if v == '' or v is None: continue sign_str += f'{k}{v}' sign_str += app_secret sign = md5(sign_str.encode()).hexdigest().upper()

易踩坑点：

• 必须过滤空值；

• 时间戳格式是 “2026-01-04 12:34:56”，不要带毫秒；

• param_json里的业务参数整体当作一个 value，不参与二次排序。

四、最小可运行 Python 示例

场景：搜“笔记本电脑”，价格 3000–8000 元，按销量倒序，取第 1 页 20 条。

import time, json, hashlib, requests class JdProSearch: def __init__(self, key, secret): self.key, self.secret, self.url = key, secret, \ "https://api.jd.com/routerjson" def sign(self, p): s = self.secret for k, v in sorted(p.items()): if v != '' and v is not None: s += f"{k}{v}" return hashlib.md5((s + self.secret).encode()).hexdigest().upper() def search(self, keyword, page=1, size=20, sort='sale_desc', price_min=None, price_max=None): biz = {"keyword": keyword, "pageIndex": page, "pageSize": size} if price_min: biz["priceMin"] = price_min if price_max: biz["priceMax"] = price_max if sort: biz["sortName"] = sort params = { "method": "jd.union.open.goods.search", "app_key": self.key, "timestamp": time.strftime("%Y-%m-%d %H:%M:%S"), "format": "json", "v": "1.0", "param_json": json.dumps(biz, ensure_ascii=False) } params["sign"] = self.sign(params) rsp = requests.post(self.url, data=params, timeout=15).json() if "error_response" in rsp: raise RuntimeError(rsp["error_response"]["zh_desc"]) data = json.loads(rsp["jd_union_open_goods_search_response"]["result"]) return data["data"]["goodsList"], data["totalCount"] # 调用 api = JdProSearch("你的AppKey", "你的AppSecret") goods, total = api.search("笔记本电脑", price_min=3000, price_max=8000) print("共", total, "件商品，本页返回", len(goods)) for g in goods[:3]: print(g["skuId"], g["skuName"], "¥", g["price"])

返回字段中skuId、price、promotionPrice、shopName、mainImageUrl最常用；如要拿券后价，再加couponInfo字段即可。

五、高级检索技巧

1. 关键词组合：空格代表“且”，+代表“或”，-代表排除；例如
   笔记本 +游戏本 -二手能过滤掉二手商品。

2. 类目锁定：先通过category.search接口把三级类目 ID 取回来，再拼到categoryId参数，可把搜索范围缩小 70 % 以上。

3. 价格/佣金双重筛选：选品库场景常用price_min、price_max、commissionShare同时过滤，快速找到“低价高佣”商品。

4. 排序权重：

   • sale_desc走量爆款；

   • price_asc找低价货源；

   • hot_desc结合京东“热度”算法，适合发现潜力新品。

5. 翻页限制：京东只返回前 50 页（约 1000 条），深度分页会被截断；需要全量数据时，按“价格段 + 销量段”多次拆分即可。

六、反爬与容错

1. 联盟接口本身对 IP 不做强校验，但返回包含有trace_id，频繁 4xx 错误会被降权。

2. 建议：单 IP QPS≤10，失败重试 3 次后休眠 5 s；出现40005 sign verify fail多数为时间戳偏差，校准时钟即可。

3. 数据落地前，对price、promotionPrice做浮点两位截断；skuName做 128 位截断并过滤 emoji，可节省 30 % 存储。

七、典型业务落地

• 比价系统：每 30 min 拉一次 Top 5000 SKU，按skuId更新价格、促销、券额，写入 Redis 供前端实时查询。

• 选品后台：运营输入关键词 → 接口返回列表 → 勾选后加入“本地商品池”，同时记录佣金率与历史价，辅助决策。

• **社群返利机器人：监听用户发来的关键词 → 实时搜索 → 返回二合一推广链接 + 券信息，整个过程 < 1.5 s。

八、常见错误码速查

九、小结

item_search_pro 本质就是京东官方关键词搜索能力的代理封装。真正的门槛只有两步：

1. 把签名算对；

2. 把业务参数拼细（类目、价格、排序、优惠券）。

跑通上述最小代码后，再结合自己的 SKU 池、价格策略与缓存机制，就能在比价、选品、返利、数据分析等场景中快速上线。祝你“搜”得开心，单量长虹！