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

一、接口定位

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

理解这一点后，后面的"实战"就三件事：

拿到合法调用身份（App-Key / Secret / Access-Token）
按业务场景拼参数、算签名
对 JSON 结果做字段裁剪与落库

二、账号与权限

注册「京东联盟」或「京东开放平台」→ 创建应用 → 审核通过后会拿到

App-Key、App-Secret；联盟版还需要备案推广位，才能回传佣金字段。
沙箱测试：联盟后台提供在线调试窗，先勾选"仅看返回字段"，把必填参数跑通后再上代码。
配额：免费账号默认 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 条。

python 复制代码

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 字段即可。

五、高级检索技巧

关键词组合：空格代表"且"，+ 代表"或"，- 代表排除；例如
笔记本 +游戏本 -二手 能过滤掉二手商品。
类目锁定：先通过 category.search 接口把三级类目 ID 取回来，再拼到 categoryId 参数，可把搜索范围缩小 70 % 以上。
价格/佣金双重筛选：选品库场景常用 price_min、price_max、commissionShare 同时过滤，快速找到"低价高佣"商品。
排序权重：
- sale_desc 走量爆款；
- price_asc 找低价货源；
- hot_desc 结合京东"热度"算法，适合发现潜力新品。
翻页限制：京东只返回前 50 页（约 1000 条），深度分页会被截断；需要全量数据时，按"价格段 + 销量段"多次拆分即可。

六、反爬与容错

联盟接口本身对 IP 不做强校验，但返回包含有 trace_id，频繁 4xx 错误会被降权。
建议：单 IP QPS≤10，失败重试 3 次后休眠 5 s；出现 40005 sign verify fail 多数为时间戳偏差，校准时钟即可。
数据落地前，对 price、promotionPrice 做浮点两位截断；skuName 做 128 位截断并过滤 emoji，可节省 30 % 存储。

七、典型业务落地

比价系统 ：每 30 min 拉一次 Top 5000 SKU，按 skuId 更新价格、促销、券额，写入 Redis 供前端实时查询。
选品后台：运营输入关键词 → 接口返回列表 → 勾选后加入"本地商品池"，同时记录佣金率与历史价，辅助决策。
**社群返利机器人：监听用户发来的关键词 → 实时搜索 → 返回二合一推广链接 + 券信息，整个过程 < 1.5 s。

八、常见错误码速查

代码	含义	处理办法
40005	签名错误	检查空值、时区、MD5 大小写
40006	应用不存在	AppKey 写错或未上线
40010	无权限	未申请联盟"商品搜索"包
50001	关键词为空	前端过滤即可

九、小结

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

把签名算对；
把业务参数拼细（类目、价格、排序、优惠券）。

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