概述
本指南将介绍如何使用 Music Analytics API，包括新用户的添加和授权、隐私要求和端点描述。如需了解更多内容，请查看支持文章。
此版本的更新内容
2026 年 2 月
Music Analytics API 的听众参与（Audience Engagement）和听众重合（Audience Overlap）端点新增了发行日期（Release Dates）功能。系统可以按照指定的发行起止日期过滤曲库数据，方便你比较新作与以往内容的表现。使用按发行日期分组（Group by Release Dates）功能还可以显示内容发行的具体日期。Music Analytics API 的版本保持不变。
Music Analytics API 的听众参与（Audience Engagement）和听众重合（Audience Overlap）端点新增了音乐类型（Genres）功能。你可以将曲库数据按照专辑或歌曲的类型和子类型过滤并分组，深入了解各类型内容的数据与相对表现。Music Analytics API 的版本保持不变。
2026 年 1 月
Music Analytics API 的听众参与（Audience Engagement）端点新增了详细结果（Detailed Results）功能。若调用此 API 端点时未使用人口统计数据（年龄、性别或城市），系统会自动返回精确计数，否则仍将显示向上取整后的数据。Music Analytics API 的版本保持不变。
2025 年 11 月
Music Analytics API 的所有听众（Audience）端点新增了异步批量处理功能。Music Analytics API 的版本保持不变。
2025 年 7 月
Music Analytics API 中所有听众（Audience）端点新增了多个 Apple Music 心情电台（Mood Stations）的容器子类型。Music Analytics API 的版本保持不变。
2025 年 6 月
Music Analytics API 中所有听众（Audience）端点新增了按日期分组（Group By date）功能。Music Analytics API 的版本保持不变。
添加用户
添加 Music Analytics API 用户的步骤如下：
在 iTunes Connect 中，点按“用户和访问”。
前往“密钥”页面。
点按加号（+）添加新用户。
在出现的“生成 API 密钥”对话框中，输入用户名（例如“Johnny Appleseed”），并在“访问”栏中为用户选择“管理”或“技术”职能。目前两个职能暂无区别。
点按“生成”。新用户将出现在“有效”列表中。
如果从未下载过 API 密钥，可点按“下载 API 密钥”链接。请妥善保管密钥，如有需要可进行备份。
【注】每个用户或共用账户的团队（例如共用邮箱账户）拥有专属的 API 密钥，且密钥只能下载 1 次。如果用户的密钥丢失或泄露，应删除该用户，然后将其添加为新用户。
生成并下载 API 密钥后，请返回“密钥”页找到 Issuer ID。此 ID 为字母数字序列，由 36 个字符组成；每个内容提供商的 ID 不同。用户登录至 Music Analytics API 时必须提供此 ID。
授权
将用户添加至 Music Analytics API 后，请确保其出现在“密钥”页中的“有效”列表中，并准备好以下文件和信息：
musicanalytics-utils-0.2.0.jar 文件
【注】使用此脚本需要 Java 8.0 或更高版本和 Java 开发工具包（JDK）。
一个单独的私钥文件（如：AuthKey_1234567890.p8）
Issuer ID（位于“有效”列表上方。此 ID 为字母数字序列，由 36 个字符组成；每个内容提供商的 ID 不同。用户登录至 Music Analytics API 时必须提供此 ID。）
准备就绪后，请使用命令提示符运行程序（如 macOS 中的“终端”或同类型的第三方程序），导航到文件目录，然后按以下步骤操作：
键入“java -jar musicanalytics- utils-0.2.0.jar -c {你的 Issuer ID} -f {你的私钥文件名}”，以执行 musicanalytics-utils-0.2.0.jar。你将收到一个 JSON Web 令牌（JWT），由 270 个区分大小写的字符组成。你需要测试此令牌。
【注】JWT 的有效期为 20 分钟。JWT 失效后，请重复步骤 1 以刷新令牌。
通过生成 curl 请求来测试 JWT（例如：curl -H "Authorization: Bearer {输入完整的 JWT}" https://musicanalytics.apple.com/v4/queries）。
如果 Music Analytics API 授权成功，你将收到 HTTP 状态代码 200。
如需进一步了解 Music Analytics API，你可以发送已验证的 GET 请求，查看请求和响应示例以及 API 查询规范。有关更多信息，请参见端点描述。
隐私要求
使用 Music Analytics API 查询时，若相关的数据量未达到最低门槛，系统不会返回结果。严禁对用户数据进行去匿名化处理，此类行为或可导致你的访问权限被暂时禁用或永久撤销。
端点描述
每个端点均支持 GET 和 POST 请求。请求的基础网址（URL）为 https://musicanalytics.apple.com/v4/queries/。
用户需获得授权才能接收和访问 GET 或 POST 请求的结果。
GET 请求：列出可查询的字段及其适用值范围。
POST 请求：根据你设置的条件返回最新结果。
如果用户未收到 HTTP 状态代码 200，则该用户可能未被授权，请按前文所述的步骤为其授权。
我们强烈建议你在获得授权后，在所有可用的查询路径上执行 GET 请求。系统将返回可查询的维度、查询示例等信息供你参考。
Audience Engagement（听众参与）
GET／POST：https://musicanalytics.apple.com/v4/queries/audience-engagement
支持按特定容器（用户发现音乐的位置）查询音乐内容的相关数据。
提供指定艺人／专辑／歌曲的汇总数据，包括听众数量（不重复计数）和播放次数；以及听众收听行为和来源等数据，如结束原因类型、流媒体来源、容器子类型等。
Audience Overlap（听众重合）
GET／POST：https://musicanalytics.apple.com/v4/queries/audience-overlap
用户可按多种维度查询听众数量和播放次数，也可按特定容器（用户发现音乐的位置）查询音乐内容的相关数据。此外，用户还可以指定两个时间段，查询艺人／专辑／歌曲在两个时间段的收听数据并对比数据。
字段名称 | 全称 | 定义 | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
primary_audience_lc | Primary Audience Listener Count | 符合第一个时间段指定条件的听众总人数。 | |||||||||
primary_difference_lc | Primary Difference Listener Count | 符合第一个时间段指定条件，但不符合第二个时间段指定条件的听众总人数。 | |||||||||
captured_lc | Captured Listener Count | 同时符合第一个和第二个时间段指定条件的听众总人数。 | |||||||||
secondary_audience_lc | Secondary Audience Listener Count | 符合第二个时间段指定条件的听众总人数。 | |||||||||
primary_audience_pc | Primary Audience Play Count | 符合第一个时间段指定条件的听众在第一个时间段内播放的总次数。 | |||||||||
primary_difference_pc | Primary Difference Play Count | 符合第一个时间段指定条件，但不符合第二个时间段指定条件的听众在第一个时间段内播放的总次数。 | |||||||||
primary_captured_pc | Primary Captured Play Count | 同时符合第一个和第二个时间段指定条件的听众在第一个时间段内播放的总次数。 | |||||||||
secondary_captured_pc | Secondary Captured Play Count | 同时符合第一个和第二个时间段指定条件的听众在第二个时间段内播放的总次数。 | |||||||||
secondary_audience_pc | Secondary Audience Play Count | 符合第二个时间段指定条件的听众在第二个时间段内播放的总次数。 | |||||||||
异步批量处理
发送 POST 请求至听众参与（Audience Engagement）或听众重合（Audience Overlap）端点，并在稍后获取结果。此类请求一次只支持处理一个查询。因此，如果已有一个正在运行的查询，新的请求将无法执行，系统会显示响应代码 400，并在返回的信息中列出正在占用计算资源的查询 ID。发现来源宏观分析（Macro Discovered-In）的参数“first-stream-since”所指定的时间不得早于“played-in”结束日期的三年前。
端点 | 类型 | 描述 | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
/request | POST | 请求在后台运行查询进程。系统会返回一个查询 ID，以供你检索结果。 | |||||||||
/status?queryId= | GET | 请求查看查询状态。系统将返回以下结果之一： In Progress（正在处理） Failed（失败） Cancelled（已取消） Ready（准备就绪） Expired（已过期） | |||||||||
/get?queryId= | GET | 请求在查询完成后返回结果。结果有效期为 24 小时。 | |||||||||
/cancel?queryId= | GET | 请求取消 API 调用。 | |||||||||
Macro Discovered-In（发现来源宏观分析）
此功能可以帮助你了解音乐发现与再互动次数的增长情况。系统会搜索你所有的曲库数据，识别出哪些内容存在播放量意外激增的现象，并找出听众的发现来源，以此衡量编辑推荐或营销活动对内容曝光度的影响。
新增“discovered_entity”参数，可根据实体类型（艺人／专辑／歌曲）查询听众的发现来源。在宏观维度查询的“discovered_in”定义中，此字段为必填项，且应当与“group_by”中的实体名称相匹配。
字段 | 描述 | 结构 | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
discovered_entity | 修改发现来源分析（Discovered-In）的过滤条件，使系统基于指定的实体类型（艺人／专辑／歌曲）统计听众数据。你需要在该字段中输入实体名称，并在“group_by”子句中使用相同的名称。如果已指定“discovered_entity”，则可以不添加实体过滤条件（即 macro + discovered_in 会生效）。 使用“discovered_entity”时，系统会针对每个实体单独计算听众发现数据。例如，指定“song_id”时，每个 ID 的分组只会包含发现过该歌曲的听众。 示例：song_id、artist_id、album_id。 | "discovered_entity": {"type": "string",} | |||||||||
查询量提升
每次查询可指定的实体数量上限提高，现为 5,000 个艺人 ID、10,000 个专辑 ID 和 10,000 个歌曲 ID。宏观维度查询的回溯范围由标准 API 调用的 31 天延长至 365 天。
City（城市）
GET／POST：https://musicanalytics.apple.com/v4/city
提供城市 ID（consumer_city ID）和城市名（consumer_city_name）对照表供用户参考；也支持按特定的城市 ID 过滤数据，以获取相应的城市名。
Flagged Streams（待核查播放量）
GET：https://musicanalytics.apple.com/reports/flagged-streams/v3
列出所有被标记的内容播放量，提供标准的报告字段。
In Review Content（核查内容）
GET：https://musicanalytics.apple.com/reports/in-review-content/v2
列出所有当前被标记为需要核查的专辑，提供标准的报告字段。
Excluded Streams（播放量剔除）
GET：https://musicanalytics.apple.com/reports/excluded-streams/v2
每月汇总列出所有不被纳入版税计算和版税报告的内容。