虾皮（Shopee）开放平台的item_search接口是根据关键词搜索商品列表的核心工具，适用于跨境电商选品、市场分析、多平台比价等场景。本文将全面讲解该接口的对接流程、参数配置、代码实现及最佳实践，帮助开发者系统掌握从入门到精通的全流程。
一、接口基础认知
二、对接前置准备
三、接口调用流程
四、代码实现示例（Python）
import requests
import hashlib
import time
import json
class ShopeeSearchApi:
def __init__(self, partner_id, partner_key, access_token=None, region="sg"):
self.partner_id = partner_id
self.partner_key = partner_key
self.access_token = access_token # 可选，公开搜索可无需
self.region = region # 区域代码：sg/my/th/id/tw等
self.base_url = f"https://{region}.api.shopee.com/api/v2/search_items/"
def generate_sign(self, params):
"""生成签名"""
# 1. 按参数名ASCII升序排序
sorted_params = sorted(params.items(), key=lambda x: x[0])
# 2. 拼接为key=value格式
sign_str = "".join([f"{k}={v}" for k, v in sorted_params])
# 3. 前缀添加partner_key
sign_str = self.partner_key + sign_str
# 4. SHA256加密
sign = hashlib.sha256(sign_str.encode()).hexdigest()
return sign
def item_search(self, keyword, page=1, limit=20, **kwargs):
"""
搜索商品列表
:param keyword: 搜索关键词（必填）
:param page: 页码，默认1
:param limit: 每页条数，默认20，最大100
:param kwargs: 可选参数（price_min, price_max, sort_by等）
:return: 搜索结果
"""
# 1. 组装基础参数
params = {
"partner_id": self.partner_id,
"timestamp": int(time.time()), # 秒级时间戳
"keyword": keyword,
"page": page,
"limit": limit
}
# 2. 添加可选参数
if self.access_token:
params["access_token"] = self.access_token
params.update(kwargs)
# 3. 生成签名
params["sign"] = self.generate_sign(params)
try:
# 4. 发送GET请求
response = requests.get(
url=self.base_url,
params=params,
timeout=15
)
response.raise_for_status()
result = response.json()
# 5. 处理响应
if "error" in result and result["error"] != 0:
return {
"success": False,
"error_code": result["error"],
"error_msg": result.get("message", "未知错误")
}
return {
"success": True,
"total_count": result.get("total_count", 0),
"page": page,
"limit": limit,
"items": result.get("items", [])
}
except Exception as e:
return {
"success": False,
"error_msg": f"请求异常: {str(e)}"
}
# 使用示例
if __name__ == "__main__":
# 替换为实际参数
PARTNER_ID = 123456 # 开发者ID
PARTNER_KEY = "your_partner_key" # 开发者密钥
ACCESS_TOKEN = None # 公开搜索可无需
REGION = "sg" # 目标区域
# 初始化API客户端
api = ShopeeSearchApi(PARTNER_ID, PARTNER_KEY, ACCESS_TOKEN, REGION)
# 搜索"phone case"，第1页，20条/页，价格1-50新元，按销量降序
result = api.item_search(
keyword="phone case",
page=1,
limit=20,
price_min=100000, # 1.00新元（1e-5单位）
price_max=5000000, # 50.00新元
sort_by="sales" # 排序方式：sales-销量，price-价格，newest-最新
)
if result["success"]:
print(f"共搜索到 {result['total_count']} 个商品")
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('itemid')}")
print(f"标题: {item.get('name')}")
print(f"售价: {item.get('price')/100000} {item.get('currency')}")
print(f"销量: {item.get('historical_sold')}")
print(f"店铺: {item.get('shopid')}")
print(f"主图: {item.get('image')}")
else:
print(f"搜索失败: {result['error_msg']} (错误码: {result.get('error_code')})")