京东开放平台的item_search接口是按关键字搜索商品的核心工具，广泛应用于电商平台、比价系统、市场分析等场景。本文将全面讲解该接口的对接流程、使用技巧和最佳实践，帮助开发者快速掌握从入门到精通的全过程。
一、接口基础认知
二、对接前置准备
三、接口调用流程
四、代码实现示例（Python）
import requests
import hashlib
import time
import json
class JdSearchApi:
def __init__(self, app_key, app_secret):
self.app_key = app_key
self.app_secret = app_secret
self.url = "https://api.jd.com/routerjson" # 正式环境
# 沙箱环境：https://sandbox-api.jd.com/routerjson
def generate_sign(self, params):
"""生成签名"""
# 按参数名ASCII排序
sorted_params = sorted(params.items(), key=lambda x: x[0])
# 拼接参数
sign_str = ""
for key, value in sorted_params:
sign_str += f"{key}={value}&"
# 去除最后一个&，并拼接app_secret
sign_str = sign_str[:-1] + self.app_secret
# MD5加密并转为大写
sign = hashlib.md5(sign_str.encode()).hexdigest().upper()
return sign
def item_search(self, keyword, page=1, page_size=20,
category_id=None, price_min=None, price_max=None,
sort=None):
"""
搜索商品
:param keyword: 搜索关键字
:param page: 页码，默认1
:param page_size: 每页条数，默认20，最大50
:param category_id: 分类ID
:param price_min: 最低价格
:param price_max: 最高价格
:param sort: 排序方式，如"price_asc"、"price_desc"、"sale_desc"
:return: 搜索结果
"""
# 业务参数
biz_params = {
"keyword": keyword,
"pageIndex": page,
"pageSize": page_size
}
# 可选参数
if category_id:
biz_params["categoryId"] = category_id
if price_min is not None:
biz_params["priceMin"] = price_min
if price_max is not None:
biz_params["priceMax"] = price_max
if sort:
biz_params["sortName"] = sort
# 公共参数
params = {
"app_key": self.app_key,
"method": "jd.union.open.goods.search", # 京东商品搜索接口
"format": "json",
"v": "1.0",
"timestamp": time.strftime("%Y-%m-%d %H:%M:%S"),
"param_json": json.dumps(biz_params)
}
# 生成签名
params["sign"] = self.generate_sign(params)
try:
# 发送POST请求
response = requests.post(
self.url,
data=params,
headers={"Content-Type": "application/x-www-form-urlencoded"},
timeout=15
)
result = json.loads(response.text)
# 处理错误响应
if "error_response" in result:
error = result["error_response"]
return {
"success": False,
"error_code": error.get("code"),
"error_msg": error.get("zh_desc") or error.get("en_desc")
}
# 提取商品数据
if "jd_union_open_goods_search_response" in result:
data = result["jd_union_open_goods_search_response"]["result"]
data_json = json.loads(data)
if data_json.get("code") == 200:
return {
"success": True,
"total": data_json.get("totalCount"),
"page": page,
"page_size": page_size,
"items": data_json.get("data", {}).get("goodsList", [])
}
else:
return {
"success": False,
"error_msg": data_json.get("message", "搜索商品失败")
}
return {"success": False, "error_msg": "未知响应格式"}
except Exception as e:
return {"success": False, "error_msg": f"请求异常: {str(e)}"}
# 使用示例
if __name__ == "__main__":
# 替换为自己的app_key和app_secret
APP_KEY = "your_app_key"
APP_SECRET = "your_app_secret"
# 初始化API客户端
api = JdSearchApi(APP_KEY, APP_SECRET)
# 搜索"笔记本电脑"，第1页，每页20条，价格3000-8000元，按销量降序
result = api.item_search(
keyword="笔记本电脑",
page=1,
page_size=20,
price_min=3000,
price_max=8000,
sort="sale_desc"
)
if result["success"]:
print(f"共搜索到 {result['total']} 个商品")
print(f"第 {result['page']} 页，当前页 {len(result['items'])} 个商品")
# 打印前5个商品信息
for i, item in enumerate(result["items"][:5]):
print(f"\n商品 {i+1}:")
print(f"ID: {item.get('skuId')}")
print(f"标题: {item.get('skuName')}")
print(f"价格: {item.get('price')} 元")
print(f"促销价: {item.get('promotionPrice')} 元")
print(f"店铺: {item.get('shopName')}")
print(f"主图: {item.get('mainImageUrl')}")
else:
print(f"搜索失败: {result['error_msg']} (错误码: {result.get('error_code')})")