淘宝开放平台的item_search接口是按关键字搜索商品的核心工具，广泛应用于电商平台、比价系统、市场分析等场景。本文将全面讲解该接口的对接流程、使用技巧和最佳实践，帮助开发者快速掌握从入门到精通的全过程。
一、接口基础认知
二、对接前置准备
三、接口调用流程
四、代码实现示例（Python）
import requests
import hashlib
import time
import json
class TaobaoSearchApi:
def __init__(self, app_key, app_secret):
self.app_key = app_key
self.app_secret = app_secret
self.api_url = "https://eco.taobao.com/router/rest"
def generate_sign(self, params):
"""生成签名"""
# 按参数名ASCII排序
sorted_params = sorted(params.items(), key=lambda x: x[0])
# 拼接签名字符串
sign_str = self.app_secret
for key, value in sorted_params:
sign_str += f"{key}{value}"
sign_str += self.app_secret
# MD5加密并转为大写
sign = hashlib.md5(sign_str.encode()).hexdigest().upper()
return sign
def item_search(self, keyword, page=1, page_size=40, cat=None, price=None, sort=None):
"""
搜索商品
:param keyword: 搜索关键字
:param page: 页码，默认1
:param page_size: 每页条数，默认40，最大不超过100
:param cat: 分类ID
:param price: 价格区间，如"10-100"
:param sort: 排序方式，如"price_asc"（价格升序）、"sale_desc"（销量降序）
:return: 搜索结果
"""
# 公共参数
params = {
"app_key": self.app_key,
"method": "taobao.item_search",
"format": "json",
"v": "2.0",
"timestamp": time.strftime("%Y-%m-%d %H:%M:%S"),
"q": keyword,
"page": page,
"page_size": page_size
}
# 可选参数
if cat:
params["cat"] = cat
if price:
params["price"] = price
if sort:
params["sort"] = sort
# 生成签名
params["sign"] = self.generate_sign(params)
try:
# 发送请求
response = requests.get(self.api_url, params=params, 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("msg")
}
# 提取商品数据
search_result = result["item_search_response"]["items"]
return {
"success": True,
"total": search_result.get("total_results"),
"page": page,
"page_size": page_size,
"items": search_result.get("item")
}
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 = TaobaoSearchApi(APP_KEY, APP_SECRET)
# 搜索"手机"，第1页，每页20条，价格1000-3000元，按销量降序
result = api.item_search(
keyword="手机",
page=1,
page_size=20,
price="1000-3000",
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"标题: {item.get('title')}")
print(f"价格: {item.get('price')} 元")
print(f"销量: {item.get('sale')} 件")
print(f"商品ID: {item.get('num_iid')}")
print(f"详情页: {item.get('detail_url')}")
else:
print(f"搜索失败: {result['error_msg']}")