为什么 Amazon 要开放 MMM API
2024 年之前，亚马逊的 MMM 数据只能通过 Amazon Ads Console 手动下载 Excel 报告。品牌主每次拿到数据都要经历一套繁琐的流程：登录控制台、点击申请、等待处理、下载文件、手工整理列名、再上传到建模工具。这个流程平均要消耗半天时间，而且容易出错。
更大的问题是：Amazon 的媒体数据（DSP 展示广告、Sponsored Products、Sponsored Brands）和零售销售数据（ASIN 级别的单量、促销数据）散落在不同的报告里，格式不统一。建模师要把这些拼在一起才能开始建模。
Amazon MMM API（目前已 GA）解决了这个问题。它把上面所有数据合并成一套标准化的异步 API，覆盖 21 个市场、9 个端点，并且明确定位为面向 MMM 合作伙伴（ISV） 使用，而不只是终端广告主。
关键定位：Amazon 提供的是"数据管道"，不是建模工具。它把自己的媒体和零售信号开放给第三方 MMM 平台（比如 SparkX）来建模和优化。
四大 API 模块
整个 API 体系由四个模块组成，每个模块职责清晰：
品牌组列表
查询你账户下被授权的品牌实体（Brand Group），每个品牌组对应一套 ASIN + 广告 Campaign 的组合。所有后续操作都基于 brandGroupId。
品牌组覆盖配置
在默认品牌组基础上，按 ASIN 或 Campaign ID 添加或排除特定数据。最多 100 条 Override 批量提交。用于精细化控制报告范围。
数据报告请求
核心模块。提交报告请求（时间范围、地理粒度、指标类型），异步生成包含媒体和销售数据的多个文件包。
报告状态监控
轮询报告生成进度（PENDING → PROCESSING → SUCCEEDED），获取下载 URL，支持列出账户下所有报告。用于自动化工作流。
数据维度与限制
三个关键维度
每次提交报告请求时，需要指定三个维度的组合：
- 时间粒度 (timeUnit)：
DAILY或WEEKLY。WEEKLY 要求完整周（以周六或周日结尾），DAILY 无此限制。 - 地理粒度 (geoDimension)：
COUNTRY（全部市场）、POSTAL_CODE（邮编级，限 6 个国家：US/CA/UK/DE/FR/ES/IT）、DMA（仅美国）。 - 指标类型 (metricsType)：
MEDIA_ONLY（仅媒体投放数据）或MEDIA_AND_SALES（含 ASIN 级别销售数据）。
数据历史上限：最多申请过去 3 年数据。
数据新鲜度：最新数据只到上周日（Amazon 保留 1 周用于数据校验），加上报告生成时间最长 24 小时，实际数据延迟约 8-9 天。
接入区域：API 端点仅限北美（NA）：https://advertising-api.amazon.com，但可请求全球 21 个市场的数据。
Brand Group 审批：需通过 Amazon Ads Console 人工注册，并联系 mmm-support@amazon.com 开通 Brand Group 访问权限，无法全自动开通。
支持的 21 个市场
北美：US、CA、MX；南美：BR；欧洲：UK、DE、FR、IT、ES、NL、BE、PL、SE、TR；中东：UAE、KSA、EG；亚太：JP、AU、IN、SG。
输出文件清单
报告生成后，urls 字段会返回一组临时下载链接（有过期时间），包含以下文件：
| 文件名 | 内容 | 可用地理粒度 |
|---|---|---|
AggregatedSummaryReport.xlsx | DSP + Sponsored Ads + 销售汇总摘要 | 全部 |
CreativeGrainNationalCampaignPerformanceMetrics.tsv.zip | DSP 创意粒度：买量类型、创意形式、设备类型、展示/点击/花费 | 全部 |
AdGrainGeoIPCampaignPerformanceMetrics.tsv.zip | DSP 广告粒度 + 地理维度 | 邮编、DMA |
SSPAGeoCampaignPerformanceMetrics.tsv.zip | Sponsored Ads（SP/SB/PDA）地理级 | 全部 |
SSPANationalCampaignPerformanceMetrics.tsv.zip | Sponsored Ads 全国级 | 邮编、DMA |
CampaignToAsinMapping.tsv.zip | Campaign ID 与 ASIN/品牌的映射 | 全部 |
TotalSalesGeoOrders.tsv.zip Sales | 核心销售文件：ASIN × 地理 × 周 × 销量/销售额/零售价 | 全部 |
TotalSalesPromo*.tsv.zip Sales | 促销活动 ASIN 列表、促销详情、促销销售（共 3 个文件） | 全部 |
TotalSalesGeoOrdersSns.tsv.zip Sales | Subscribe & Save 订阅数据：新订和续订 | 全部 |
NationalAsinEngagement.tsv.zip Sales | ASIN 级别加购次数（购物参与度信号） | 仅 COUNTRY |
STVRecommendations.pdf | 流媒体电视（STV）最佳实践 | 全部 |
注意：Sales 文件仅在 metricsType=MEDIA_AND_SALES 时出现。如果 DSP 或 Sponsored Ads 文件缺失，说明报告时间段内没有对应的广告活动数据。
完整调用流程（六步）
Amazon MMM API 是异步 API，不能同步拿到结果。完整流程如下：
获取 Brand Group 列表
POST /mmm/v1/brandGroups/list — 传入 countryCode 过滤，返回 brandGroupId 列表。这是后续所有操作的基础。
确认 ASIN 和广告活动
GET /mmm/v1/brandGroups/{id}/products 和 /campaigns — 核查品牌组包含的 ASIN 和 Campaign 是否符合预期，支持分页（nextToken）。
按需创建覆盖（可选）
POST /mmm/v1/brandGroupOverrides — 用 INCLUDE/EXCLUDE 类型批量增减 ASIN 或 Campaign，最多 100 条/请求。有权限问题会返回 403。
提交报告请求
POST /mmm/v1/reports — 指定 brandGroupId、metricsType、geoDimension、timeUnit、startDate/endDate，以及 dueDate。返回 reportId。
轮询报告状态
GET /mmm/v1/reports/{reportId} — 状态流转：PENDING → PROCESSING → SUCCEEDED（或 FAILED/CANCELED）。最长等待 24 小时，超时联系 mmm-support。
下载报告文件
状态变为 SUCCEEDED 后，urls 字段包含各文件的临时下载链接（注意 urlsExpireAt）。文件格式为 TSV.zip 和 XLSX，需要解压后处理。
# 示例：提交一个 MEDIA_AND_SALES + 邮编粒度 + 按周汇总的报告
curl -X POST https://advertising-api.amazon.com/mmm/v1/reports \
-H "Amazon-Advertising-API-ClientId: amzn1.application-oa2-client.xxxx" \
-H "Amazon-Advertising-API-Manager-Account: amzn1.ads1.ma1.xxxx" \
-H "Authorization: Bearer Atza|xxxx" \
-H "Content-Type: application/json" \
-d '{
"reportName": "Q2-2026 Running Shoes Weekly by ZIP",
"configuration": {
"brandGroupId": "d0145381-b4a9-41a0-83de-e56c8f07d712",
"metricsType": "MEDIA_AND_SALES",
"geoDimension": "POSTAL_CODE",
"timeUnit": "WEEKLY"
},
"startDate": "2026-01-01",
"endDate": "2026-06-30",
"dueDate": "2026-07-20"
}'关键注意事项
1. 认证体系与 Amazon Ads API 共用
MMM API 使用 Login with Amazon (LwA) 的 OAuth 2.0 流程，和普通 Amazon Ads API 共享认证体系。但有一点不同：MMM API 不需要 Profile ID（不同于 Campaign Management API 必须指定 profileId），只需要 Manager Account ID。
需要的 Header：Amazon-Advertising-API-ClientId、Amazon-Advertising-API-Manager-Account、Authorization: Bearer <token>。授权 scope 使用 advertising::campaign_management。
2. Brand Group 需要人工审批
Brand Group 的访问权限必须由 Amazon MMM 项目经理（Program Manager）在后台手动配置。无法通过 API 自助开通。在申请审批期间，调用 brandGroups/list 会返回空数组。整个开通周期通常需要 1-2 周。
3. TSV.zip 格式的处理
绝大多数输出文件是 .tsv.zip 格式，解压后是 Tab 分隔的文本文件。字段名和 schema 在不同报告类型（DAILY/WEEKLY、COUNTRY/POSTAL_CODE/DMA）下会略有差异。接入前需要做 schema mapping。
解压 TotalSalesGeoOrders.tsv.zip 后，列结构大致为：
asin | week_start | postal_code | sold_units | retail_price | retail_sales | currency
这就是 SparkX 需要的 dependent variable（被解释变量）格式 — 用 retail_sales 作为 KPI，week_start 作为时间轴，加上 Sponsored Ads 和 DSP 的花费作为 media channels，即可直接进入 MMM 建模。
接入 SparkX 的路线
从 SparkX 的角度，Amazon MMM API 是一个高价值的数据连接器，而不是竞品。Amazon 提供原始数据，SparkX 负责建模、归因和预算优化。
数据流向
具体的字段对应关系：
- 媒体花费（因变量候选）：DSP
spend+ Sponsored Adsspend，按渠道类型分列 - 销售 KPI（被解释变量）：
TotalSalesGeoOrders的retail_sales - 促销控制变量：
TotalSalesPromoFacts的total_discount和促销期间的 dummy 变量 - 参与度信号（辅助特征）：
NationalAsinEngagement的加购次数，可作为意向信号 - 地理维度：如果使用邮编或 DMA 粒度，可在 SparkX 中做分区域 MMM（Geo-level modeling）
接入难点与解法
- 异步轮询：SparkX 后端需要维护一个 job queue，在报告生成完成后自动触发下载和预处理，而不是让用户等待。
- 文件格式转换：TSV.zip → 标准 CSV，字段映射到 SparkX 的列命名规范（date、kpi、channel_1_spend 等）。
- 多 ASIN 汇总：同一品牌组下通常有多个 ASIN，需要先做品牌级别汇总（
GROUP BY week_start），再进入 MMM。 - S&S 数据增强：Subscribe & Save 的订阅单量是 Amazon DTC 品牌的重要 retention 指标，可作为额外的 KPI 维度在 Expert Mode 中建模。
SparkX 计划在 v1.4 中推出 Amazon Ads 一键连接（OAuth 授权 → 自动拉取 → 自动映射 → 直接进入 Instant Mode）。对于已在 Amazon 注册 MMM 的品牌方，整个数据准备时间可以从"半天手工整理"压缩到 5 分钟。
总结
Amazon MMM API 的开放是 MMM 生态的重要信号 — 平台方开始主动把数据开放给第三方建模工具，而不是试图自己做建模。这和 Google 开源 Meridian、Meta 维护 Robyn 的逻辑一致：平台的核心竞争力是数据和流量，建模和决策优化是第三方工具的机会。
对于在 Amazon 上有广告投放的品牌方，现在有了一个相对标准化的方式拿到"媒体花费 + ASIN 销售"的对齐数据集，这本身就解决了 MMM 最耗时的数据准备环节。剩下的问题是：拿到数据之后，用什么工具建模、用什么逻辑优化预算。
如果你正在评估如何把 Amazon 渠道纳入整体 MMM 框架，欢迎联系我们或直接在 Instant Mode 上传数据试跑一次。