你想要掌握日本乐天商品详情 API 响应数据的完整解析与处理方法，核心是解决「数据结构理解、核心字段提取、异常容错、数据清洗」四大问题。以下是从响应结构拆解→字段解析→数据清洗→实战优化的全流程指南，包含可直接复用的 Python 代码，适配跨境选品、数据统计等实际业务场景。
一、 先明确响应数据的核心结构
乐天商品详情 API（IchibaItem/Item）返回的 JSON 数据分为「基础层、核心商品层、扩展信息层」，不同formatVersion（1/2）的结构略有差异，推荐使用 version=2（结构更清晰、字段更全）。
1. 响应数据整体结构（version=2）
json
{ "itemCode": "shop001:item123456", // 商品编码（核心标识） "itemName": "ソニーワイヤレスイヤホン WH-1000XM5", // 商品名称 "itemPrice": 32800, // 价格（日元，整型） "availability": 1, // 库存状态（1=有货/0=无货） "itemUrl": "https://item.rakuten.co.jp/shop001/item123456/", // 商品链接 "mediumImageUrls": [{"imageUrl": "https://xxx.jpg"}], // 商品图片 "shopName": "ソニー公式店", // 店铺名称 "reviewAverage": 4.8, // 评价平均分 "reviewCount": 1256, // 评价总数 "genreId": 555086, // 分类ID "brandName": "SONY", // 品牌名 "postageFlag": 1, // 包邮标识（1=包邮/0=不包邮） "size": "M", // 规格 "weight": 250, // 重量（g） // 更多扩展字段... }
2. 核心字段分类（按业务场景）
| 字段分类 | 核心字段 | 业务价值 | 数据类型 | 注意点 |
| 基础标识 | itemCode、itemName | 商品唯一标识 / 名称 | 字符串 | 名称含日文 / 特殊字符，需编码处理 |
| 价格体系 | itemPrice、postageFlag | 售价 / 包邮状态 | 整型 / 整型 | 价格无小数（日元为最小单位） |
| 库存履约 | availability、deliveryDate | 库存 / 发货时间 | 整型 / 字符串 | availability=1 为有货，0 为无货 |
| 口碑数据 | reviewAverage、reviewCount | 评分 / 评价数 | 浮点型 / 整型 | 评分范围 0-5，无评价时为 null |
| 媒体信息 | mediumImageUrls、largeImageUrls | 商品图片 | 数组 | 可能为空数组，需容错 |
| 店铺信息 | shopName、shopUrl | 店铺名称 / 链接 | 字符串 | 部分店铺名称含特殊符号 |
二、 核心解析步骤与实战代码
1. 基础依赖（无需额外安装）
仅需 Python 内置库 +requests，已安装可跳过：
bash
运行
pip install requests
2. 完整解析与处理代码（含容错 + 清洗）
python
运行
import requests import json import re from requests.exceptions import RequestException def get_rakuten_item_detail(application_id, item_code): """ 调用乐天API并解析响应数据（含完整的数据清洗与容错） """ # 1. 调用API获取原始响应 api_url = "https://app.rakuten.co.jp/services/api/IchibaItem/Item/20170426" params = { "applicationId": application_id, "itemCode": item_code, "format": "json", "formatVersion": 2 } try: response = requests.get(api_url, params=params, timeout=15) response.raise_for_status() raw_data = response.json() except (RequestException, json.JSONDecodeError) as e: print(f"API调用/解析失败：{e}") return None # 2. 核心解析逻辑（分字段处理，全容错） item_data = {} # -------- 基础标识字段 -------- item_data["商品编码"] = raw_data.get("itemCode", "") # 商品名称清洗：去除多余空格/特殊符号，统一编码 raw_name = raw_data.get("itemName", "") item_data["商品名称"] = re.sub(r"\s+", " ", raw_name).strip() # 合并多余空格 # -------- 价格字段（核心清洗） -------- item_price = raw_data.get("itemPrice", 0) # 容错：确保价格为数字（极少数情况返回字符串） item_data["商品价格(日元)"] = int(item_price) if isinstance(item_price, (int, float)) else 0 # 包邮状态转换：1→包邮，0→不包邮，其他→未知 postage_flag = raw_data.get("postageFlag", -1) item_data["包邮状态"] = "包邮" if postage_flag == 1 else "不包邮" if postage_flag == 0 else "未知" # -------- 库存字段 -------- availability = raw_data.get("availability", 0) item_data["库存状态"] = "有货" if availability == 1 else "无货" # 发货时间：处理空值/特殊格式 delivery_date = raw_data.get("deliveryDate", "") item_data["预计发货时间"] = delivery_date if delivery_date else "暂无信息" # -------- 口碑数据 -------- # 评分容错：无评价时设为0，保留1位小数 review_avg = raw_data.get("reviewAverage", 0.0) item_data["评价平均分"] = round(float(review_avg) if review_avg else 0.0, 1) # 评价数容错：确保为非负整数 review_count = raw_data.get("reviewCount", 0) item_data["评价总数"] = int(review_count) if isinstance(review_count, (int, float)) else 0 # -------- 图片字段（提取主图） -------- image_urls = raw_data.get("mediumImageUrls", []) # 容错：数组为空/无imageUrl字段时返回空字符串 item_data["商品主图URL"] = image_urls[0].get("imageUrl", "") if image_urls and len(image_urls) > 0 else "" # -------- 扩展字段（规格/品牌） -------- item_data["品牌名称"] = raw_data.get("brandName", "未知") # 规格清洗：去除多余符号 size = raw_data.get("size", "") item_data["商品规格"] = re.sub(r"[^\w\-/]", "", size) if size else "无规格" # 3. 数据二次校验（过滤无效数据） if item_data["商品编码"] == "" or item_data["商品价格(日元)"] <= 0: print(f"商品{item_code}数据无效，过滤") return None return item_data # -------------------------- 测试解析 -------------------------- if __name__ == "__main__": APPLICATION_ID = "你的32位Application ID" ITEM_CODE = "shop001:item123456" # 替换为真实商品编码 result = get_rakuten_item_detail(APPLICATION_ID, ITEM_CODE) if result: print("=== 解析后的商品数据（清洗后）===") for key, value in result.items(): print(f"{key}：{value}")
3. 代码关键解析点说明
| 处理场景 | 实现方法 | 作用 |
| 字段容错 | raw_data.get("字段名", 默认值) |
避免字段缺失导致 KeyError |
| 数值类型转换 | int()/float() + 类型判断 |
确保价格 / 评分等为预期类型 |
| 字符串清洗 | re.sub() 去除多余空格 / 符号 |
统一商品名称 / 规格的格式 |
| 状态值转换 | 条件判断（如 availability=1→有货） | 将数字状态转为易理解的文本 |
| 数组取值容错 | 先判断数组长度再取值 | 避免图片数组为空时报错 |
| 无效数据过滤 | 校验核心字段（编码 / 价格） | 排除无意义的脏数据 |
三、 批量解析与数据标准化（适配选品场景）
当批量调用 API 时，需将多商品的解析结果标准化，便于后续统计 / 导出，以下是批量解析 + 数据标准化的代码：
python
运行
def batch_parse_rakuten_items(application_id, item_codes): """ 批量解析多个商品的响应数据，返回标准化列表 """ parsed_list = [] for idx, item_code in enumerate(item_codes): print(f"正在解析第{idx+1}个商品：{item_code}") item_data = get_rakuten_item_detail(application_id, item_code) if item_data: parsed_list.append(item_data) # 限流：避免触发API频率限制 requests.post("https://httpbin.org/delay/0.1") # 等价于time.sleep(0.1) # 数据标准化：补充缺失字段，统一格式 standard_fields = [ "商品编码", "商品名称", "商品价格(日元)", "包邮状态", "库存状态", "预计发货时间", "评价平均分", "评价总数", "商品主图URL", "品牌名称", "商品规格" ] standard_list = [] for item in parsed_list: standard_item = {field: item.get(field, "") for field in standard_fields} standard_list.append(standard_item) return standard_list # 调用示例 # ITEM_CODES = ["shop001:item123456", "shop002:item654321"] # batch_result = batch_parse_rakuten_items(APPLICATION_ID, ITEM_CODES)
四、 常见数据问题与解决方案
| 问题现象 | 原因 | 处理方法 |
| 商品名称乱码 | 日文编码未处理 | 打印 / 保存时添加ensure_ascii=False，如json.dump(data, f, ensure_ascii=False) |
| 价格为字符串 | 极少数接口返回 "32800 円" 等格式 | 用正则提取数字：price = int(re.findall(r"\d+", price_str)[0]) |
| 评分为 null | 商品无评价 | 统一赋值为 0.0，并标注 "无评价" |
| 图片 URL 为空 | 商品无图片 | 填充默认占位符 URL，如 "https://placeholder.jpg" |
| 字段值为 0 但实际有数据 | 接口版本错误（version=1） | 确认 formatVersion=2，重新调用 API |
| 重复商品编码 | 批量调用时重复传入 | 解析前先去重：item_codes = list(set(item_codes)) |
五、 进阶处理：数据导出与可视化（实用扩展）
解析后的数据可导出为 Excel/CSV，或生成可视化报表，以下是导出 Excel 的代码：
1. 导出 Excel（需安装 pandas）
bash
运行
pip install pandas openpyxl
python
运行
import pandas as pd def export_to_excel(parsed_data, file_path="rakuten_items.xlsx"): """ 将解析后的数据导出为Excel（UTF-8编码，支持日文） """ if not parsed_data: print("无有效数据可导出") return df = pd.DataFrame(parsed_data) # 调整列顺序（按业务优先级） col_order = [ "商品编码", "商品名称", "品牌名称", "商品价格(日元)", "包邮状态", "库存状态", "评价平均分", "评价总数" ] df = df[col_order + [col for col in df.columns if col not in col_order]] # 导出Excel（避免日文乱码） df.to_excel( file_path, index=False, engine="openpyxl", encoding="utf-8-sig" ) print(f"数据已导出到：{file_path}，共{len(df)}条") # 调用示例 # export_to_excel(batch_result)
2. 简单数据统计（选品分析）
python
运行
def analyze_rakuten_items(parsed_data): """ 基础选品分析：价格区间、好评率、库存占比 """ if not parsed_data: return df = pd.DataFrame(parsed_data) # 1. 价格区间统计 price_ranges = [0, 10000, 20000, 50000, 100000] df["价格区间"] = pd.cut(df["商品价格(日元)"], price_ranges, labels=["0-1万", "1-2万", "2-5万", "5-10万"]) price_count = df["价格区间"].value_counts() print("\n=== 价格区间分布 ===") print(price_count) # 2. 有货商品占比 in_stock_ratio = len(df[df["库存状态"] == "有货"]) / len(df) * 100 print(f"\n有货商品占比：{in_stock_ratio:.1f}%") # 3. 高评分商品（≥4.5分）数量 high_score_count = len(df[df["评价平均分"] ≥ 4.5]) print(f"高评分商品（≥4.5分）数量：{high_score_count}") # 调用示例 # analyze_rakuten_items(batch_result)
六、 关键优化原则（避免踩坑）
- 容错优先：所有字段解析必须加默认值，严禁直接通过
raw_data["字段名"]取值； - 类型统一：数值型字段（价格 / 评分 / 评价数）必须转为 int/float，避免后续统计出错；
- 格式标准化：相同类型的字段（如库存状态）统一文本描述（仅 "有货"/"无货"），避免多格式；
- 无效数据过滤：解析后校验核心字段（编码 / 价格），过滤空值 / 负值数据；
- 编码兼容：处理日文时始终使用 UTF-8 编码，导出 Excel 用
utf-8-sig避免乱码。
总结
日本乐天商品详情 API 响应数据解析的核心要点：
- 结构理解：先掌握 version=2 的响应结构，按「基础 / 价格 / 库存 / 口碑」分类提取字段；
- 容错处理：用
get()方法 + 类型判断避免字段缺失 / 类型错误，是解析的核心； - 数据清洗：统一字符串格式、转换状态值、过滤脏数据，适配业务场景；
- 落地应用：标准化后的数据可导出 Excel 或做选品统计，提升数据利用效率。
