京东关键词item_search-按关键字搜索京东商品

京东关键词搜索（item_search）技术实现指南：合规 API 调用 + 数据运营实战

京东商品关键词搜索（item_search）是电商技术从业者核心需求之一，需优先采用京东官方开放平台 API或合规第三方数据服务（避免直接爬取官网，存在反爬封禁、法律风险）。本文将从「接口接入、多语言代码实现、数据提取、运营落地」四个维度，提供可直接落地的技术方案，覆盖选品、定价、库存监控等核心场景。

一、合规前提：京东 item_search 接口类型选择

接口类型	适用场景	合规性	调用限制	核心优势
京东开放平台「商品搜索接口」	自有店铺运营、官方数据对接	100% 合规	需申请 AppKey，有 QPS 限制	数据权威、字段完整（含库存 / 销量 / 优惠券）
京东联盟 API「商品搜索接口」	联盟推广、选品数据分析	100% 合规	需联盟账号备案	支持佣金比例、推广链接提取
第三方合规数据平台 API	快速验证需求、非店铺运营	合规（需资质）	按调用次数计费	接入门槛低、无需复杂备案

⚠️ 重要提醒：京东官网（jd.com）禁止未经授权的爬虫抓取，轻则 IP 封禁，重则涉及《反不正当竞争法》，优先选择上述合规接口！

二、京东开放平台 item_search 接口接入流程（推荐）

1. 前期准备

注册京东开放平台开发者账号：https://open.jd.com/

创建应用，申请「商品搜索」接口权限（需完成企业 / 个人资质认证）

获取核心凭证：AppKey、AppSecret（在应用管理页查看）

接口文档参考：京东开放平台 - 商品搜索接口（v3.0）：https://open.jd.com/doc/api.htm?apiId=34526

2. 核心接口参数（item_search）

参数名	类型	必选	说明	示例值
keyword	String	是	搜索关键词（支持多关键词组合，空格分隔）	「无线蓝牙耳机 主动降噪」
page	Int	否	页码（默认 1，最大支持 50 页）	1
page_size	Int	否	每页条数（默认 30，最大 50）	50
sort_type	String	否	排序方式（price_asc：低价；price_desc：高价；sales_desc：销量；review_desc：评价）	sales_desc
cat	String	否	商品分类 ID（可通过「分类列表接口」获取）	6528（手机配件类）
is_promotion	Int	否	是否只显示促销商品（1：是；0：否）	1

3. 签名算法（京东 API 核心验证步骤）

京东 API 采用HMAC-SHA256签名机制，步骤如下：

按参数名 ASCII 升序排列所有请求参数（含公共参数：app_key、timestamp、format 等）

拼接为「key=value&key=value」格式的字符串（无 url 编码）

用AppSecret作为密钥，对拼接字符串进行 HMAC-SHA256 加密，得到签名值（sign）

将签名值加入请求参数，以 GET/POST 方式提交请求

公共参数说明：必须包含app_key、timestamp（格式：yyyy-MM-dd HH:mm:ss）、format（默认 json）、v（接口版本，如 3.0）、sign（签名值）

三、多语言代码实现（item_search 接口调用）

以下代码基于「京东开放平台商品搜索接口 v3.0」，包含 Python/Java/PHP 三种主流语言，直接替换AppKey、AppSecret即可运行。

1. Python 实现（推荐，含数据解析）

python

运行

import requests
import hashlib
import hmac
import time
from urllib.parse import urlencode, quote_plus

class JDItemSearch:
    def __init__(self, app_key, app_secret):
        self.app_key = app_key
        self.app_secret = app_secret
        self.url = "https://api.jd.com/routerjson"  # 京东API网关地址

    # 生成签名
    def generate_sign(self, params):
        # 按ASCII升序排序参数
        sorted_params = sorted(params.items(), key=lambda x: x[0])
        # 拼接为key=value字符串（无url编码）
        sign_str = "&".join([f"{k}={v}" for k, v in sorted_params])
        # HMAC-SHA256加密
        hmac_obj = hmac.new(self.app_secret.encode("utf-8"), sign_str.encode("utf-8"), hashlib.sha256)
        return hmac_obj.hexdigest().upper()

    # 执行搜索
    def search(self, keyword, page=1, page_size=30, sort_type="sales_desc"):
        # 公共参数
        params = {
            "app_key": self.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
        }
        # 生成签名
        params["sign"] = self.generate_sign(params)
        # 发送请求
        response = requests.get(self.url, params=params, timeout=10)
        if response.status_code == 200:
            return response.json()
        else:
            raise Exception(f"请求失败：状态码{response.status_code}，响应内容{response.text}")

# ------------------- 实战调用 -------------------
if __name__ == "__main__":
    # 替换为你的AppKey和AppSecret
    APP_KEY = "你的京东开放平台AppKey"
    APP_SECRET = "你的京东开放平台AppSecret"
    
    jd_search = JDItemSearch(APP_KEY, APP_SECRET)
    # 搜索「无线蓝牙耳机 主动降噪」，按销量排序，第1页，50条/页
    result = jd_search.search(
        keyword="无线蓝牙耳机 主动降噪",
        page=1,
        page_size=50,
        sort_type="sales_desc"
    )
    
    # 解析核心数据（选品/运营关键字段）
    goods_list = result.get("jd_union_open_goods_search_response", {}).get("result", {}).get("data", [])
    for goods in goods_list:
        print("="*50)
        print(f"商品ID：{goods.get('skuId')}")
        print(f"商品标题：{goods.get('goodsName')}")
        print(f"售价：{goods.get('price')}元")
        print(f"销量：{goods.get('salesCount')}件")
        print(f"佣金比例：{goods.get('commissionRatio')}%")
        print(f"库存状态：{'有货' if goods.get('stock') > 0 else '缺货'}")
        print(f"店铺名称：{goods.get('shopName')}")
        print(f"优惠券金额：{goods.get('couponInfo', {}).get('discount', 0)}元")

2. Java 实现（含签名工具类）

java

运行

import org.apache.commons.codec.digest.HmacUtils;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;
import com.alibaba.fastjson.JSONObject;
import java.util.*;

public class JDItemSearch {
    private static final String APP_KEY = "你的京东开放平台AppKey";
    private static final String APP_SECRET = "你的京东开放平台AppSecret";
    private static final String API_URL = "https://api.jd.com/routerjson";

    // 生成签名
    private static String generateSign(Map< String, String > params) {
        // 按ASCII升序排序
        List< Map.Entry< String, String >> entryList = new ArrayList<  >(params.entrySet());
        entryList.sort(Map.Entry.comparingByKey());
        // 拼接字符串
        StringBuilder signStr = new StringBuilder();
        for (Map.Entry< String, String > entry : entryList) {
            signStr.append(entry.getKey()).append("=").append(entry.getValue()).append("&");
        }
        signStr.deleteCharAt(signStr.length() - 1);
        // HMAC-SHA256加密
        return new HmacUtils("HmacSHA256", APP_SECRET).hmacHex(signStr.toString()).toUpperCase();
    }

    // 搜索商品
    public static JSONObject search(String keyword, int page, int pageSize, String sortType) throws Exception {
        Map< String, String > params = new HashMap<  >();
        // 公共参数
        params.put("app_key", APP_KEY);
        params.put("method", "jd.union.open.goods.search");
        params.put("format", "json");
        params.put("v", "3.0");
        params.put("timestamp", new SimpleDateFormat("yyyy-MM-dd HH:mm:ss").format(new Date()));
        // 业务参数
        params.put("keyword", keyword);
        params.put("page", String.valueOf(page));
        params.put("page_size", String.valueOf(pageSize));
        params.put("sort_type", sortType);
        // 生成签名
        params.put("sign", generateSign(params));

        // 构建请求URL
        StringBuilder urlBuilder = new StringBuilder(API_URL).append("?");
        for (Map.Entry< String, String > entry : params.entrySet()) {
            urlBuilder.append(entry.getKey()).append("=").append(URLEncoder.encode(entry.getValue(), "UTF-8")).append("&");
        }
        String url = urlBuilder.deleteCharAt(urlBuilder.length() - 1).toString();

        // 发送请求
        try (CloseableHttpClient client = HttpClients.createDefault()) {
            HttpGet request = new HttpGet(url);
            return JSONObject.parseObject(EntityUtils.toString(client.execute(request).getEntity()));
        }
    }

    // 主函数调用
    public static void main(String[] args) throws Exception {
        JSONObject result = search("无线蓝牙耳机 主动降噪", 1, 50, "sales_desc");
        // 解析核心字段
        JSONArray goodsList = result.getJSONObject("jd_union_open_goods_search_response")
                .getJSONObject("result")
                .getJSONArray("data");
        for (Object obj : goodsList) {
            JSONObject goods = (JSONObject) obj;
            System.out.println("商品ID：" + goods.getString("skuId"));
            System.out.println("商品标题：" + goods.getString("goodsName"));
            System.out.println("售价：" + goods.getBigDecimal("price") + "元");
            System.out.println("销量：" + goods.getIntValue("salesCount") + "件");
            System.out.println("库存状态：" + (goods.getIntValue("stock") > 0 ? "有货" : "缺货"));
            System.out.println("---------------------");
        }
    }
}

3. PHP 实现（简洁版）

php

运行

< ?php
class JDItemSearch {
    private $appKey = "你的京东开放平台AppKey";
    private $appSecret = "你的京东开放平台AppSecret";
    private $apiUrl = "https://api.jd.com/routerjson";

    // 生成签名
    private function generateSign($params) {
        ksort($params); // 按ASCII升序排序
        $signStr = http_build_query($params, '', '&');
        return strtoupper(hash_hmac('sha256', $signStr, $this- >appSecret));
    }

    // 搜索商品
    public function search($keyword, $page = 1, $pageSize = 30, $sortType = "sales_desc") {
        $params = [
            'app_key' => $this->appKey,
            'method' => 'jd.union.open.goods.search',
            'format' => 'json',
            'v' => '3.0',
            'timestamp' => date('Y-m-d H:i:s'),
            'keyword' => $keyword,
            'page' => (string)$page,
            'page_size' => (string)$pageSize,
            'sort_type' => $sortType
        ];
        $params['sign'] = $this->generateSign($params);

        // 发送请求
        $url = $this->apiUrl . '?' . http_build_query($params);
        $response = file_get_contents($url);
        return json_decode($response, true);
    }
}

// 调用示例
$jdSearch = new JDItemSearch();
$result = $jdSearch->search("无线蓝牙耳机 主动降噪", 1, 50, "sales_desc");

// 解析数据
$goodsList = $result['jd_union_open_goods_search_response']['result']['data'] ?? [];
foreach ($goodsList as $goods) {
    echo "商品ID：" . $goods['skuId'] . "n";
    echo "商品标题：" . $goods['goodsName'] . "n";
    echo "售价：" . $goods['price'] . "元n";
    echo "销量：" . $goods['salesCount'] . "件n";
    echo "-----------------n";
}
?>

四、数据提取与运营实战（选品 / 定价 / 库存）

调用接口后，核心是从返回数据中提取运营关键字段，并落地到业务场景：

1. 核心字段提取（JSON 结构示例）

json

{
  "jd_union_open_goods_search_response": {
    "result": {
      "data": [
        {
          "skuId": "100062888888", // 商品唯一ID（关键）
          "goodsName": "无线蓝牙耳机 主动降噪...", // 商品标题
          "price": 299.00, // 现价
          "originalPrice": 399.00, // 原价
          "salesCount": 12560, // 累计销量
          "reviewCount": 3280, // 评价数
          "stock": 568, // 库存数量
          "shopName": "XX官方旗舰店", // 店铺名称
          "shopType": "JD_MALL", // 店铺类型（京东自营/第三方）
          "commissionRatio": 15.00, // 佣金比例（联盟API特有）
          "couponInfo": {
            "discount": 50, // 优惠券金额
            "startTime": "2024-01-01", // 优惠券生效时间
            "endTime": "2024-01-31" // 优惠券失效时间
          },
          "categoryId": "6528", // 分类ID
          "brandName": "XX品牌" // 品牌名称
        }
      ]
    }
  }
}

2. 运营场景落地

（1）选品分析（高销量低竞争）

筛选条件：salesCount > 5000（高销量）、reviewCount/salesCount < 0.3（低评价占比，竞争小）、couponInfo.discount > 30（有大额优惠券）

代码示例（Python）：

python

运行

# 筛选高销量、大额券、低竞争商品
high_potential_goods = []
for goods in goods_list:
    sales = goods.get('salesCount', 0)
    review = goods.get('reviewCount', 0)
    coupon = goods.get('couponInfo', {}).get('discount', 0)
    # 筛选条件
    if sales > 5000 and coupon > 30 and (review/sales < 0.3 if sales > 0 else False):
        high_potential_goods.append({
            'skuId': goods['skuId'],
            'goodsName': goods['goodsName'],
            'price': goods['price'],
            'sales': sales,
            'coupon': coupon
        })
print("高潜力选品：", high_potential_goods)

（2）定价策略参考

提取同类商品价格区间：min_price = min([g['price'] for g in goods_list])、max_price = max([g['price'] for g in goods_list])

定价建议：若为第三方店铺，定价可低于区间均值 5%-10%；若为自营，可参考区间中位数，搭配优惠券提升竞争力。

（3）库存监控

实时监控爆款库存：for goods in goods_list: if goods['salesCount'] > 10000: print(f"爆款{goods['goodsName']}库存：{goods['stock']}")

触发预警：当库存goods['stock'] < 100时，发送邮件 / 短信提醒补货。

五、常见问题与解决方案

问题类型	原因分析	解决方案
签名错误（sign invalid）	参数排序错误、AppSecret 错误	严格按 ASCII 升序排序参数，核对 AppSecret 是否正确
调用频率限制（QPS 超限）	超过平台规定的 QPS 上限	1. 申请提高 QPS；2. 加入请求重试机制（带延迟）；3. 缓存重复搜索结果
数据返回为空	关键词无匹配商品、权限不足	1. 优化关键词（更具体）；2. 检查接口权限是否开通
库存 / 销量字段缺失	接口版本过低	升级到 v3.0 及以上版本，确认接口权限包含「销量 / 库存」字段

六、合规与风险提示

禁止使用爬虫爬取京东官网（jd.com）、京东超市等非开放平台页面，仅允许调用官方开放平台或合规第三方 API。

数据使用范围：仅用于自身店铺运营、选品分析，不得泄露、转售他人数据，遵守《京东开放平台服务协议》。

接口调用规范：严格遵守 QPS 限制，避免高频次恶意调用，否则会导致 AppKey 封禁。

审核编辑 黄宇