主题
Product Object
product 对象是 Keepa 最核心的返回对象，包含一个 ASIN 的全部基础信息、价格历史、销量排名、变种、Buy Box、A+ 内容等。/api/keepa/product、/api/keepa/productsearch、/api/keepa/productfinder 返回的都是它（或它的列表）。
对应 Keepa 官方：Product Object
重要：先看 productType
任何对该对象的解析逻辑都应该首先判断 productType，因为它决定了哪些字段会被填充：
| 值 | 名称 | 可用数据 |
|---|---|---|
| 0 | STANDARD | 全部数据可用 |
| 1 | DOWNLOADABLE | 无价格 / 评分 / offers，更新频率较低 |
| 2 | EBOOK | 同上 |
| 3 | INACCESSIBLE | 无价格 / 评分 / offers；销量排名和 offer 计数有但更新慢，部分字段缺失 |
| 4 | INVALID | ASIN 失效或非法导致暂时无数据，可能稍后恢复 |
| 5 | VARIATION_PARENT | 是变体父 ASIN，请看 variations 字段 |
detailLevel 与字段可见性
Keepamore 在透传 Keepa 原始 product 之前，按 detailLevel 做了一次裁剪（详见 /api/keepa/product 文档）：
| detailLevel | 删除的字段 | 备注 |
|---|---|---|
summary | 仅保留下表里 ✅ summary 列标记的字段 | 给 LLM 用，最省 token |
lite（默认） | csv、variationCSV、salesRanks、couponHistory、monthlySoldHistory、parentAsinHistory、salesRankReferenceHistory、reviews、所有以 History 结尾的数组；variations 超过 5 个时只留前 5 个 | 业务/选品场景的最佳平衡 |
full | 不裁剪，与 Keepa 官方一致 | 离线分析或下游再处理时使用 |
下表的 summary 列：✅ = summary 也保留；其余 detailLevel=lite / full 默认都返回，除非另注 (lite 删)。
字段：基础元信息
| 字段 | 类型 | summary | 说明 |
|---|---|---|---|
asin | string | ✅ | ASIN，10 位字母数字。例：B00M0QVG3W。 |
domainId | int | ✅ | 站点 ID。映射见 domain 列表。 |
productType | int | ✅ | 产品类型，见上表。 |
title | string | ✅ | 标题，罕见情况下可能含未转义 HTML，前端展示请清洗。 |
brand | string | ✅ | 品牌，null = 不可用。 |
manufacturer | string | ✅ | 制造商。 |
partNumber | string | ✅ | MPN / 制造商型号。 |
model | string | ✅ | 型号。 |
binding | string | ✅ | 装订 / 形态。书籍是装订类型，其他品类一般是大类目名。 |
color | string | ✅ | 颜色。 |
size | string | ✅ | 尺寸。 |
type | string | ✅ | productType 字符串（与上方数字 productType 不同），如 VIDEO_GAME_CONTROLLER。 |
urlSlug | string | ✅ | 详情页 URL slug。 |
parentAsin | string | ✅ | 父 ASIN（变体场景）。无变体则 null。 |
parentAsinHistory (lite 删) | string[] | 父 ASIN 变更历史 [keepaTime, prevParent, ...]。从 2024-03-18 开始记录。 | |
trackingSince | int | ✅ | 我们开始跟踪该 ASIN 的时间（KeepaTime）。 |
listedSince | int | ✅ | Amazon 上首次上架时间（KeepaTime）；不可用时为 0 或 -1。 |
lastUpdate | int | ✅ | 最近一次产品信息更新时间（KeepaTime）。 |
lastPriceChange | int | ✅ | 最近一次价格变化时间（KeepaTime）。 |
lastRatingUpdate | int | ✅ | 最近一次评分 / 评论数更新时间（KeepaTime）。 |
lastEbayUpdate | int | 最近一次 eBay 价格更新时间；负数 = 未匹配到 eBay 商品。 | |
lastStockUpdate | int | 最近一次库存更新时间，仅在请求带 stock 参数时有值。 |
字段：分类与图片
| 字段 | 类型 | summary | 说明 |
|---|---|---|---|
rootCategory | int | ✅ | 根类目节点 ID；0 = 未知，9223372036854775807（long max）= 占位符 ?（产品未挂在任何有效类目下）。 |
categories | long[] | ✅ | 该 ASIN 所在的全部类目节点 ID。可为空。 |
categoryTree | object[] | ✅ | 类目树，每个对象 { catId, name }，按层级顺序。 |
salesRankReference | long | 主销量排名所在的类目 ID；-1 = 不可用，-2 = 在 launchpad。 | |
salesRankReferenceHistory (lite 删) | long[] | 主销量类目历史 [keepaTime, catId, ...]。 | |
salesRanks (lite 删) | object | 各类目销量排名历史，键 = 类目 ID，值 = [keepaTime, salesRank, ...]。 | |
images | object[] | ✅ | 图片 metadata 数组，每个含 l / lH / lW（大图）和 m / mH / mW（中图）。完整 URL：https://m.media-amazon.com/images/I/<l>。summary 下最多保留 6 张。 |
字段：标识符
| 字段 | 类型 | summary | 说明 |
|---|---|---|---|
eanList | string[] | ✅ | EAN 列表，第 0 项为主 EAN。 |
upcList | string[] | ✅ | UPC 列表，第 0 项为主 UPC。 |
gtinList | string[] | GTIN 列表，第 0 项为主 GTIN。 |
字段：品牌商店与展示分组
| 字段 | 类型 | summary | 说明 |
|---|---|---|---|
brandStoreName | string | 品牌店铺名（数字商品 / 视频租赁 / 商品包 / Fresh / Pantry 一律不可用）。 | |
brandStoreUrl | string | 品牌店铺 URL 路径，需自行拼接 Amazon 站点域名。 | |
brandStoreUrlName | string | 品牌店铺 URL 中的 slug。 | |
websiteDisplayGroup | string | 决定销量排名计算与展示方式的产品分组（变体场景重要）。 | |
websiteDisplayGroupName | string | 同上分组的可读名。 | |
salesRankDisplayGroup | string | 主销量排名所基于的分组。 |
字段：商品属性（属性流字段）
这一组都是 Amazon listing 的属性流字段，部分品类才有，多数取值为字符串。
summary默认不带（除非另注 ✅）。
| 字段 | 类型 | summary | 说明 |
|---|---|---|---|
scent | string | 香味，例：Lavender。 | |
shortDescription | string | 简短描述。 | |
activeIngredients | string | 活性成分。 | |
specialIngredients | string | 特殊成分。 | |
ingredients | string | 全成分表。 | |
itemForm | string | 形态 / 物理状态，例：Liquid。 | |
itemTypeKeyword | string | 商品类型关键词，例：body-lotions。 | |
recommendedUsesForProduct | string | 推荐用途，例：Aromatherapy, Home Decoration。 | |
pattern | string | 图案，例：Striped。 | |
materials | string[] | 材质数组。 | |
material | string | 主要材质（单值字段）。 | |
specialFeatures | string[] | 特色功能数组。 | |
specificUsesForProduct | string[] | 具体用途数组。 | |
safetyWarning | string | 安全警告。 | |
productBenefit | string | 产品卖点 / 优势。 | |
batteriesRequired | boolean | 是否需要电池。 | |
batteriesIncluded | boolean | 是否含电池。 | |
targetAudienceKeyword | string | 目标用户关键词。 | |
style | string | 风格，例：Modern。 | |
includedComponents | string | 包装内含件。 | |
audienceRating | string | 影音分级，例：PG-13。 | |
numberOfItems | int | 商品件数；-1 = 不可用。 | |
numberOfPages | int | 页数；-1 = 不可用。 | |
publicationDate | int | 出版日期，格式 YYYY / YYYYMM / YYYYMMDD；-1 = 不可用。例：20150409 = 2015-04-09。 | |
releaseDate | int | 上市日期，格式同上。 | |
contributors | string[][] | 贡献者，每项 [name, role]，例：[["Vin Diesel", "actor"]]。 | |
languages | string[][] | 语言，每项 [name] 或 [name, type]，例：[["English", "Original Language"]]。 | |
edition | string | 版本。 | |
format | string | 格式（影音）。 | |
features | string[] | ✅ | Listing 五点描述，最多 5 条，单条最多 1000 字符。summary 下超过 10 条会截断并附说明。 |
description | string | 商品描述，可能含 HTML 与 \n，最多 4000 字符。需带 offers 才会刷新。 | |
hazardousMaterials | object[] | 危险品类型，每项 { aspect, value }。 |
字段：尺寸 / 重量
| 字段 | 类型 | summary | 说明 |
|---|---|---|---|
packageHeight | int | ✅ | 包装高度（毫米）；0 或 -1 = 不可用。 |
packageLength | int | ✅ | 包装长度（毫米）。 |
packageWidth | int | ✅ | 包装宽度（毫米）。 |
packageWeight | int | ✅ | 包装重量（克），例：1500 = 1.5 kg。 |
packageQuantity | int | 包装内件数。 | |
itemHeight | int | 商品本体高度（毫米）。 | |
itemLength | int | 商品本体长度（毫米）。 | |
itemWidth | int | 商品本体宽度（毫米）。 | |
itemWeight | int | 商品本体重量（克）。 | |
unitCount | object | 单位计量对象 { unitValue, unitType, eachUnitCount }，用于「按单位售价」展示。 |
字段：变种 / 关联商品
| 字段 | 类型 | summary | 说明 |
|---|---|---|---|
variations | object[] | 该 ASIN 的变种，最多 4000 个。每项 { asin, image, attributes: [{ dimension, value }] }。需带 offers 才会刷新。lite 模式下超过 5 个会只保留前 5 个，并附 _variationsTruncated: { shown, total } 标记。 | |
historicalVariations (lite 删) | string[] | 已下架 / 缺货的历史变种 ASIN。需带 historical-variations 参数。 | |
frequentlyBoughtTogether | string[] | "经常一起购买" ASIN（1–2 个）。需带 offers 才会刷新。 | |
bundleItems | string[] | 虚拟商品包内含 ASIN 列表。 |
字段：媒体内容
| 字段 | 类型 | summary | 说明 |
|---|---|---|---|
videos | object[] | 视频 metadata 数组。需带 videos + offers 参数。每项 { title, image, duration, creator, name, url }，creator 取值：Main / Customer / Seller / Influencer / Vendor / ThirdParty / Amazon / Merchant / Brand。 | |
aPlus | object[] | A+ 内容数组。需带 aplus 参数。每项 { module: [{ text, image, imageAltText, video, asin }], fromManufacturer }。 |
字段：促销 / 优惠券 / Deal
| 字段 | 类型 | summary | 说明 |
|---|---|---|---|
coupon | int[] | Buy Box offer 的优惠券 [一次性优惠券, S&S 首单优惠券]。值规则：0 = 无；正数 = 绝对金额（cents）；负数 = 百分比折扣（如 -15 = 15% off）。需带 offers 才会刷新。例：[200, -15] = $2 一次券 + S&S 首单 15% off。 | |
couponHistory (lite 删) | int[] | 优惠券历史 [keepaTime, oneTime, sns, ...]。从 2024-06-15 开始记录。 | |
promotions | object[] | 当前活跃促销，每项 { type, amount, discountPercent, snsBulkDiscountPercent }。type 当前主要是 SNS。需带 offers。 | |
deals | object[] | 当前 Buy Box 的 deal 标识。需带 offers。每项 { accessType, dealType, badge }。· accessType：ALL / PRIME_EARLY_ACCESS / PRIME_EXCLUSIVE· dealType：PRIME_DAY / PRIME_DAY_EARLY / EARLY_ACCESS_WITH_PRIME / PRIME_EXCLUSIVE / SELLING_FAST / PRIME_SELLING_FAST / LIMITED_TIME_DEAL / COUNTDOWN_ENDS_IN / APP_ONLY / CLEARANCE_NO_RETURNS / SPECIAL_EVENT_SALE / GENERIC_OFFER_PROMO / UNKNOWN· badge：商品页显示文案，例 Early Prime Deal | |
businessDiscount | int | 最高商企折扣百分比；常滞后于实际报价。 | |
lastBusinessDiscountUpdate | int | 上述字段的更新时间。 |
字段：库存 / Buy Box / Offer
| 字段 | 类型 | summary | 说明 |
|---|---|---|---|
availabilityAmazon | int | Amazon 自营 offer 库存状态：-1 无 Amazon offer ｜ 0 有货可发 ｜ 1 暂时缺货但可预订 ｜ 2 状态未知 ｜ 3 暂时缺货但可补单 ｜ 4 发货延迟（看 availabilityAmazonDelay） | |
availabilityAmazonDelay | int[] | 当 availabilityAmazon=4 时，发货延迟 [最小小时, 最大小时]，例 [24, 48] = 1–2 天。 | |
buyBoxEligibleOfferCounts | int[] | 各状态合格 Buy Box offer 数，长度 8：[NewFBA, NewFBM, UsedFBA, UsedFBM, CollectibleFBA, CollectibleFBM, RefurbishedFBA, RefurbishedFBM]。 | |
competitivePriceThreshold | int | Amazon 给出的竞品压力价。卖家高于此价可能失去 Buy Box 资格。 | |
suggestedLowerPrice | int | Amazon 建议的更低售价（含运费）。 | |
offers | object[] | Marketplace Offer 对象数组。需带 offers 参数；detailLevel=summary 不返回。 | |
liveOffersOrder | int[] | 在 offers 数组中按 Amazon 列出顺序排列的索引。需带 offers。重复索引 = 该位置原本是更高价的重复 offer，已替换为最低价对应索引。 | |
buyBoxSellerIdHistory (lite 删) | string[] | Buy Box 卖家变更历史 [keepaTime, sellerId, ...]。sellerId 特殊值：-1 = 无人合格，-2 = 缺货 / 未识别。需带 offers / buybox。 | |
buyBoxUsedHistory (lite 删) | string[] | Used Buy Box 历史 [keepaTime, sellerId, condition, isFBA, ...]。condition：2=Like New / 3=Very Good / 4=Good / 5=Acceptable；isFBA：1/0。 | |
isRedirectASIN | boolean | 该 ASIN 是否会被 Amazon 重定向到另一个 ASIN（如缺货变体跳到在售变体）。需带 offers。 | |
isSNS | boolean | Buy Box 是否支持 Subscribe & Save。 | |
offersSuccessful | boolean | offers 是否成功拉取。注意：无任何 offer 的产品该字段会一直 false。 |
字段：评分 / 销量
| 字段 | 类型 | summary | 说明 |
|---|---|---|---|
reviews (lite 删) | object | 评分 / 评论数历史对象 { lastUpdate, ratingCount: [keepaTime, count, ...], reviewCount: [keepaTime, count, ...] }。需带 rating 参数。⚠️ ratingCount 自 2025-04-09 起 Amazon 不再提供，已停止更新。非变种维度的评分 / 评论数请改读 csv[16] (RATING) 与 csv[17] (COUNT_REVIEWS)。 | |
monthlySold | int | ✅ | Amazon 搜索结果页"过去一月已售"指标。不是估算值，但 Amazon 只给区间（如 1000+）。多数 ASIN 无此值，且按变种维度统计。 |
monthlySoldHistory (lite 删) | int[] | 上字段历史 [keepaTime, monthlySold, ...]。 | |
lastSoldUpdate | int | ✅ | monthlySold 的最后更新时间（KeepaTime）。 |
returnRate | int | 退货率：null = 不可用或正常水平 ｜ 1 = 低退货 ｜ 2 = 高退货。 |
字段：FBA 费用 / 资质标记
| 字段 | 类型 | summary | 说明 |
|---|---|---|---|
fbaFees | object | ✅ | FBA Pick & Pack 费用 { lastUpdate, pickAndPackFee }，单位 cents。 |
variableClosingFee | int | 可变结算费（cents）。 | |
referralFeePercentage | double | ✅ | 推荐费百分比（按当前 / 上次 offer 价计算；默认假设售价 $100）。 |
referralFeePercent | double | ✅ | referralFeePercentage 的同义字段（旧版命名，部分场景仍出现，统一含义相同）。 |
isEligibleForTradeIn | boolean | 是否支持 Trade-In。 | |
isAdultProduct | boolean | ✅ | 是否成人商品。 |
isHeatSensitive | boolean | 是否怕热（如易融化）。 | |
isMerchOnDemand | boolean | 是否 Amazon Merch on Demand 商品。 | |
isHaul | boolean | 是否 Amazon Haul 商品（仅基础信息可用）。 | |
launchpad | boolean | 是否在 Launchpad 类目下（会影响 salesRankReference）。 | |
isEligibleForSuperSaverShipping | boolean | Buy Box 是否支持免运费 Super Saver。 | |
ebayListingIds | long[] | 最低价 eBay listing [newId, usedId]，null 或 0 = 不可用。 |
字段：历史时间序列（csv）
| 字段 | 类型 | summary | 说明 |
|---|---|---|---|
csv (lite 删) | int[][] | 二维历史数组，第一维下标是 Price Type，第二维是 [keepaTime, value, ...] 或含运费类型时 [keepaTime, price, shipping, ...]。null = 该 Price Type 无历史。 | |
stats | object | ✅ | Statistics Object。需带 stats=N 参数。 |
关于 csv 的几条关键约束
- 只在变化时追加：相邻条目时间间隔不固定。
- 运费：除字段名带
_SHIPPING外，价格不含运费。 - NEW / USED / COLLECTIBLE / REFURBISHED 的价格定义：
- 2026-02-23 之前：仅 listing price。
- 2026-02-23 及以后：landing price = listing + shipping。
- Amazon 自营也算 marketplace，所以 Amazon 抢到最低价时，
NEW与AMAZON在该时段值相同。 - Lightning Deal 特例：见
csv与stats的 Lightning Deal 形态。 - eBay 价格慎用：listing 信息常错配 / 错码，更新节奏也与 Amazon 不同。
- 不要写死第一维长度：Keepa 可能随时新增 Price Type。