淘宝/天猫商品详情API返回值详解（含代码示例）
一、API接口概述
淘宝开放平台/万邦开放平台提供taobao.item.get接口，用于通过商品ID（num_iid）获取商品的详细信息，包括基础属性、价格、库存、图文描述、SKU规格、促销活动等。
二、核心返回值字段解析
字段名说明示例值
num_iid商品唯一ID，用于精准定位商品"123456789"
title商品标题，含关键词，影响搜索和识别"2025新款智能手表旗舰版"
price当前销售价格"1299.00"
original_price原价（部分接口返回，用于价格对比）"1599.00"
pic_url商品主图URL（高清图片链接）"https://img.alicdn.com/xxx.jpg"
category商品所属分类"智能设备"
brand品牌名称"XX品牌"
description商品详细描述（HTML格式，含特点、规格、材质等）"<p>2025年最新款智能手表...</p>"
item_imgs商品图片列表（含主图、详情图等多角度展示）[{"url":"https://img.alicdn.com/xxx_1.jpg"}]
stock商品总库存数量150
sales商品销量（反映受欢迎程度）350
skusSKU列表（含不同规格的价格、库存及属性组合）[{"sku_id":"sku_001", "price":"1299.00", "stock":150, "properties":"颜色:黑色;尺寸:标准版"}]
seller_id卖家唯一ID"987654321"
seller_nick卖家昵称"官方旗舰店"
location发货地（影响物流时效和运费）"浙江杭州"
post_fee邮费（"0.00"表示包邮）"0.00"
promotion当前促销活动（如满减、打折）"满1000减100"
coupon_info优惠券信息（面额及使用条件）{"amount":"100.00", "condition":"满1000元可用"}
service_list服务保障（如七天无理由退换）["七天无理由退换"]
rate_info评价数据（好评率及总评价数）{"good_rate":"97.6%", "total_count":1250}
detail_url商品详情页链接（可直接跳转至淘宝页面）"https://item.taobao.com/item.htm?id=123456789"
三、返回值结构示例
json
{
"item_get_response":{
"item":{
"num_iid":"123456789",
"title":"2025新款智能手表旗舰版",
"price":"1299.00",
"original_price":"1599.00",
"pic_url":"https://img.alicdn.com/xxx.jpg",
"category":"智能设备",
"brand":"XX品牌",
"description":"<p>2025年最新款智能手表，支持心率监测...</p>",
"item_imgs":[
{"url":"https://img.alicdn.com/xxx_1.jpg"},
{"url":"https://img.alicdn.com/xxx_2.jpg"}
],
"stock":150,
"sales":350,
"skus":[
{
"sku_id":"sku_001",
"price":"1299.00",
"stock":150,
"properties":"颜色:黑色;尺寸:标准版",
"image":"https://img.alicdn.com/xxx_black.jpg"
}
],
"seller_id":"987654321",
"seller_nick":"官方旗舰店",
"location":"浙江杭州",
"post_fee":"0.00",
"promotion":"满1000减100",
"coupon_info":{"amount":"100.00","condition":"满1000元可用"},
"service_list":["七天无理由退换"],
"rate_info":{"good_rate":"97.6%","total_count":1250},
"detail_url":"https://item.taobao.com/item.htm?id=123456789"
}
}
}
四、代码调用示例（Python）
python
importrequests
importhashlib
importtime
defget_taobao_item_details(app_key, app_secret, num_iid):
url ="https://eco.taobao.com/router/rest"
timestamp = time.strftime("%Y-%m-%d %H:%M:%S")
params = {
'method':'taobao.item.get',
'app_key': app_key,
'num_iid': num_iid,
'timestamp': timestamp,
'format':'json',
'v':'2.0',
'sign_method':'md5',
'fields':'num_iid,title,price,pic_url,desc,skus,stock,sales'
}
# 生成签名
sorted_params =sorted(params.items())
query_string =''.join([f"{k}{v}"fork, vinsorted_params])
sign_str = app_secret + query_string + app_secret
params['sign'] = hashlib.md5(sign_str.encode('utf-8')).hexdigest().upper()
# 发送请求
response = requests.get(url, params=params)
returnresponse.json()
# 示例调用
app_key ="YOUR_APP_KEY"
app_secret ="YOUR_APP_SECRET"
num_iid ="123456789"
data = get_taobao_item_details(app_key, app_secret, num_iid)
ifdata.get('item_get_response', {}).get('item'):
item = data['item_get_response']['item']
print(f"商品标题:{item['title']}")
print(f"当前价格: ¥{item['price']}")
print(f"库存:{item['stock']}件")
print(f"主图链接:{item['pic_url']}")
else:
print(f"请求失败:{data.get('error_response', {}).get('msg', '未知错误')}")
五、调用注意事项
权限与认证
需在淘宝开放平台注册账号、创建应用并获取AppKey和AppSecret。
部分接口（如taobao.item.detail.get）需额外申请权限。
签名生成规则
按参数名排序后拼接密钥，使用MD5加密生成签名。
频率限制
免费版每日调用限5000次，超出需付费或优化逻辑（如缓存数据）。
字段筛选
通过fields参数指定返回字段（如fields=num_iid,title,price），减少数据冗余。
错误处理
检查status字段（0为成功），非0时根据error_code和message排查问题。
六、扩展功能场景
多SKU管理
通过skus字段获取商品规格（如颜色、尺码）的价格和库存，支持电商系统动态展示。
促销活动监控
实时解析promotion和coupon_info字段，向用户推送限时折扣或满减优惠。
服务保障透传
展示service_list中的服务（如七天无理由退换），提升用户信任度。
通过以上接口和返回值说明，可高效集成淘宝商品详情数据至业务系统，支持商品展示、价格监控、智能选品等场景。
