API 文档

说明 REST 端点、参数与响应模式。

基础 URL: https://appatlas.dev/api/v1

Android SDK 版本

Maven Central 上 dev.appatlas:atlas-links 的最新发布版本。响应体是单个 JSON 字符串。 Android 构件同版本一起发布，因此这也是 atlas-core、atlas-crash 与 atlas-crash-ndk 的版本。

Apple SDK 版本

CocoaPods trunk 上 AppAtlasSDK 的最新发布版本。响应体是单个 JSON 字符串。 Swift Package Manager 解析同一个标签，因此这也是 SPM 的版本。

.NET SDK 版本

NuGet 上 AppAtlas.Sdk 的最新发布版本。响应体是单个 JSON 字符串。

查询 Track ID

将 App Store 的 bundle_id 转换为数字 track_id。响应体是单个 JSON 字符串。未知标识符返回 404。

bundle_id — 反向域名形式的 bundle 标识符，例如 com.netflix.Netflix。

查询 Bundle ID

将 App Store 的 track_id 转换为 bundle_id。响应体是单个 JSON 字符串。未知标识符返回 404。

track_id — 商店 URL 中的数字 ID，例如 363590051。

查询 Product ID

将 Microsoft Store 的 package_family_name 转换为 product_id。响应体是单个 JSON 字符串。未知标识符返回 404。

package_family_name — 包家族名称，例如 4DF9E0F8.Netflix_mcm4njqhnhss8。

查询 Package Family Name

将 Microsoft Store 的 product_id 转换为 package_family_name。响应体是单个 JSON 字符串。未知标识符返回 404。 Win32 产品（XP 开头的 ID）没有包家族名称，同样返回 404。

product_id — 12 位商店 ID，例如 9WZDNCRFJ3TJ。

访问令牌

用账户页面签发的 API 密钥换取 1 小时的 Bearer 访问令牌。每次调用都以 Authorization: Bearer 头发送。没有刷新令牌。过期后用密钥重新换取。撤销密钥会终止兑换并立即作废其现有令牌。

当前权限

返回此刻调用实际会被允许的操作：密钥策略与商店所允许能力的交集。上次核验过期的商店连接会在本次请求中重新核验，因此在商店端被吊销的密钥会先从 grants 中消失，而不是让你的下一次调用失败。 global 为账户级操作列表；grants 按（商店、操作组合）各一项，应用已合并。 readOnly 仅在既无 grants 也无任何账户级操作时为 true；自有前端的匿名读取以 readOnly true 和空列表作答。

应用信息

单个应用的完整信息：名称、描述、开发者、价格、评分、截图、视频和分类。每日历史由统计端点提供。

lang — ISO 639-1 语言代码。决定商店页面文本、价格和评论的语言。
country — ISO 3166-1 alpha-2 国家代码。决定商店区域，因此价格、货币和可用性也随之变化。
<identifier> — 与路径中商店对应的标识符：package_name、track_id / bundle_id 或 product_id / package_family_name。缺失时返回 422。

应用构建

你所管理应用的商店已接收构建列表，最新在前，并附带投递邮件会警告的内容。仅 App Store；其他商店返回空列表。与官方统计相同的方式进行保护：会话、拥有 data:read 的 API 密钥或嵌入授权可访问，其他调用者得到空列表而非 404，因此不会暴露构建是否存在。

page — 从 0 开始的页码。默认 0。
size — 每页构建数。 1-100，默认 5。
sort — 排序依据：uploaded（默认）、version 或 state。
direction — desc（默认）或 asc。
state — 仅保留这些处理状态，用逗号分隔（VALID、PROCESSING、INVALID、FAILED）。省略时为全部。
q — 匹配构建号或市场版本。
<identifier> — 与路径中商店对应的标识符：package_name、track_id / bundle_id 或 product_id / package_family_name。缺失时返回 422。

应用统计

每日快照，以及对有管理权限的调用者附带的商店自有统计。背后不运行页面抓取。返回多少历史由 <code>span</code> 一个参数决定。

span — 返回多少历史。默认 30d。 <code>n</code> 为自然数，<code>u</code> 为 d、w、m、y 之一，<code>A</code> 与 <code>B</code> 为日期形式。 <code>yyyy</code> 该年 <code>yyyy</code>-<code>MM</code> 该月 <code>yyyy</code>-W<code>ww</code> 该 ISO 周 <code>yyyy</code>-<code>MM</code>-<code>dd</code> 该日 <code>u</code> 当前这一格 <code>n</code><code>u</code> 当前这一格及此前 <code>n</code>-1 格 <code>n</code>c 最近 <code>n</code> 条记录 0c 不返回历史 <code>A</code>~<code>B</code> 从 <code>A</code> 到 <code>B</code>，包含两端 <code>A</code>~ 自 <code>A</code> 起 ~<code>B</code> 截至 <code>B</code> ~ 全部 <code>n</code>c~<code>A</code> 以 <code>A</code> 结束的 <code>n</code> 条记录 <code>A</code>~<code>n</code>c 自 <code>A</code> 起的 <code>n</code> 条记录 <code>n</code><code>u</code>~<code>A</code> 以 <code>A</code> 结束的 <code>n</code> 格 <code>A</code>~<code>n</code><code>u</code> 自 <code>A</code> 起的 <code>n</code> 格
official — 设为 1 时，对有权管理该应用的调用者，同时以 official 字段返回商店自有统计。判定权限使用你发送的标识符：Google Play 为 package_name，App Store 为 bundle_id。无权限者将被忽略。
lang — ISO 639-1 语言代码。仅用于把 App Store 的 bundle_id 解析为 track id；历史数据本身与语言无关。
country — ISO 3166-1 alpha-2 国家代码。观测按商店区域进行，因此它决定读取哪个国家的历史。
<identifier> — 与路径中商店对应的标识符：package_name、track_id / bundle_id 或 product_id / package_family_name。缺失时返回 422。

分类查询

将单个分类 id 解析为本地化的显示名称、商店链接和 embed 地址，与 categories 端点列出的行结构相同。此端点不读取应用标识符。

id — 要解析的分类 id。未知 id 返回 404。
content_type — 哪个列表：应用(app)或游戏(game)。默认为 app。
pricing_type — 返回的 link 和 embed 指向的榜单：免费(free)或付费(paid)。默认为 free。
lang — ISO 639-1 语言代码。决定商店页面文本、价格和评论的语言。
country — ISO 3166-1 alpha-2 国家代码。决定商店区域，因此价格、货币和可用性也随之变化。

排行榜

商店的排行榜（免费、付费或畅销榜），可针对整个商店或单个分类查询。返回与搜索相同的精简卡片。此端点不读取应用标识符。

id — categories 端点返回的分类 id。省略时返回整个商店的排行榜；未知 id 返回 404。
content_type — 哪个列表：应用(app)或游戏(game)。默认为 app。
pricing_type — 榜单类型：免费(free)、付费(paid)或畅销(grossing)。 Microsoft Store 没有畅销榜，请求 grossing 时返回 422。
lang — ISO 639-1 语言代码。决定商店页面文本、价格和评论的语言。
country — ISO 3166-1 alpha-2 国家代码。决定商店区域，因此价格、货币和可用性也随之变化。
count — 返回的最大条目数：1-200，默认 20。商店可能返回更少。
token — 上一页返回的续页令牌，首页省略。携带令牌时其他参数将被忽略，以令牌快照为准；令牌损坏返回 400。响应中的 token 为 null 表示列表结束。

一页用户评论，若存在开发者回复也会一并返回。将响应中的 token 回传即可翻页。

order_by — 排序方式：recent 或 helpful，默认 recent。 helpful 优先显示获赞最多的评论；在 Google Play 上是 Google 的相关性排序。
token — 上一页返回的续页令牌，首页省略。携带令牌时其他参数将被忽略，以令牌快照为准；令牌损坏返回 400。响应中的 token 为 null 表示列表结束。
official — 设为 1 时，从商店官方 API 读取评论而非抓取结果，仅适用于有权管理该应用的调用者。只有这些评论的 id 才能用于回复。无权限者将被忽略并返回抓取结果。参见响应中的 canReply。
lang — ISO 639-1 语言代码。决定商店页面文本、价格和评论的语言。
country — ISO 3166-1 alpha-2 国家代码。决定商店区域，因此价格、货币和可用性也随之变化。
count — 返回的最大条目数：1-200，默认 20。商店可能返回更少。
<identifier> — 与路径中商店对应的标识符：package_name、track_id / bundle_id 或 product_id / package_family_name。缺失时返回 422。

回复评论

为一条评论发布开发者回复。若已有回复则替换，即以此方式编辑。仅限调用者通过已连接商店密钥管理的应用；review_id 必须来自官方评论列表（reviews 的 official=1）。

删除回复

删除一条评论的开发者回复。仅限 App Store。 Google Play 的 API 只能替换回复而不能删除，因此 play-store 返回 400 unsupported_store。对没有回复的评论执行删除会静默成功。

翻译评论

将一条评论翻译成请求的语言，并检测原文所用语言。 reviews 端点返回过的任何评论都可以：抓取或官方列表、是否你自己的应用均可。该响应中每条评论都带有签名的 reviewKey；将其与评论的 title、content 原文一并发回，签名即可证明文本正是我们返回过的原文。翻译按评论和语言缓存；被编辑过的评论会重新翻译。

回复草稿

为一条评论撰写开发者回复草稿并以文本返回。不会向任何商店发送内容：发布仍由回复端点和人来完成。草稿以评论本身的语言撰写，响应还附带同一回复以 lang 语言渲染的副本供核对，两种语言相同时为 null。与翻译一样，将 reviews 响应中的 reviewKey 连同评论原文一并发回。相同的评论与选项会免费返回已存草稿；设置 regenerate 可重写（此前的草稿会保留）。

搜索

按关键词搜索商店。返回每个应用的精简卡片，而非完整信息。

query — 搜索关键词。实际为必填，缺失时返回 422。
lang — ISO 639-1 语言代码。决定商店页面文本、价格和评论的语言。
country — ISO 3166-1 alpha-2 国家代码。决定商店区域，因此价格、货币和可用性也随之变化。
count — 返回的最大条目数：1-200，默认 20。商店可能返回更少。
token — 上一页返回的续页令牌，首页省略。携带令牌时其他参数将被忽略，以令牌快照为准；令牌损坏返回 400。响应中的 token 为 null 表示列表结束。

相似应用

商店为该应用推荐的相关应用。卡片结构与搜索相同。

lang — ISO 639-1 语言代码。决定商店页面文本、价格和评论的语言。
country — ISO 3166-1 alpha-2 国家代码。决定商店区域，因此价格、货币和可用性也随之变化。
count — 返回的最大条目数：1-200，默认 20。商店可能返回更少。
token — 上一页返回的续页令牌，首页省略。携带令牌时其他参数将被忽略，以令牌快照为准；令牌损坏返回 400。响应中的 token 为 null 表示列表结束。
<identifier> — 与路径中商店对应的标识符：package_name、track_id / bundle_id 或 product_id / package_family_name。缺失时返回 422。

新闻

关于该应用的近期文章，按相关性和时效性筛选。先解析应用名称，再由窄到宽逐级放宽查询，因此冷门应用仍能获得结果，而普通名词类应用不会返回过多噪声。

lang — ISO 639-1 语言代码。决定商店页面文本、价格和评论的语言。
country — ISO 3166-1 alpha-2 国家代码。决定商店区域，因此价格、货币和可用性也随之变化。
count — 返回的最大条目数：1-200，默认 20。商店可能返回更少。
token — 上一页返回的续页令牌，首页省略。携带令牌时其他参数将被忽略，以令牌快照为准；令牌损坏返回 400。响应中的 token 为 null 表示列表结束。
<identifier> — 与路径中商店对应的标识符：package_name、track_id / bundle_id 或 product_id / package_family_name。缺失时返回 422。

新闻缩略图

将 Google 新闻的跳转 URL 解析为原文 URL，并提取各自的 og:image。与商店无关，接受任意文章 URL 列表。

深层链接列表

返回账户下的全部深层链接（最新在前），并附带各自的访问计数。需要密钥具备 deeplink:read 权限。

创建深层链接

创建链接并连同短网址返回。 short id 由服务端分配，无法指定。若已用尽套餐的链接额度，将以 403 plan_limit 拒绝。需要 deeplink:create 权限。

深层链接详情

返回单个链接及其完整路由配置。需要 deeplink:read 权限。

short_id — 链接的 short id，即短网址的最后一段。

修改深层链接

替换链接的名称与路由配置。配置为整体覆盖：未包含的字段会被删除而非保留。短网址不会改变，已分发的链接继续有效。需要 deeplink:update 权限。

short_id — 链接的 short id，即短网址的最后一段。

删除深层链接

删除该链接及其全部访问记录。短网址立即失效，且该 id 不会被重新分配。需要 deeplink:delete 权限。

short_id — 链接的 short id，即短网址的最后一段。

深层链接统计

展示访问的结果：总访问量、独立访客、每次启动最终选择的路径，以及按系统与国家的分布。在计入访问后数秒内的重复访问会保留为记录，但不计入此处任何数字。 options 始终描述整个周期，因此当前筛选排除的项仍会保留在选择器中。需要 deeplink:stats 权限。

short_id — 链接的 short id，即短网址的最后一段。
span — 聚合哪些天，使用与应用统计端点相同的窗口写法。默认 30d。记录条数（30c）会被拒绝：访问没有可计数的记录。
countries — 以逗号分隔的国家代码进行筛选；"unknown" 表示无国家信息的访问。
routes — 以逗号分隔的路径进行筛选；"failed" 表示所有候选均失败的启动。
os — 以逗号分隔的操作系统进行筛选。
channels — 以逗号分隔的渠道进行筛选；"unknown" 表示没有 ch 标签的访问。
campaigns — 以逗号分隔的营销活动进行筛选；"unknown" 表示没有 cp 标签的访问。
sources — 以逗号分隔的来源进行筛选：qr、push，普通打开为 web。

开始观察

注册该应用，在每日 00:00 UTC 采集快照。注册后，应用信息响应会附带 snapshots，记录评分、评论数、累计安装量（totalInstalls）和版本随时间的变化。

country — ISO 3166-1 alpha-2 国家代码。决定商店区域，因此价格、货币和可用性也随之变化。
<identifier> — 与路径中商店对应的标识符：package_name、track_id / bundle_id 或 product_id / package_family_name。缺失时返回 422。

停止观察

取消注册。已采集的历史数据不会被删除，只是不再采集新快照。

country — ISO 3166-1 alpha-2 国家代码。决定商店区域，因此价格、货币和可用性也随之变化。
<identifier> — 与路径中商店对应的标识符：package_name、track_id / bundle_id 或 product_id / package_family_name。缺失时返回 422。

App Atlas · 嵌入文档 · SDK 文档 · 服务条款 · 隐私政策 · Sign up

en · ko