京东关键词搜索 item_search_pro API 接口获取数据——代码逐行解析

最新推荐文章于 2026-01-09 22:02:53 发布

原创最新推荐文章于 2026-01-09 22:02:53 发布 · 314 阅读

7 ·

CC 4.0 BY-SA版权

文章标签：

#python #开发语言

京东api 专栏收录该内容

8 篇文章

订阅专栏

说明：item_search_pro 并非京东官方文档里的接口名，而是第三方/服务商对「关键词搜索商品」能力的统一封装，内部实际调用的是京东联盟开放平台的 jd.union.open.goods.search（联盟版）或 routerjson 下的 item_search（自营版）。下文以「联盟版」为例，给出一份可直接落地的 Python 实现，并逐行拆解关键代码，方便你二次封装或排查签名、分页、字段裁剪等常见坑点。

一、接口基本信息

要点	取值
请求地址	`https://api.jd.com/routerjson`
方法名	`jd.union.open.goods.search`
请求方式	`POST` / `x-www-form-urlencoded`
数据格式	`JSON`
签名算法	参数名 ASCII 升序 + 首尾拼 `app_secret` 再 `MD5` 转大写
返回核心字段	`skuId、skuName、price、promotionPrice、commissionShare、shopName、mainImageUrl`
分页上限	50 页（≈ 1000 条）

二、完整源码（可直接跑）

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
import time, json, hashlib, requests, os

class JdItemSearchPro:
    """
    京东关键词搜索 item_search_pro 联盟版实现
    官方文档：https://union.jd.com/openplatform/api/10421
    """
    def __init__(self, app_key: str, app_secret: str):
        self.app_key = app_key
        self.app_secret = app_secret
        self.base_url = "https://api.jd.com/routerjson"

    # —— ① 生成京东签名 —— #
    def _sign(self, params: dict) -> str:
        """
        1. 过滤空值
        2. 按 key 升序排列
        3. 首尾拼 app_secret 后 MD5→大写
        """
        params = {k: v for k, v in params.items() if v not in ("", None)}
        src = self.app_secret
        for k, v in sorted(params.items()):
            src += f"{k}{v}"
        src += self.app_secret
        return hashlib.md5(src.encode("utf-8")).hexdigest().upper()

    # —— ② 业务方法：关键词搜索 —— #
    def search(self, keyword: str,
               page: int = 1,
               page_size: int = 20,
               price_min: int = None,
               price_max: int = None,
               sort: str = "sale_desc") -> dict:
        """
        :param keyword:   搜索关键词，如“笔记本电脑”
        :param page:      页码，1 开始
        :param page_size: 每页条数，最大 50
        :param price_min: 最低价（元）
        :param price_max: 最高价（元）
        :param sort:      sale_desc | price_asc | price_desc | hot_desc
        :return:          {"total":100,"items":[{},{},...]}
        """
        # 1）业务参数
        biz = {
            "keyword": keyword,
            "pageIndex": page,
            "pageSize": page_size,
            "sortName": sort
        }
        if price_min is not None:
            biz["priceMin"] = price_min
        if price_max is not None:
            biz["priceMax"] = price_max

        # 2）公共参数
        params = {
            "method": "jd.union.open.goods.search",
            "app_key": self.app_key,
            "timestamp": time.strftime("%Y-%m-%d %H:%M:%S"),
            "format": "json",
            "v": "1.0",
            "param_json": json.dumps(biz, ensure_ascii=False)
        }

        # 3）生成签名并追加
        params["sign"] = self._sign(params)

        # 4）发请求
        rsp = requests.post(self.base_url,
                            data=params,
                            headers={"Content-Type": "application/x-www-form-urlencoded"},
                            timeout=15)
        rsp.raise_for_status()
        root = rsp.json()

        # 5）错误处理
        if "error_response" in root:
            err = root["error_response"]
            raise RuntimeError(f'{err["code"]} {err.get("zh_desc") or err.get("en_desc")}')

        # 6）提取商品列表
        data_json = json.loads(root["jd_union_open_goods_search_response"]["result"])
        if data_json["code"] != 200:
            raise RuntimeError(data_json["message"])
        return {
            "total": data_json["totalCount"],
            "page": page,
            "page_size": page_size,
            "items": data_json["data"]["goodsList"]
        }

# —— ③ 快速体验 —— #
if __name__ == "__main__":
    # 换成你的联盟 APP 凭证
    api = JdItemSearchPro(app_key=os.getenv("JD_APPKEY"),
                          app_secret=os.getenv("JD_SECRET"))
    ret = api.search("手机", page=1, page_size=10, price_min=1000, price_max=5000)
    print(f'共 {ret["total"]} 件商品，本页返回 {len(ret["items"])} 条')
    for i, g in enumerate(ret["items"], 1):
        print(i, g["skuId"], g["skuName"], "¥", g["price"])

三、逐行代码拆解

行号区间	关键知识点	说明
① `_sign`	签名算法	京东全系接口统一规则：过滤空值→ASCII 升序→首尾拼 `app_secret`→MD5 大写；任何多余空格或大小写错误都会报 `40005` 。
② `biz` 参数	业务参数	`keyword/pageIndex/pageSize` 为必传；价格区间、排序、类目 ID、品牌 ID 等均为可选。
③ `param_json`	嵌套 JSON	京东要求把业务参数整体当字符串放进 `param_json`，并不再二次排序；否则同样 `40005` 。
④ `timestamp`	时间格式	必须 `YYYY-MM-DD HH:MM:SS`，不带毫秒；Linux 可直接 `time.strftime` 生成。
⑤ 返回解析	三层嵌套	`routerjson→jd_union_open_goods_search_response→result` 才是业务 JSON，官方用了字符串再包一层，记得 `json.loads` 。
⑥ 分页陷阱	50 页上限	深度翻页会被截断；想拉全量请按“价格段+销量段”多次拆分再合并。
⑦ 字段裁剪	`fields`	联盟支持 `fields` 参数，只返回需要的列，节省 30 % 流量；示例未开启，可自行追加。

四、常见报错速查

错误码	中文描述	排查思路
40005	签名验证失败	1. 空值未过滤 2. 时间戳格式错 3. `param_json` 被二次排序
40006	应用不存在	`AppKey` 写错或应用未上线
40010	无权限	未在联盟后台申请“商品搜索” API 包
50001	关键词为空	前端未做非空校验