淘宝关键词搜索 API（核心接口：taobao.tbk.item.search）是实现商品搜索、市场分析的核心工具，调用需完成「参数构造→签名生成→HTTP 请求→数据解析」全流程。以下是基于 Python 的完整调用教程，含通用代码、参数说明、避坑要点，适配新手快速上手。
一、前置准备
1. 核心信息获取
调用前需先在淘宝开放平台完成：
- 联系博主，企业 / 个人实名认证，创建应用并获取
App Key和App Secret（接口调用的身份凭证）； - 申请
taobao.tbk.item.search接口权限（审核周期 1-3 个工作日）； - 确认接口请求地址：固定为
https://eco.taobao.com/router/rest。
2. 环境依赖
安装必备 Python 库（仅需请求库）：
bash
运行
pip install requests
二、完整调用代码（可直接复用）
以下代码包含「签名生成、参数构造、接口调用、数据解析」全逻辑，适配绝大多数搜索场景：
python
运行
import requests import hashlib import time import json class TaobaoSearchAPI: """淘宝关键词搜索API调用类""" 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): """ 生成淘宝API签名（核心步骤，签名错误会直接调用失败） :param params: 接口请求参数（字典） :return: 加密后的签名字符串 """ # 1. 按参数名ASCII升序排序 sorted_params = sorted(params.items(), key=lambda x: x[0]) # 2. 拼接参数字符串（key+value） sign_str = "" for k, v in sorted_params: # 过滤空值，避免签名错误 if v is not None and v != "": sign_str += f"{k}{v}" # 3. 首尾拼接App Secret，MD5加密后转大写 sign_str = self.app_secret + sign_str + self.app_secret sign = hashlib.md5(sign_str.encode("utf-8")).hexdigest().upper() return sign def search(self, keyword, page_no=1, page_size=20, sort="sales_desc", start_price=None, end_price=None): """ 调用关键词搜索API :param keyword: 搜索关键词（必填，如"夏季纯棉T恤"） :param page_no: 页码，默认1（最大不超过总页数） :param page_size: 每页条数，默认20（最大100） :param sort: 排序方式，sales_desc=按销量降序，price_asc=按价格升序 :param start_price: 价格区间下限（如30） :param end_price: 价格区间上限（如100） :return: 解析后的商品数据 + 搜索元信息（总条数、页码） """ # 1. 构造基础参数（淘宝API固定要求） params = { "method": "taobao.tbk.item.search", # 接口名，固定值 "app_key": self.app_key, "timestamp": time.strftime("%Y-%m-%d %H:%M:%S"), # 时间戳（误差≤5分钟） "format": "json", # 返回格式，固定json "v": "2.0", # API版本，固定2.0 "sign_method": "md5", # 签名方式，固定md5 "q": keyword, # 搜索关键词 "page_no": page_no, "page_size": page_size, "sort": sort } # 2. 可选参数：价格区间（按需添加） if start_price: params["start_price"] = start_price if end_price: params["end_price"] = end_price # 3. 生成签名并添加到参数 params["sign"] = self._generate_sign(params) # 4. 发起GET请求（淘宝API仅支持GET） try: response = requests.get( url=self.api_url, params=params, timeout=10 # 超时时间，避免卡请求 ) response.encoding = "utf-8" result = response.json() except Exception as e: raise Exception(f"接口请求失败：{str(e)}") # 5. 解析返回数据 if result.get("code") != 0: # 调用失败，提取错误信息 error = result["resp_data"]["error_response"] raise Exception(f"API调用失败：{error['msg']}（错误码：{error['sub_code']}）") else: # 调用成功，格式化数据 data = result["resp_data"]["tbk_item_search_response"] meta = { "总商品数": data.get("total_results", 0), "当前页码": data.get("page_no", 1), "每页条数": data.get("page_size", 20), "总页数": data.get("max_page", 0) } # 提取核心商品信息 goods_list = [] for item in data.get("results", []): goods_list.append({ "商品ID": item.get("num_iid"), "标题": item.get("title"), "主图链接": item.get("pict_url"), "券后价": float(item.get("zk_final_price", 0)), "原价": float(item.get("reserve_price", 0)), "销量": item.get("sales", 0), "店铺名称": item.get("shop_title"), "是否天猫": item.get("is_tmall", False), "佣金比例": float(item.get("tk_rate", 0)) / 100, # 转小数（如20%→0.2） "商品链接": item.get("item_url") }) return meta, goods_list # ==================== 调用示例 ==================== if __name__ == "__main__": # 替换为你的App Key和App Secret APP_KEY = "你的App Key" APP_SECRET = "你的App Secret" # 初始化API调用类 taobao_api = TaobaoSearchAPI(APP_KEY, APP_SECRET) # 调用搜索接口（搜索"夏季纯棉T恤"，按销量排序，价格30-100元） try: meta_info, goods_data = taobao_api.search( keyword="夏季纯棉T恤", page_no=1, page_size=20, sort="sales_desc", start_price=30, end_price=100 ) # 打印结果 print("=== 搜索元信息 ===") print(json.dumps(meta_info, ensure_ascii=False, indent=2)) print("\n=== 商品列表（前3条）===") print(json.dumps(goods_data[:3], ensure_ascii=False, indent=2)) except Exception as e: print(f"调用失败：{str(e)}")
三、关键参数说明
| 参数名 | 是否必填 | 说明 | 示例 |
q |
是 | 搜索关键词（需 URL 编码，代码已自动处理） | "夏季纯棉 T 恤" |
page_no |
否 | 页码，默认 1 | 2 |
page_size |
否 | 每页条数，默认 20，最大 100 | 50 |
sort |
否 | 排序方式 | sales_desc（销量降序）、price_asc（价格升序） |
start_price/end_price |
否 | 价格区间 | start_price=30，end_price=100 |
is_tmall |
否 | 是否仅搜天猫商品 | true（仅天猫）、false（全部） |
四、调用结果示例
成功调用后返回格式化数据，示例如下：
json
=== 搜索元信息 === { "总商品数": 15600, "当前页码": 1, "每页条数": 20, "总页数": 780 } === 商品列表（前3条）=== [ { "商品ID": "689712345678", "标题": "2025夏季纯棉宽松T恤男 透气百搭休闲短袖", "主图链接": "https://img.alicdn.com/xxx.jpg", "券后价": 59.9, "原价": 99.0, "销量": 12500, "店铺名称": "XX男装旗舰店", "是否天猫": true, "佣金比例": 0.2, "商品链接": "https://detail.tmall.com/item.htm?id=689712345678" } ]
五、避坑核心要点
1. 签名错误（最常见问题）
- 确保参数按 ASCII 升序排序（不是中文拼音排序）；
- 时间戳格式必须为
YYYY-MM-DD HH:mm:ss，且与服务器时间误差≤5 分钟； - 拼接签名时 过滤空值（如 start_price 未传则不参与签名）；
- App Secret 首尾拼接，加密后转 大写（小写会判定签名错误）。
2. 限流与权限问题
- 普通应用 QPS 限制为 1（每秒最多 1 次调用），批量调用需加延迟：
运行
time.sleep(1) # 每次调用后休眠1秒
- 未申请接口权限会返回
isv.permission-denied错误，需在开放平台确认权限审核状态； - 个人账号每日调用配额有限（约 100 次），企业账号配额更高（1 万次 / 天）。
3. 数据解析注意事项
- 价格、佣金等字段返回为字符串，需转
float后计算； - 分页调用时，总页数 = 总商品数 / 每页条数，超过总页数会返回空列表；
- 部分字段（如
stock库存）需额外申请权限，未授权时返回null。
六、扩展场景适配
1. 批量分页获取全量数据
python
运行
# 循环获取前5页数据 all_goods = [] for page in range(1, 6): meta, goods = taobao_api.search(keyword="夏季纯棉T恤", page_no=page) all_goods.extend(goods) time.sleep(1) # 避免限流 print(f"共获取 {len(all_goods)} 条商品数据")
2. 仅搜索天猫商品
python
运行
meta, goods = taobao_api.search( keyword="夏季纯棉T恤", is_tmall=True # 新增该参数，仅返回天猫商品 )
七、其他语言适配思路
核心逻辑与 Python 一致，仅需调整语法：
- Java：用
TreeMap排序参数，MessageDigest生成 MD5 签名，OkHttp发起 GET 请求； - Go：用
url.Values构造参数，sort.Strings排序，crypto/md5加密； - Node.js：用
axios发起请求，Object.keys().sort()排序参数，crypto.createHash生成签名。
只要遵循「参数排序→签名生成→GET 请求→数据解析」的核心流程，即可在任意语言中实现调用。
