京东关键词搜索接口获取商品数据的实操指南

京东关键词搜索接口获取商品数据 实操指南

本指南聚焦京东开放平台合规接口（item_search基础版 / item_search_pro增强版），提供从账号准备→接口调用→数据解析→落地应用的全流程实操步骤，确保新手也能快速完成商品数据获取，适配电商选品、竞品分析、运营监控等核心场景。

一、 实操前置：合规准备与核心凭证获取

京东关键词接口属于官方开放接口，需完成开发者认证与权限申请，严禁未经授权的爬虫抓取，否则会面临 IP 封禁、法律风险。

1. 账号与权限准备（3 步完成）

步骤	操作内容	详细指引
1	注册京东开放平台开发者账号	访问 京东开放平台官网 → 点击 “开发者注册” → 选择个人 / 企业身份完成实名认证（企业需提供营业执照，个人需提供身份证）
2	创建应用并申请接口权限	登录后进入 “应用管理” → 点击 “创建应用” → 填写应用名称、用途（如 “商品数据采集与选品分析”） → 提交审核 → 审核通过后，在 “权限管理” 中申请 「商品搜索接口」（基础版item_search或增强版item_search_pro）
3	获取核心调用凭证	应用审核通过后，在 “应用详情” 页查看并保存 AppKey（应用唯一标识）、AppSecret（密钥） → 这两个参数是接口调用的核心，需妥善保管，避免泄露

注意：item_search_pro属于高级接口，需单独申请权限，审核周期比基础版长 1-2 个工作日。

2. 工具准备

开发环境：Python/Java/PHP（推荐 Python，代码简洁易上手）

依赖工具：Python 需安装requests库（pip install requests）、Java 需安装HttpClient、PHP 需开启curl扩展

辅助工具：Postman（接口调试）、Excel/MySQL（数据存储）

二、 核心配置：接口参数与签名算法（必掌握）

京东 API 采用 “参数 + 签名” 验证机制，签名错误是调用失败的最常见原因，需严格按以下步骤配置。

1. 接口参数分类（公共参数 + 业务参数）

（1） 公共参数（所有接口通用，必填）

参数名	取值要求	示例值
app_key	应用详情页获取的AppKey	1234567890
method	接口名称，基础版填jd.union.open.goods.search；增强版填jd.union.open.goods.search.pro	jd.union.open.goods.search
format	响应格式，固定为json	json
v	接口版本，基础版用3.0；增强版用4.0	3.0
timestamp	请求时间戳，格式yyyy-MM-dd HH:mm:ss（需与京东服务器时间一致，误差≤5 分钟）	2026-01-08 10:30:00
sign	签名值，通过 HMAC-SHA256 算法生成（下文详细说明）	8F7A6B5C4D3E2F1A9087654321ABCDEF

（2） 业务参数（关键词搜索核心参数）

参数名	必填	取值说明	示例值
keyword	是	搜索关键词，支持多词组合（空格分隔）	无线蓝牙耳机 主动降噪
page	否	页码，默认 1，基础版最大 50 页；增强版最大 100 页	1
page_size	否	每页条数，默认 30，基础版最大 50；增强版最大 100	50
sort_type	否	排序方式：price_asc（低价）、sales_desc（销量）、real_sales_desc（增强版实时销量）	sales_desc
price_from/price_to	否	价格区间筛选（增强版专属）	100/300

2. 签名算法实操（3 步生成，以 Python 为例）

签名是京东 API 的核心验证环节，步骤如下：

参数排序：将所有公共参数 + 业务参数，按参数名 ASCII 码升序排列（如app_key→format→keyword→method...）

拼接字符串：按 key=value&key=value 格式拼接排序后的参数（不进行 URL 编码）

HMAC-SHA256 加密：用AppSecret作为密钥，对拼接字符串进行加密，结果转大写即为sign

python

运行

 

# 签名生成示例代码（直接复用）
import hashlib
import hmac

def generate_sign(params, app_secret):
    # 步骤1：按参数名ASCII升序排序
    sorted_params = sorted(params.items(), key=lambda x: x[0])
    # 步骤2：拼接字符串
    sign_str = "&".join([f"{k}={v}" for k, v in sorted_params])
    # 步骤3：HMAC-SHA256加密并转大写
    sign = hmac.new(
        app_secret.encode("utf-8"),
        sign_str.encode("utf-8"),
        hashlib.sha256
    ).hexdigest().upper()
    return sign

 

三、 实战调用：Python 代码实现（基础版 / 增强版通用）

以下代码为可直接运行版本，只需替换APP_KEY、APP_SECRET即可完成调用，包含「接口请求 + 数据解析 + 结果输出」全流程。

1. 完整代码（基础版item_search）

python

运行

 

import requests
import hashlib
import hmac
import time

# ------------------- 配置区（替换为你的凭证） -------------------
APP_KEY = "你的AppKey"
APP_SECRET = "你的AppSecret"
API_URL = "https://api.jd.com/routerjson"  # 京东API网关地址

# ------------------- 签名生成函数 -------------------
def generate_sign(params, app_secret):
    sorted_params = sorted(params.items(), key=lambda x: x[0])
    sign_str = "&".join([f"{k}={v}" for k, v in sorted_params])
    sign = hmac.new(
        app_secret.encode("utf-8"),
        sign_str.encode("utf-8"),
        hashlib.sha256
    ).hexdigest().upper()
    return sign

# ------------------- 接口调用函数 -------------------
def jd_item_search(keyword, page=1, page_size=30, sort_type="sales_desc"):
    # 1. 组装参数（公共参数+业务参数）
    params = {
        "app_key": APP_KEY,
        "method": "jd.union.open.goods.search",  # 基础版接口名
        "format": "json",
        "v": "3.0",
        "timestamp": time.strftime("%Y-%m-%d %H:%M:%S", time.localtime()),
        "keyword": keyword,
        "page": str(page),
        "page_size": str(page_size),
        "sort_type": sort_type
    }
    # 2. 生成签名并加入参数
    params["sign"] = generate_sign(params, APP_SECRET)
    # 3. 发送请求
    try:
        response = requests.get(API_URL, params=params, timeout=10)
        response.raise_for_status()  # 抛出HTTP异常
        return response.json()
    except Exception as e:
        print(f"接口调用失败：{str(e)}")
        return None

# ------------------- 数据解析函数 -------------------
def parse_goods_data(result):
    """提取商品核心字段：ID、标题、价格、销量、库存"""
    goods_list = []
    if not result:
        return goods_list
    # 解析返回结果（按京东API格式）
    data = result.get("jd_union_open_goods_search_response", {}) 
                .get("result", {}) 
                .get("data", [])
    for goods in data:
        goods_info = {
            "sku_id": goods.get("skuId", ""),          # 商品唯一ID
            "title": goods.get("goodsName", ""),       # 商品标题
            "price": goods.get("price", 0.0),          # 现价
            "original_price": goods.get("originalPrice", 0.0),  # 原价
            "sales": goods.get("salesCount", 0),       # 累计销量
            "stock": goods.get("stock", 0),            # 库存
            "shop_name": goods.get("shopName", "")     # 店铺名称
        }
        goods_list.append(goods_info)
    return goods_list

# ------------------- 主函数调用 -------------------
if __name__ == "__main__":
    # 搜索关键词：无线蓝牙耳机 主动降噪，按销量排序
    result = jd_item_search(
        keyword="无线蓝牙耳机 主动降噪",
        page=1,
        page_size=50,
        sort_type="sales_desc"
    )
    # 解析数据
    goods_data = parse_goods_data(result)
    # 输出结果
    print(f"共获取 {len(goods_data)} 条商品数据n")
    for idx, goods in enumerate(goods_data[:5]):  # 打印前5条
        print(f"【{idx+1}】")
        print(f"商品ID：{goods['sku_id']}")
        print(f"标题：{goods['title']}")
        print(f"价格：{goods['price']}元（原价：{goods['original_price']}元）")
        print(f"销量：{goods['sales']} 库存：{goods['stock']}")
        print(f"店铺：{goods['shop_name']}n")

 

2. 增强版item_search_pro适配修改

只需修改两处即可切换到增强版：

接口名改为 method": "jd.union.open.goods.search.pro

接口版本改为 v": "4.0

可选添加增强版参数（如price_from、price_to、brand_id）

四、 数据落地：清洗、存储与应用

调用接口获取数据后，需进行数据清洗→存储→业务应用，才能转化为运营价值。

1. 数据清洗（解决 3 个常见问题）

去重：以sku_id为唯一标识，剔除重复商品（分页调用易出现重复）

过滤无效数据：删除stock=0（无库存）、price=0（价格异常）的商品

字段标准化：统一价格格式（保留 2 位小数）、截取过长标题（避免存储溢出）

python

运行

 

# 数据清洗示例代码
def clean_goods_data(goods_list):
    cleaned = []
    sku_ids = set()  # 用于去重
    for goods in goods_list:
        sku = goods["sku_id"]
        if sku in sku_ids or goods["stock"] <= 0 or goods["price"] <= 0:
            continue
        # 价格标准化
        goods["price"] = round(float(goods["price"]), 2)
        goods["original_price"] = round(float(goods["original_price"]), 2)
        # 标题截取（前50字）
        goods["title"] = goods["title"][:50] + "..." if len(goods["title"]) > 50 else goods["title"]
        sku_ids.add(sku)
        cleaned.append(goods)
    return cleaned

 

2. 数据存储（2 种常用方式）

存储方式	适用场景	操作代码示例
Excel	小批量数据、选品清单导出	使用pandas库：import pandas as pd; pd.DataFrame(cleaned_data).to_excel("京东商品数据.xlsx", index=False)
MySQL	大批量数据、长期监控	使用pymysql库，创建数据表后批量插入（参考前文item_search_pro代码中的save_to_db函数）

3. 业务应用（3 个核心场景）

选品分析：筛选sales>5000、price在目标区间的商品，统计热销规格

竞品监控：定期调用接口，对比竞品价格、销量变化，触发调价 / 补货预警

库存管理：监控爆款商品库存，当stock<100时发送邮件 / 短信提醒

五、 常见问题与排障指南（避坑必备）

问题现象	原因分析	解决方案
签名错误（sign invalid）	1. 参数未按 ASCII 升序排序；2. AppSecret 错误；3. timestamp 格式错误	1. 检查参数排序逻辑；2. 核对 AppSecret 是否与应用一致；3. 确保时间格式为yyyy-MM-dd HH:mm:ss
权限不足（403 Forbidden）	未申请对应接口权限，或应用审核未通过	登录开放平台，在 “权限管理” 中确认已申请item_search/item_search_pro权限
数据返回为空	1. 关键词无匹配商品；2. 页码超过最大限制；3. 筛选条件过严	1. 优化关键词（更宽泛）；2. 检查页码是否≤50（基础版）/100（增强版）；3. 放宽价格、品牌等筛选条件
调用频率超限（429 Too Many Requests）	超过平台 QPS 限制（通常基础版 10QPS，增强版 20QPS）	1. 调用后添加延迟（time.sleep(1)）；2. 申请提高 QPS；3. 缓存重复搜索结果

六、 合规与风险提示

仅使用官方开放接口：严禁爬取京东官网（jd.com）数据，仅可调用京东开放平台 / 京东联盟 API

数据使用边界：采集的数据仅用于自身运营分析，不得转售、泄露或用于商业竞争

凭证安全：AppKey和AppSecret避免上传至代码仓库（如 GitHub），可通过环境变量注入

审核编辑 黄宇