一、接口概述
item_cat_get 是淘宝开放平台提供的核心类目查询接口,用于获取淘宝/天猫平台的商品类目信息。该接口支持通过类目 ID 查询单个类目的详细信息,包括类目名称、层级、父类目、属性规则等关键数据,是商品发布、类目导航、数据分析等场景的基础能力。二、接口基本信息
表格
| 项目 | 说明 |
|---|---|
| 接口名称 | taobao.item.cat.get |
| 所属类目 | 商品类目 API |
| 请求方式 | HTTP POST / GET |
| 数据格式 | JSON |
| 授权方式 | 需要 App Key 和 App Secret |
| 调用频率 | 根据应用等级限制(一般 5000-10000 次/天) |
三、请求参数
3.1 公共参数(所有淘宝 API 通用)
表格
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
app_key | String | 是 | 应用 App Key |
method | String | 是 | API 接口名称,固定为 taobao.item.cat.get |
session | String | 条件必填 | 用户授权 Token(部分接口需要) |
timestamp | String | 是 | 时间戳,格式 yyyy-MM-dd HH:mm:ss |
format | String | 否 | 响应格式,默认 json,可选 xml |
v | String | 是 | API 版本号,如 2.0 |
sign | String | 是 | 签名,按淘宝签名规则生成 |
sign_method | String | 是 | 签名方法,固定为 hmac-md5 |
3.2 业务参数
表格
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
cid | Number | 是 | 类目 ID,淘宝标准类目 ID |
注意:cid为必填参数,需要传入具体的淘宝类目 ID(如50008163表示女装类目)。
四、签名生成规则
淘宝 API 采用 HMAC-MD5 签名算法,签名生成步骤如下:
4.1 参数排序
将所有请求参数(除
sign 外)按照参数名的 ASCII 码升序排列。4.2 拼接字符串
将排序后的参数按
key1value1key2value2... 格式拼接成字符串。4.3 生成签名
使用 HMAC-MD5 算法,以
App Secret 为密钥,对拼接后的字符串进行签名。4.4 签名示例(Python)
Python
import hashlibimport hmacdef generate_sign(params, app_secret):
# 1. 过滤空值和 sign 参数
filtered = {k: v for k, v in params.items() if v is not None and k != 'sign'}
# 2. 按 key 排序
sorted_params = sorted(filtered.items())
# 3. 拼接字符串
query = ''.join([f"{k}{v}" for k, v in sorted_params])
# 4. 首尾拼接 App Secret
sign_str = app_secret + query + app_secret # 5. HMAC-MD5 签名
sign = hmac.new(
app_secret.encode('utf-8'),
sign_str.encode('utf-8'),
hashlib.md5 ).hexdigest().upper()
return sign五、响应参数
5.1 成功响应示例
JSON
{
"item_cat_get_response": {
"item_cat": {
"cid": 50008163,
"parent_cid": 16,
"name": "女装/女士精品",
"is_parent": true,
"status": "normal",
"sort_order": 1,
"features": [
{
"attr_key": "cat_name",
"attr_value": "女装"
}
]
},
"request_id": "4e9p1x9z8z8z8z8z8z8z8z8z"
}}5.2 响应字段说明
表格
| 字段名 | 类型 | 说明 |
|---|---|---|
cid | Number | 类目 ID |
parent_cid | Number | 父类目 ID,0 表示根类目 |
name | String | 类目名称 |
is_parent | Boolean | 是否为父类目(有子类目则为 true) |
status | String | 类目状态:normal(正常)、deleted(已删除) |
sort_order | Number | 排序值 |
features | Array | 类目特性列表 |
5.3 错误响应示例
JSON
{
"error_response": {
"code": 40,
"msg": "Invalid arguments:cid",
"sub_code": "isv.invalid-parameter:cid",
"sub_msg": "cid 参数不合法",
"request_id": "4e9p1x9z8z8z8z8z8z8z8z8z"
}}六、完整调用示例
6.1 Python 调用示例
Python
import requestsimport timeimport jsonfrom urllib.parse import urlencode
APP_KEY = 'your_app_key'APP_SECRET = 'your_app_secret'API_URL = 'https://eco.taobao.com/router/rest'def call_item_cat_get(cid):
# 1. 准备参数
params = {
'app_key': APP_KEY,
'method': 'taobao.item.cat.get',
'timestamp': time.strftime('%Y-%m-%d %H:%M:%S'),
'format': 'json',
'v': '2.0',
'sign_method': 'hmac-md5',
'cid': cid }
# 2. 生成签名
params['sign'] = generate_sign(params, APP_SECRET)
# 3. 发送请求
response = requests.post(API_URL, data=params)
result = response.json()
return result# 调用示例:查询女装类目result = call_item_cat_get(50008163)print(json.dumps(result, indent=2, ensure_ascii=False))6.2 Java 调用示例
java
import java.util.*;import javax.crypto.Mac;import javax.crypto.spec.SecretKeySpec;import org.apache.commons.codec.binary.Hex;public class TaobaoApiClient {
private static final String APP_KEY = "your_app_key";
private static final String APP_SECRET = "your_app_secret";
private static final String API_URL = "https://eco.taobao.com/router/rest";
public static String generateSign(Map<String, String> params, String appSecret) throws Exception {
// 排序参数
List<String> keys = new ArrayList<>(params.keySet());
Collections.sort(keys);
// 拼接字符串
StringBuilder sb = new StringBuilder();
sb.append(appSecret);
for (String key : keys) {
String value = params.get(key);
if (value != null && !value.isEmpty()) {
sb.append(key).append(value);
}
}
sb.append(appSecret);
// HMAC-MD5 签名
Mac mac = Mac.getInstance("HmacMD5");
SecretKeySpec secretKey = new SecretKeySpec(appSecret.getBytes("UTF-8"), "HmacMD5");
mac.init(secretKey);
byte[] bytes = mac.doFinal(sb.toString().getBytes("UTF-8"));
return Hex.encodeHexString(bytes).toUpperCase();
}
public static void main(String[] args) throws Exception {
Map<String, String> params = new HashMap<>();
params.put("app_key", APP_KEY);
params.put("method", "taobao.item.cat.get");
params.put("timestamp", new java.text.SimpleDateFormat("yyyy-MM-dd HH:mm:ss").format(new Date()));
params.put("format", "json");
params.put("v", "2.0");
params.put("sign_method", "hmac-md5");
params.put("cid", "50008163");
String sign = generateSign(params, APP_SECRET);
params.put("sign", sign);
// 发送 HTTP 请求(此处省略具体实现)
System.out.println("Sign: " + sign);
}}七、常见错误码
表格
| 错误码 | 错误信息 | 解决方案 |
|---|---|---|
40 | Invalid arguments | 检查必填参数是否完整 |
40001 | Insufficient isv permissions | 应用无权限调用该接口,需申请权限 |
40002 | Invalid timestamp | 时间戳格式错误或与服务端时间偏差过大 |
40003 | Invalid signature | 签名生成错误,检查签名算法 |
40004 | Invalid method | 接口名称错误 |
40006 | Invalid app_key | App Key 不存在或已失效 |
50001 | API call limit exceeded | 调用频率超限,请降低调用频率 |
八、典型应用场景
8.1 商品发布前的类目校验
在发布商品时,通过
item_cat_get 验证用户选择的类目是否有效,获取类目属性规则。8.2 类目导航树构建
结合
itemcats.get(批量获取类目列表)接口,递归构建完整的类目树结构。8.3 数据分析与竞品监控
通过类目信息聚合商品数据,进行行业分析和竞品监控。
8.4 类目迁移与同步
将淘宝类目体系同步到自有系统,保持类目数据的一致性。
九、注意事项
- 类目 ID 获取:淘宝类目 ID 可通过
itemcats.get接口批量获取,或在淘宝商品详情页 URL 中解析。 - 类目更新:淘宝类目会不定期调整,建议定期同步类目数据。
- 权限申请:部分类目信息需要特殊权限,需在开放平台申请。
- 缓存策略:类目数据变化频率低,建议在本地缓存,减少 API 调用次数。
- 沙箱环境:开发测试阶段建议使用淘宝沙箱环境,避免影响正式数据。
十、相关接口推荐
表格
| 接口名称 | 说明 |
|---|---|
taobao.itemcats.get | 批量获取商品类目列表 |
taobao.itemprops.get | 获取类目属性列表 |
taobao.itempropvalues.get | 获取类目属性值列表 |
taobao.item.add | 发布商品 |
taobao.item.update | 更新商品信息 |
十一、总结
item_cat_get 是淘宝开放平台最基础的类目查询接口之一,虽然功能单一(仅支持单类目查询),但在商品管理、数据分析等场景中不可或缺。实际开发中,通常需要配合 itemcats.get 等批量接口使用,以提升效率。开发者在使用时需注意签名生成规则、参数校验和频率控制,确保接口调用的稳定性和可靠性。如遇任何疑问或有进一步的需求,请随时与我私信或者评论联系。