淘宝商品评论 API（核心接口如 taobao.item.review.get）是获取商品用户评价数据的官方通道，返回数据以 JSON 格式为主，结构规范且字段丰富，涵盖评论基础信息、用户画像、内容详情、多媒体信息等维度。本文将拆解通用返回结构、核心字段含义、多场景示例及解析注意事项，为开发者提供完整的数据参考指南。
一、通用返回数据结构（成功 / 失败统一规范）
淘宝开放平台所有 API 均遵循统一的响应格式，评论 API 也不例外，分为 成功响应 和 失败响应 两种结构，便于开发者封装通用解析逻辑。
1. 成功响应通用格式
json
{ "code": 0, "msg": "success", "request_id": "123456789abcdef", "resp_data": { "item_review_get_response": { "total_results": 1250, "reviews": [ { // 单条评论核心数据 } ], "request_id": "123456789abcdef" } } }
- 顶层关键字段说明
code: 状态码，0表示成功，非 0 为失败；msg: 状态描述，成功为success；request_id: 全局请求唯一标识，用于问题排查；resp_data.item_review_get_response: 业务响应体，名称与接口名强关联；total_results: 商品评论总条数，用于分页计算；reviews: 评论数据数组，单页默认返回 20 条，可通过入参page_size调整（最大 100）。
2. 失败响应通用格式
json
{ "code": 40, "msg": "error", "request_id": "123456789abcdef", "resp_data": { "error_response": { "code": 40, "msg": "签名错误", "sub_code": "isv.invalid-sign", "sub_msg": "签名参数不正确，请检查签名生成逻辑" } } }
- 错误关键字段说明
code: 顶层错误码，与业务错误码一致；sub_code: 精准错误类型标识（如isv.invalid-sign签名错误、isv.api-rate-limit-exceeded限流）；sub_msg: 具体错误原因，用于定位问题。
二、单条评论核心字段解析（以 taobao.item.review.get 为例）
reviews 数组中的单条评论数据是解析核心，涵盖 基础标识、用户信息、评论内容、多媒体、时效 五大类字段，以下是完整示例及字段说明。
1. 单条评论完整数据示例
json
{ "id": "9876543210abcdef", "num_iid": "689712345678", "user_nick": "tbNick123456", "user_id": "123456789", "user_level": "V3", "user_vip": true, "content": "纯棉材质很舒服，尺码标准，洗了不缩水，夏天穿透气！", "created": "2025-05-10 14:30:00", "modified": "2025-05-11 09:15:00", "rate": 5, "rate_content": "好评", "has_more": true, "more_content": "穿了一周再来追评，版型宽松不挑身材，搭牛仔裤超好看！", "pic_num": 3, "pic_urls": [ "https://img.alicdn.com/imgextra/i1/123456789/O1CN01abcdef123456_!!0-review.jpg", "https://img.alicdn.com/imgextra/i2/123456789/O1CN01abcdef123457_!!0-review.jpg", "https://img.alicdn.com/imgextra/i3/123456789/O1CN01abcdef123458_!!0-review.jpg" ], "spec_info": "颜色:白色;尺寸:L", "useful_vote": 25, "reply": "感谢亲的认可，我们会继续努力做好品质~", "reply_created": "2025-05-10 16:20:00" }
2. 核心字段分类说明
| 字段分类 | 字段名 | 含义说明 | 数据类型 | 核心用途 |
| 基础标识 | id |
评论唯一 ID，不可重复 | 字符串 | 去重、增量采集的核心标识 |
num_iid |
商品 ID，关联评论所属商品 | 字符串 | 多商品评论数据归类 | |
| 用户信息 | user_nick |
用户昵称（已脱敏，如 tbNick123456） |
字符串 | 用户画像分析 |
user_id |
用户唯一标识（部分接口需申请权限才能获取） | 字符串 | 精准用户行为追踪 | |
user_level |
用户等级（如 V1-V6） | 字符串 | 高价值用户评论权重分析 | |
user_vip |
是否为淘宝 VIP 用户 | 布尔值 | 区分普通 / 付费用户评价倾向 | |
| 评论内容 | content |
评论正文 | 字符串 | 舆情分析、商品优缺点提取 |
rate |
评分（1-5 星，5 星为好评，1 星为差评） | 整数 | 商品评分统计、口碑计算 | |
rate_content |
评分标签（如 “好评”“中评”“差评”） | 字符串 | 快速分类评论倾向 | |
has_more |
是否有追评 | 布尔值 | 识别深度评价用户 | |
more_content |
追评内容（has_more=true 时才有值） |
字符串 | 长期使用反馈分析 | |
| 多媒体信息 | pic_num |
晒图数量 | 整数 | 评估评论真实性（晒图评论可信度更高） |
pic_urls |
晒图链接数组（高清图，可直接下载） | 数组 | 商品真实展示素材收集、买家秀运营 | |
| 时效与互动 | created |
评论发布时间（格式：YYYY-MM-DD HH:MM:SS） | 字符串 | 增量采集时间筛选、评论热度趋势分析 |
modified |
评论修改时间（用户编辑评论后更新） | 字符串 | 识别用户评价态度变化 | |
useful_vote |
评论有用投票数（其他用户点赞数） | 整数 | 高价值评论筛选（点赞多的评论更具参考性） | |
| 其他信息 | spec_info |
评论对应的商品规格（如 “颜色：白色；尺寸：L”） | 字符串 | 不同规格商品口碑对比 |
reply |
商家回复内容 | 字符串 | 商家服务质量分析 | |
reply_created |
商家回复时间 | 字符串 | 响应时效评估（如多久回复用户评论） |
三、不同场景下的返回数据差异
淘宝评论 API 的返回字段会根据 接口权限 和 商品类目 有所差异，以下是两类典型场景的差异示例。
1. 差评场景（rate=1）
差评数据会包含更多负面反馈信息，部分接口会返回 reason 字段（差评原因）：
json
{ "id": "9876543210abcdeg", "num_iid": "689712345678", "user_nick": "tbNick654321", "rate": 1, "rate_content": "差评", "content": "材质太薄，洗了一次就变形，不值这个价！", "reason": "商品质量差", "created": "2025-05-12 10:00:00", "pic_num": 1, "pic_urls": ["https://img.alicdn.com/imgextra/i4/123456789/O1CN01abcdef123459_!!0-review.jpg"] }
2. 无晒图 / 无追评场景
非核心字段会返回默认值（如空数组、false），避免解析时出现空指针异常：
json
{ "id": "9876543210abcdeh", "num_iid": "689712345678", "content": "物流很快，客服态度好", "rate": 5, "has_more": false, "more_content": "", "pic_num": 0, "pic_urls": [], "reply": "" }
3. 特殊类目差异（如美妆 / 3C）
- 美妆类目：会额外返回
use_effect字段（使用效果，如 “保湿效果好”“不卡粉”）； - 3C 类目：会额外返回
use_scene字段（使用场景，如 “办公用”“游戏用”）。
四、数据解析实战示例（Python）
以下是基于 Python 的评论 API 数据解析示例，包含 成功 / 失败判断、核心字段提取、数据格式化 三个核心步骤。
python
运行
import json def parse_review_api_response(response_data): """ 解析淘宝商品评论API返回数据 :param response_data: API返回的原始JSON字典 :return: 格式化的评论数据列表 + 总条数 """ # 1. 判断请求是否成功 if response_data.get("code") != 0: error_info = response_data["resp_data"]["error_response"] raise Exception( f"API调用失败：{error_info['msg']} " f"(错误码：{error_info['code']}，子错误码：{error_info['sub_code']})" ) # 2. 提取业务数据 review_resp = response_data["resp_data"]["item_review_get_response"] total = review_resp.get("total_results", 0) raw_reviews = review_resp.get("reviews", []) # 3. 格式化核心字段 formatted_reviews = [] for review in raw_reviews: formatted = { "评论ID": review.get("id"), "商品ID": review.get("num_iid"), "用户昵称": review.get("user_nick"), "评分": review.get("rate"), "评论内容": review.get("content"), "评论时间": review.get("created"), "是否追评": review.get("has_more"), "晒图数量": review.get("pic_num"), "晒图链接": review.get("pic_urls", []), "商家回复": review.get("reply") } formatted_reviews.append(formatted) return total, formatted_reviews # 模拟API返回数据 mock_success_response = { "code": 0, "msg": "success", "request_id": "123456789abcdef", "resp_data": { "item_review_get_response": { "total_results": 1250, "reviews": [ { "id": "9876543210abcdef", "num_iid": "689712345678", "user_nick": "tbNick123456", "rate": 5, "content": "纯棉材质很舒服", "created": "2025-05-10 14:30:00", "has_more": True, "pic_num": 3, "pic_urls": ["https://xxx.jpg"], "reply": "感谢亲的认可" } ], "request_id": "123456789abcdef" } } } # 调用解析函数 try: total_count, reviews = parse_review_api_response(mock_success_response) print(f"共获取 {total_count} 条评论，本页解析 {len(reviews)} 条") print("第一条评论：", json.dumps(reviews[0], ensure_ascii=False, indent=2)) except Exception as e: print("解析失败：", str(e))
五、数据解析与使用注意事项
- 字段空值处理：
more_content、pic_urls、reply等字段可能为空，解析时需判断默认值，避免KeyError； - 时间格式转换：
created字段为字符串格式，需转换为datetime类型后再进行时间筛选（如增量采集）； - 数据去重：以
id字段作为唯一标识，避免重复存储相同评论； - 权限限制：
user_id、use_effect等字段需申请额外权限才能获取，未授权时返回null； - 图片有效期：
pic_urls中的链接有效期通常为 30 天，如需长期使用，建议下载后存储至自有服务器； - 限流适配：评论 API 有 QPS 限制（普通应用 1 QPS），解析后的数据建议缓存至 Redis/MySQL，减少重复调用。
六、总结
淘宝商品评论 API 返回数据具有 结构统一、字段规范、场景适配性强 的特点，核心解析重点在于 顶层状态判断 和 单条评论字段提取。开发者需重点关注 id（去重）、created（增量）、content（舆情）、pic_urls（素材）等核心字段，同时做好空值处理与权限适配，才能高效利用评论数据实现商品口碑分析、用户画像构建、买家秀运营等业务场景。
