开场：一个让所有对比表失效的问题
选亚马逊数据 API 时，我最常看到的一步操作是：打开三四个供应商官网，把功能列表复制到 Excel 里，做一张对比表，然后发现——全都一样。
商品数据 ✓、评论数据 ✓、搜索数据 ✓、价格监控 ✓。
四家供应商，四个一模一样的对勾。然后你就卡住了，最后大概率按价格或者销售的态度来拍板。
问题不在你不够仔细，在于这张表的度量粒度太粗了。
我做过一次实测：同一个 ASIN，两家都宣称「支持商品数据」的供应商，一家返回 12 个字段，另一家返回 58 个。差 46 个字段，在对比表上是同一个对勾。
这篇文章讲的就是怎么把那 46 个字段的差距量化出来——不靠文档，不靠销售，靠你自己跑。
另外先排除一类：如果你的候选清单里还放着官方渠道 API（SP-API），那这张对比表从一开始就不成立。SP-API 的授权绑定在你自己的卖家账户上，竞品数据和市场级排名不在它的授权范围内——这不是「暂不支持」，是设计上就不提供。底层原因见这篇《亚马逊卖家必看：官方API无法获取竞品数据的底层原因》。下面讨论的都是垂直数据 API 之间的比较。
一、先把「支持」这个词拆开
1.1 二元勾选为什么会骗人
功能对比表用的是二元判断：支持 / 不支持。但真实的交付是连续量，至少有三个层次：
第一层：schema 里有没有这个字段 → 字段覆盖率
第二层：有值的时候能不能取到 → 非空填充率
第三层：这两层都过了的记录有多少 → 可用记录率
只有第三层才和你的业务有关。前两层都过了，这条记录才能直接用；任何一层没过，下游就要么报错、要么静默产出错误结果。
1.2 第二层是最容易被跳过的一层
很多人测到第一层就停了——看到 schema 里有 60 个字段，覆盖率 92%，觉得这家很全。
我见过一个真实的反面案例：某团队就是这么签的年约。上线三个月后发现，优惠券维度常年为空、配送时效常年为空。字段在 schema 里好好的，实际填充率不到 15%。
{
"asin": "B0C7V9K2XQ",
"title": "...",
"coupon": null, // schema 有，值没有
"deliveryEstimate": null, // schema 有，值没有
"price": { "current": 49.99, "original": null }
}
JSON 解析不报错，schema 校验通过，监控看状态码一片绿。只有业务侧觉得「这个数最近不太对」。
年约中途更换成本很高。这个坑本来十分钟就能测出来。
1.3 一个反直觉的结论
覆盖率 95% + 填充率 60% 的供应商，和覆盖率 70% + 填充率 98% 的供应商，后者通常更有价值。
前者给你一堆 null，你得在下游写一堆判空逻辑，还不知道到底是「这个商品真的没有优惠券」还是「没取到」。后者给你的每条记录都是实的，虽然字段少一点，但每个都能信。
字段少而实，胜过字段多而空。
二、三种返回形态：你的项目停在哪一层
把同一批 ASIN 喂给不同供应商，返回会明显分成三种形态。这个分层比任何榜单都有用。
形态 A（薄）：约 12–18 个字段
{
"asin": "B0C7V9K2XQ",
"title": "...",
"brand": "...",
"price": 49.99,
"currency": "USD",
"rating": 4.3,
"reviewCount": 1284,
"availability": "In Stock",
"mainImage": "https://...",
"bsr": 1842,
"category": "Electronics",
"url": "https://..."
}
能做什么：价格监控、基础选品。
做不了什么：任何需要变体、促销、广告位、卖家维度的分析。
形态 B（中等）：约 30–40 个字段，含变体但无广告位标记
{
"asin": "B0C7V9K2XQ",
"parentAsin": "B0C7V90001",
"price": {"current": 49.99, "original": 69.99, "currency": "USD"},
"coupon": {"amount": 5.00, "type": "percentage"},
"availability": {"status": "In Stock", "deliveryEstimate": "..."},
"rating": {"value": 4.3, "count": 1284,
"histogram": {"5": 62, "4": 21, "3": 9, "2": 4, "1": 4}},
"bsr": [{"category": "Electronics", "rank": 1842},
{"category": "Portable Audio", "rank": 97}],
"variants": [
{"asin": "B0C7V9K2XQ", "attributes": {"color": "Black", "size": "256GB"},
"price": 49.99, "availability": "In Stock"},
{"asin": "B0C7V9K2XR", "attributes": {"color": "White", "size": "512GB"},
"price": 79.99, "availability": "In Stock"}
],
"seller": {"name": "...", "rating": 4.6, "isFulfilledByAmazon": true},
"images": [{"url": "...", "variant": "MAIN"}],
"badges": ["Amazon's Choice"]
}
能做什么：选品分析、变体分析、评分分布分析。
做不了什么：排名归因。因为分不清广告位和自然位。
形态 C（完整）：含广告位、自然位次、变体深度
{
// 形态 B 的全部字段，外加：
"variants": [
{"asin": "B0C7V9K2XQ", "attributes": {"color": "Black", "size": "256GB"},
"price": {"current": 49.99, "original": 69.99},
"availability": "In Stock", "rating": {"value": 4.3, "count": 812},
"isBuyBoxWinner": true, "offerCount": 7}
],
"isSponsored": false,
"organicPosition": 1,
"searchContext": {"keyword": "...", "page": 1, "positionOnPage": 3,
"sponsoredCountAhead": 2,
"adTypesAhead": ["SB", "SP"]},
"priceHistory": {"min90d": 44.99, "max90d": 69.99},
"subscribeAndSave": {"discount": 5},
"buyBoxWinner": {"seller": "...", "price": 49.99, "shipping": "FREE"}
}
能做什么：排名归因、广告竞争分析、变体级洞察、历史价格区间分析。
在功能对比表上，这三种形态是同一个对勾。在你的报表上，你买的不只是数据，是你能提什么问题。
三、自己动手：字段契约 + 度量脚本
3.1 写字段契约
字段契约是你自己的需求清单，不是从供应商文档抄来的。按三级分：
- P0：缺了这条记录就废了，直接进死信队列
- P1：影响分析深度但不致命
- P2：锦上添花
CONTRACT = {
"P0": [
"asin", "title", "price.current", "availability.status",
"rating.value", "rating.count", "bsr", "variants",
],
"P1": [
"parentAsin", "brand", "price.original", "price.currency",
"coupon", "seller.name", "offerCount", "images",
"badges", "isSponsored", "categoryPath",
],
}
P0 定 8 到 15 个比较合适。判据很简单：如果一个字段缺失你会让这条记录直接进死信队列，它就是 P0。
不同对象的契约重点不一样：
| 对象 | 关键字段 | 为什么 |
|---|---|---|
| 商品 | price.current、bsr、variants | 定价与选品的基础 |
| 搜索 | page、items[].position、items[].isSponsored、items[].adType、items[].organicRank | 没有后三个，排名监测就是把广告和自然结果混着排序 |
| 评论 | reviewId、asin（子体）、parentAsin、variant、rating、date、verifiedPurchase | variant 决定洞察能否落到具体规格 |
3.2 拍平函数：关键的一行
整个方法的技术核心就是这一个函数：
def flatten(obj, prefix=""):
"""拍平成 a.b.c 路径；列表取前若干元素；空值不进入结果"""
out = {}
if isinstance(obj, dict):
for k, v in obj.items():
out.update(flatten(v, f"{prefix}.{k}" if prefix else k))
elif isinstance(obj, list):
for v in obj[:50]:
out.update(flatten(v, f"{prefix}[]"))
elif obj is not None and obj != "":
out[prefix] = obj # ← 这一行是全部关键
return out
看最后那个 elif。空值不进入结果，所以后面统计「哪些契约字段被返回了」的时候，统计到的是真的有值的字段。
这一行同时解决了两个度量：覆盖率用分子分母算，填充率已经被这个函数隐含处理了。那个真实案例里 coupon: null 的情况，在这里会被直接过滤掉。
3.3 评估与汇总
import statistics
def evaluate(record, cov_threshold=0.8):
flat = flatten(record)
contract = CONTRACT["P0"] + CONTRACT["P1"]
present = [f for f in contract if f in flat]
coverage = len(present) / len(contract)
p0_ok = all(f in flat for f in CONTRACT["P0"]) # P0 必须 100% 有值
return {
"coverage": round(coverage, 3),
"usable": bool(p0_ok and coverage >= cov_threshold),
}
def run(records, spend_usd):
ev = [evaluate(r) for r in records]
usable = [e for e in ev if e["usable"]]
return {
"样本数": len(ev),
"可用记录率": round(len(usable) / len(ev), 4) if ev else 0,
"平均覆盖率": round(statistics.mean(e["coverage"] for e in ev), 3),
"每千条可用记录成本": round(spend_usd / len(usable) * 1000, 2)
if usable else None,
}
p0_ok 用 all() 而不是比例——P0 是硬约束，缺一个整条记录就废了，不存在「缺一半还能用」。
3.4 一个真实的对照输出
=== Vendor A ===
样本数 : 300
平均覆盖率 : 0.94
可用记录率 : 61.33%
每千条可用记录成本: $12.40
=== Vendor B ===
样本数 : 300
平均覆盖率 : 0.71
可用记录率 : 92.67%
每千条可用记录成本: $4.85
A 的覆盖率明显更高，但可用记录率只有 B 的三分之二，成本是 B 的 2.5 倍。
只看覆盖率或功能表，你会选 A。看完可用记录率，结论完全反过来。
这就是为什么要跑这套东西——单看任何一个指标都会误导你。
四、样本集：为什么你测出来各家都差不多
经常有人反馈「我测了，四家都差不多」。九成的原因是样本集没有区分度。
4.1 最常见的错误：只测爆款
拿十几个爆款 ASIN 去测，这类商品的数据最全，所有供应商都能返回完整字段，测出来当然都是满分。
你测的不是供应商的能力，是亚马逊对爆款的数据完备度。
4.2 有区分度的样本长什么样
五类，缺一不可：
- 跨类目——至少 4 个一级类目。页面模板差异很大，字段可用性跟着变
- 跨站点——至少 US 加两个非美站点。我见过太多「国内测试一切正常，铺到欧洲发现少了一半维度」的情况
- 含多变体——变体数 20 以上的商品，测变体级字段的深度
- 含弱数据商品——新品无评论、长期缺货、无 Buy Box。这是填充率的试金石，形态 A 和形态 C 在这类商品上差距最大
- 含深页——搜索场景必须测到第 5 页
规模上，每家 200 到 500 条足够。太少噪声大，太多浪费预算。
4.3 执行的四条纪律
同一批 ASIN
同一时间窗 ← 压缩在几小时内，避免价格与库存自然波动
同一并发水平
同一重试策略 ← 最容易出错
最后一条：如果给 A 家配了三次重试而 B 家只跑一次，A 的可用率虚高，成本却是真实的三倍。这不是在测供应商，是在测你的重试策略。
五、五个位置决定成败
跑过多轮之后，供应商之间的分化几乎总是集中在以下五处。时间有限就优先看这五个。
5.1 广告位标记与自然位次
区分度最高的一项。有 isSponsored 与 organicRank 的供应商是少数，多数只有页面位次。
缺了它，「排名」这个指标就是系统性失真的。真实案例：某团队监测核心词连续四个月稳定第 3 位，判断自然流量触顶，准备加大投放。补上 isSponsored 后重算，真实情况是自然位第 1，前面插了两个竞品的 Sponsored Brands 广告。自然表现其实一直在变好。
反向的更常见：某个词监测到「排名很好」，实际是第 4 页，前三页铺满竞品 Sponsored Products，自然流量接近零。
没有广告位字段，你连「我的排名是多少」都回答不准。
5.2 变体级字段深度
很多供应商的 variants 只有 ASIN 列表，没有每个变体的价格、库存、评分。等于告诉你「有五个变体」，但没告诉你哪个在卖、哪个缺货、哪个评分在掉。
真实案例：某小家电团队跑出「用户普遍抱怨续航不足」，但没法落地——不知道哪个规格。补上 variant 后定位到某一容量规格，问题集中在低配版。应对方案从「全产品线改电池」变成「调整低配版规格描述与预期管理」，成本降一个数量级。
变体归属这个字段，把洞察从「有道理」变成「可执行」。
5.3 搜索深页
前两页各家都行，第 3 页往后分化明显：有些返回重复记录，有些直接空。
后果比听起来严重：竞争度判断完全依赖深页。只看到前两页，你会系统性地低估竞争强度。而且当你只能看到两页时，「这个市场竞争不激烈」这个判断描述的是你的观测能力，不是市场。
5.4 促销与优惠券
coupon、promotions、Subscribe & Save 折扣，覆盖率普遍偏低，但对定价决策影响很大——只看标价会系统性高估竞品实际成交价。
5.5 卖家与 Buy Box 信息
offerCount、buyBoxWinner、卖家评分，在跟卖激烈的品类里是核心指标，很多返回里完全没有。
六、失败要分四类，第三类最贵
可用记录率告诉你总体表现，但不告诉你怎么改。拆开看：
def classify(record):
if record.get("_http_status") != 200:
return "hard" # 硬失败：可见
if not record.get("asin"):
return "soft" # 软失败：200 但主体为空
flat = flatten(record)
if not all(f in flat for f in CONTRACT["P0"]):
return "partial" # 部分失败：静默 ← 核心目标
return "ok"
| 类型 | 表现 | 可见性 | 成本 |
|---|---|---|---|
| 硬失败 | 非 200、超时 | 完全可见 | 低，重试即可 |
| 软失败 | 200 但主体为空 | 半可见 | 中，要标记缺失 |
| 部分失败 | 200、结构完整，P0 为 null | 静默 | 最高 |
| 陈旧数据 | 有值但过期 | 静默 | 高，要监控新鲜度 |
第三类是本文的重点。它不报错、不告警、不引发账单争议，只会让报表慢慢失真。上面 classify 里 partial 那一行，就是为了专门抓它。
静默失败的成本不体现在 API 账单上，体现在基于错误数据做出的决策上。这类损失没有上限，也没有账单可查。
七、把回归排进周常
一次验收只能证明「现在能用」。供应商的覆盖能力会漂移——页面改版、策略调整、容量变化，都会让上个月的结论失效。
建议每周跑一次固定样本（50 到 100 条即可，成本极低），记录四个数字的趋势：
中位延迟 / p95 延迟 / 可用记录率 / 平均覆盖率
做成折线图。投入极小，但这是把「数据供应商」从黑盒变成可管理组件的唯一办法。
八、几个实操问答
Q：各家字段名不一样，怎么比？
这正是要写字段契约的原因——契约用你自己的命名，测试脚本里加一层映射。映射本身也是有价值的信息：需要写复杂映射才能对上的字段，通常说明该供应商的数据模型与你的业务模型有偏差。
Q：cov_threshold=0.8 怎么定？
0.8 是经验起点。业务严重依赖变体数据的话，把 variants 相关字段全提到 P0，阈值放宽到 0.7；要求极高完整性就提到 0.9。这个阈值应该由业务方定，不是工程师定。
Q：测出来各家都差不多？
大概率是样本集缺区分度（第四节）。换一批含深页、弱数据商品、多变体、非美站点的样本再试。
Q：这套方法要跑多久？
写契约半天（主要是跟业务方对齐 P0），跑测试一天，分析半天。**两天能跑完四家候选。**比起读两周官网、发邮件要字段字典、最后靠感觉拍板，投入产出比高太多了。
九、小结
回到标题那个问题：你的亚马逊数据 API 到底缺了哪 46 个字段？
答案不在任何一份对比表里，在你自己跑出来的那四个数字里。
1. 先写字段契约，再选供应商 ← 顺序不能反
2. 覆盖率和填充率必须一起看 ← 高覆盖低填充最危险
3. 唯一可比口径是每千条可用记录成本 ← 起售价都是陷阱
4. 回归排进周常 ← 一次性验收只证明「现在能用」
需要商品与搜索的公开对象数据，可以用 Pangolinfo Amazon Scraper API；评论场景走 Pangolinfo Amazon Review API；让 Agent 直接取数走 Pangolinfo Amazon Data MCP。可以从 Pangolinfo 控制台获取 API Key跑一轮盲测，文档见 Pangolinfo Amazon Data MCP 技术文档
**最后一句：这套脚本请用在包括我们在内的每一家候选身上。**供应商自己报的数字，无论谁报的，都该被验证。
