日本乐天商品详情 API（IchibaItem/Item）返回的 JSON 数据结构，会随formatVersion参数不同而变化，推荐使用formatVersion=2（结构更清晰、字段更规范）。以下是完整的 JSON 数据结构解析、核心字段说明、示例数据及实用解析技巧，适配跨境选品、海外仓对接等业务场景。
一、 基础请求与 JSON 返回前提
1. 关键请求参数
要获取标准 JSON 响应，需在请求中指定以下参数：
| 参数名 | 必填 | 取值 | 作用 |
applicationId |
是 | 32 位开发者 ID | API 身份认证 |
itemCode |
是 | 乐天商品编码（如shop001:item123456） |
指定查询商品 |
format |
否 | json（默认） |
响应格式为 JSON |
formatVersion |
否 | 2（推荐） |
响应结构版本，v2 比 v1 更简洁 |
elements |
否 | 字段名列表（如itemName,itemPrice） |
按需返回字段，减少数据冗余 |
2. 最简请求示例
python
运行
import requests APP_ID = "你的Application ID" ITEM_CODE = "shop001:item123456" url = "https://app.rakuten.co.jp/services/api/IchibaItem/Item/20170426" params = { "applicationId": APP_ID, "itemCode": ITEM_CODE, "format": "json", "formatVersion": 2 } response = requests.get(url, params=params) json_data = response.json() # 解析JSON数据
二、 JSON 响应完整结构（formatVersion=2）
乐天商品详情 API 返回的 JSON 数据分为 基础信息、价格信息、库存履约、店铺信息、媒体信息、口碑信息 六大模块，以下是完整字段说明与示例：
1. 完整 JSON 示例
json
{ "itemCode": "shop001:item123456", "itemName": "ソニーワイヤレスイヤホン WH-1000XM5 ブラック", "itemPrice": 32800, "listPrice": 39800, "discountRate": 18, "availability": 1, "deliveryDate": "通常3～4営業日で発送", "shopName": "ソニー公式ストア", "shopCode": "shop001", "mediumImageUrls": [{"imageUrl": "https://img.r10s.jp/item/image/123456.jpg"}], "largeImageUrls": [{"imageUrl": "https://img.r10s.jp/item/large/123456.jpg"}], "reviewAverage": 4.8, "reviewCount": 1256, "brandName": "SONY", "weight": 250, "size": "本体：約18×20×9cm", "postageFlag": 1, "itemUrl": "https://item.rakuten.co.jp/shop001/item123456/", "genreId": 555086, "catchcopy": "ノイズキャンセリング最強モデル", "salesDate": "2023-05-26" }
2. 核心字段分类说明
| 模块 | 字段名 | 类型 | 含义 | 业务价值 |
| 基础标识 | itemCode |
字符串 | 商品唯一编码 | 海外仓 SKU 关联核心标识 |
itemName |
字符串 | 商品名称（日文） | 选品、商品上架标题参考 | |
brandName |
字符串 | 品牌名称 | 品牌占有率分析 | |
genreId |
整型 | 商品分类 ID | 品类趋势分析 | |
| 价格体系 | itemPrice |
整型 | 当前售价（日元） | 定价策略、成本核算 |
listPrice |
整型 | 原价（日元） | 折扣率计算 | |
discountRate |
整型 | 折扣率（%） | 热销款判断（折扣率＞15%） | |
postageFlag |
整型 | 包邮标识（1 = 包邮 / 0 = 不包邮） | 履约成本计算 | |
| 库存履约 | availability |
整型 | 库存状态（1 = 有货 / 0 = 无货） | 库存同步、补货触发 |
deliveryDate |
字符串 | 发货时间 | 订单履约时效承诺 | |
weight |
整型 | 商品重量（g） | 头程运费、仓储费计算 | |
size |
字符串 | 商品尺寸 | 海外仓仓储空间规划 | |
| 店铺信息 | shopName |
字符串 | 店铺名称 | 竞品店铺监控 |
shopCode |
字符串 | 店铺编码 | 店铺销量排名分析 | |
| 媒体信息 | mediumImageUrls |
数组 | 商品中图 URL 列表 | 商品主图素材 |
largeImageUrls |
数组 | 商品大图 URL 列表 | 详情页素材 | |
| 口碑信息 | reviewAverage |
浮点型 | 评价平均分（0-5） | 爆款筛选（≥4.5 分） |
reviewCount |
整型 | 评价总数 | 热销款筛选（≥500 条） | |
| 其他信息 | itemUrl |
字符串 | 商品详情页链接 | 详情页内容爬取参考 |
salesDate |
字符串 | 发售日期 | 新品趋势分析 |
三、 不同场景下的 JSON 字段筛选技巧
根据业务需求，通过elements参数指定返回字段，可减少数据传输体积、提升解析效率。
1. 跨境选品场景（核心字段）
需求：筛选热销款，关注价格、口碑、库存
python
运行
params = { "applicationId": APP_ID, "itemCode": ITEM_CODE, "format": "json", "formatVersion": 2, "elements": "itemCode,itemName,itemPrice,discountRate,reviewAverage,reviewCount,availability" } # 返回的JSON仅包含上述字段，体积减少60%以上
2. 海外仓对接场景（核心字段）
需求：库存同步、成本核算，关注重量、尺寸、包邮状态
python
运行
params = { "applicationId": APP_ID, "itemCode": ITEM_CODE, "format": "json", "formatVersion": 2, "elements": "itemCode,itemName,weight,size,postageFlag,availability,deliveryDate" }
四、 JSON 数据解析实战（含容错处理）
解析 JSON 时需做好字段容错，避免因字段缺失导致KeyError，以下是通用解析函数：
python
运行
def parse_rakuten_json(json_data): """ 解析乐天API返回的JSON数据，返回标准化字典 :param json_data: API返回的原始JSON字典 :return: 清洗后的标准化数据 """ if not isinstance(json_data, dict): return None parsed_data = { # 基础标识 "商品编码": json_data.get("itemCode", ""), "商品名称": json_data.get("itemName", "").strip(), "品牌名称": json_data.get("brandName", "未知"), "分类ID": json_data.get("genreId", 0), # 价格体系 "当前售价(日元)": int(json_data.get("itemPrice", 0)), "原价(日元)": int(json_data.get("listPrice", 0)), "折扣率(%)": int(json_data.get("discountRate", 0)), "包邮状态": "包邮" if json_data.get("postageFlag") == 1 else "不包邮", # 库存履约 "库存状态": "有货" if json_data.get("availability") == 1 else "无货", "预计发货时间": json_data.get("deliveryDate", "暂无"), "商品重量(g)": int(json_data.get("weight", 0)), "商品尺寸": json_data.get("size", "无数据"), # 口碑信息 "评价平均分": round(float(json_data.get("reviewAverage", 0.0)), 1), "评价总数": int(json_data.get("reviewCount", 0)), # 媒体信息 "主图URL": json_data.get("mediumImageUrls", [{}])[0].get("imageUrl", "") } return parsed_data # 调用示例 # parsed_result = parse_rakuten_json(json_data)
五、 常见 JSON 数据问题与解决方案
| 问题现象 | 原因 | 处理方法 |
字段值为null |
商品无该属性（如无评价） | 解析时设置默认值（如评价数默认 0） |
| 图片 URL 数组为空 | 商品无图片 | 填充默认占位图 URL |
| 商品名称含特殊符号 | 日文特殊字符转义 | 打印 / 存储时使用ensure_ascii=False |
| 数值字段为字符串 | 极少数异常数据（如itemPrice:"32800"） |
用int()强制转换，捕获异常 |
| 响应结构混乱 | formatVersion未指定或为 1 |
明确指定formatVersion=2 |
六、 批量 JSON 数据处理技巧
当调用IchibaItem/Search接口批量获取商品数据时，返回的 JSON 包含Items数组，解析方法如下：
python
运行
def parse_batch_json(batch_json_data): """解析批量商品搜索API的JSON数据""" item_list = [] if not batch_json_data or "Items" not in batch_json_data: return item_list for item in batch_json_data["Items"]: item_info = item.get("Item", {}) parsed_item = parse_rakuten_json(item_info) # 复用单商品解析函数 item_list.append(parsed_item) return item_list # 调用示例：批量解析100个商品 # batch_result = search_rakuten_items(APP_ID, "ワイヤレスイヤホン", hits=100) # parsed_list = parse_batch_json(batch_result)
