# Storelift API

URL: https://storelift.net/zh/guide/storelift-api/
Language: zh
Updated: 2026-10-15

控制台上能看到的一切，也都是 JSON 端点。33 个 GET 端点读取你追踪的应用和整个市场；POST /v1/actions 先预览一项改动，再由 POST /v1/actions/confirm 执行。这样，脚本、表格任务或 CI 步骤都能读到同样的数字并据此行动。API 包含在 Pro 和 Studio 套餐中。完整参考见 /docs/api/，机器可读的规范见 /openapi.json（OpenAPI 3.1）；如果是让 AI 助手使用同一份数据，通常更适合用 MCP 服务器，所有套餐都包含。

## 基础地址与身份验证

基础地址是 https://storelift.net/v1。在 Settings → API 中创建密钥；密钥只显示一次，且只以哈希形式存储，所以丢失的密钥只能更换，无法找回。

通过 x-api-key 发送；如果你的客户端只支持 Authorization 请求头，也可以作为 bearer 令牌发送：

curl -s https://storelift.net/v1/apps \
-H "x-api-key: sl_live_..."

NOTE: API 访问包含在 Pro 和 Studio 套餐中：每月 $20 起，Studio 为 $60。降级后密钥仍会保留，再次升级即可恢复原有集成。

## 33 个端点

| 端点 | 返回内容 |
| --- | --- |
| GET /v1/apps | 该账户追踪的应用。其他所有调用都从这里开始，id 就取自这个端点。 |
| GET /v1/apps/{id} | 单个应用，以及最近一次测量的快照。 |
| GET /v1/apps/{id}/keywords | 某个店面中每个追踪关键词的当前排名，附测量状态和搜索深度。 |
| GET /v1/apps/{id}/rivals | 排在你前面的应用，每个都列出它在哪些词上超过你，以及双方的排名。 |
| GET /v1/apps/{id}/ai | AI 助手在回答你所在品类的问题时会不会提到你的应用，附已保存的数据序列。需要 Studio 或 Enterprise 套餐。 |
| GET /v1/apps/{id}/history | 每个关键词的排名序列，截取到套餐允许的历史时长。 |
| GET /v1/apps/{id}/page | 你自己的产品页面，与商店实际展示的一致，覆盖两个平台，并附上检测到的带日期改动。 |
| GET /v1/apps/{id}/reviews | 近期评论，附星级汇总、本次测量新增的评论数，如有测量还包括 Google Play 端。/reviews/search 可按文本、星级、版本和日期搜索完整存档；/reviews/stats 返回评分分布、逐日曲线和按版本拆分。 |
| GET /v1/apps/{id}/timeline | 产品页面的带日期改动：版本、截图、活动、推荐位、关键词字段修改，每一项都附上前后的关键词排名变化。 |
| GET /v1/apps/{id}/featuring | 按国家/地区列出的编辑卡片、App 内活动和 Apple 的“你可能也会喜欢”货架，附推荐和新活动的带日期历史。dedicated 用来区分专门讲这个应用的故事和它所在的合集。 |
| GET /v1/apps/{id}/charts | 应用在所属类别和店面的热门榜单排名，附数据序列。 |
| GET /v1/apps/{id}/revenue | 来自已连接数据源的收入和下载量：App Store Connect 的单位数、Google Play 的安装量、RevenueCat 的 MRR、订阅和试用。未连接任何数据源时返回 connected:false。权限范围 revenue:read。 |
| GET /v1/apps/{id}/subscriptions | 来自 RevenueCat / Adapty webhook 的订阅事件数，按天、国家/地区和月度同期群统计。权限范围 revenue:read。 |
| GET /v1/apps/{id}/funnel | App Store 展示次数 → 产品页面浏览 → 下载量：今天的数据点，以及来自 App Store Connect 分析的逐日历史。权限范围 revenue:read。 |
| GET /v1/apps/{id}/pricing | 来自 RevenueCat / Adapty webhook：按产品和国家/地区列出的现行价格，每个固定价格周期内的试用、首次付费和收入，以及优惠代码。权限范围 revenue:read。 |
| GET /v1/apps/{id}/campaigns | 推广该应用的 Apple Ads 广告系列（按 App Store id 匹配）：花费、点击、安装、预算和状态，外加表现最好的关键词和搜索词。权限范围 ads:read。 |

/apps/{id} 下的端点接受 country 参数（店面代码，例如 us，默认为应用的第一个店面）；如果两个商店都在测量，还接受 platform=ios|android。

## 三种测量状态在传递中保持区分

写集成之前最值得读的就是这一部分。排名字段可以是一个数字，但“没有数字”其实有两种不同的含义，API 会把它们分开：

- measured: true，rank: 7：应用排在第 7 位。
- measured: true，rank: null：搜索已执行，但在 searchDepth 以内的结果里没有这个应用。
- measured: false：当天无法执行搜索，排名情况未知。

{
"country": "de",
"platform": "ios",
"live": true,
"measuredAt": "2026-09-19T02:14:08.921Z",
"keywords": [
{ "term": "traumdeutung", "measured": true, "rank": 7, "demand": 6, "searchDepth": 200 },
{ "term": "traumsymbole", "measured": true, "rank": null, "demand": 3, "searchDepth": 200 },
{ "term": "traumtagebuch", "measured": false, "rank": null, "demand": null, "searchDepth": null }
]
}

如果把后两种情况都当成 0，就会凭空造出一次并不存在的暴跌，基于它算出的所有平均值也都会出错。如果你的代码只需要一个数字，请把 measured: false 当作序列中的缺口，而不是一个值。

## 账户、用量和搜索

四个端点，分别关于密钥本身和账户自己的记录。前两个不计费，脚本可以在开始工作前先确认能读什么、还剩多少额度。search 和 fetch 沿用 ChatGPT 对 deep research 连接器要求的格式：查询返回 id，id 返回记录。

| 端点 | 返回内容 |
| --- | --- |
| GET /v1/account | 密钥归属：套餐、身份验证方式、权限范围、可读取的应用、额度余额。消耗 0 额度。 |
| GET /v1/usage | 每项配额的 used / limit / reset、今天的 Hive 额度以及每秒请求上限。消耗 0 额度。 |
| GET /v1/search?q= | 搜索你自己的应用、追踪的关键词和竞品；返回供 /v1/fetch 使用的 id（ChatGPT deep research 格式）。 |
| GET /v1/fetch?id= | search 返回的 id 对应的完整记录：一张应用卡片、一个带历史的关键词，或一个竞品及它超过你的那些词。 |

## Hive：任意应用，任意市场

上面的端点读取你自己追踪的应用。Hive 端点读取的是整个网络测量到的数据：榜单、任意应用的每日测量、关键词搜索结果列表、竞品的关键词，以及任意应用的收入和下载量。它们需要密钥上单独的权限范围，每次调用消耗的额度也更多；每个套餐另有每日 Hive 额度，保证一个月的额度能用满一个月。

| 端点 | 返回内容 | 权限范围 |
| --- | --- | --- |
| GET /v1/hive/charts?country=&kind=&genre= | 某个店面的 Top Free、Top Grossing 或 iPad 榜单（深度 100），截至最近一天。 | hive:read |
| GET /v1/hive/apps/{storeId}?country= | 任意应用最新的每日测量：评分数、评分、版本、价格、星级分布、分类徽章，以及支持的语言、即将开始的 App 内活动、推广文本和推荐的 App 内购买项目。 | hive:read |
| GET /v1/hive/keywords/{term}/ranks?country=&days=&top= | 某个关键词下每天谁排在哪里，最深 200 位（每次调用 1,000 行）。 | hive:read |
| GET /v1/hive/spy/{storeId}?country= | 竞品有排名的关键词，隐私过滤和每月 spy 额度与控制台相同。 | hive:spy |
| GET /v1/hive/estimate/{storeId}?country= | 任意 App Store 应用的全球月收入和下载量（首次读取进行中时返回 202）。 | hive:estimate |
| GET /v1/hive/movers?country=&kind=&genre=&days=&limit= | 与 N 天前的同一榜单相比，谁上升、谁下降、谁新上榜、谁跌出。每个变化都在两个测量日之间计算，回答中会写明这两天。 | hive:read |
| GET /v1/hive/new?days=&country=&limit= | 首次登上热门榜单的应用，最新的在前。回答会说明这些天里有多少天在索引覆盖范围内，所以每个首次上榜日期都是我们确实索引过的一天。 | hive:read |
| GET /v1/hive/find?genre=&country=&kind=&released=&rankMin=&rankMax=&text=&publisher=&page= | 在我们测量的榜单中查找应用：按分类、店面、榜单（Top Grossing、Top Free、Top Paid、Top iPad）、排名区间、首次上榜日期、名称或发行商筛选。每一行都带有该应用的收入和下载量。 | hive:read |
| GET /v1/hive/gap?ids=&country=&platform= | 最多五个应用的关键词差距并排对比：每个应用在哪些词上有排名、漏掉了哪些词。需要 Hive Explorer。隐私过滤与 spy 相同，每个应用都带有自己的测量状态，表格里的每个单元格都是测量得到的事实。 | hive:spy |
| GET /v1/hive/publisher/{publisherId} | Hive 见过的某个发行商的全部应用，以及每个应用首次上榜的日期。 | hive:read |
| GET /v1/hive/resolve?q=&country=&limit= | 通过名称、开发者、商店链接、App Store id 或包名查到任意应用的 id。名称会通过该店面的 App Store 搜索查找。 | hive:read |
| GET /v1/hive/similar/{storeId}?country= | 商店为任意应用展示的“相似应用”货架，按货架顺序排列，附每个应用的分类、名称和货架读取日期。 | hive:read |
| GET /v1/hive/reviews/{storeId}?country=&limit= | 任意应用在某个店面的近期评论，附星级分布；不含评论者姓名。 | hive:read |

这里不会传出任何个人信息：评论作者从不显示；竞品的某个关键词，只有在至少另外两个账户或你自己也在追踪时才会显示。

## 无需密钥即可试用

每个路径在 /v1/sandbox/ 下都有对应版本，完全不需要密钥：结构相同，使用固定的两个应用的数据集，日期随“昨天”一起滚动。响应中带有 x-sandbox: true。在 CI 中可以到 Settings 创建一个测试密钥（sl_test_）：它只从沙盒返回数据，不消耗额度，所有套餐都能用，即使测试密钥泄露也不会暴露任何数据。

curl -s https://storelift.net/v1/sandbox/apps
curl -s 'https://storelift.net/v1/sandbox/hive/keywords/sleep%20sounds/ranks?country=us&days=3&top=10'

## 写入和权限范围如何运作

- 每次写入都先预览。读取用 GET。POST /v1/actions 返回改动前后的 diff、所需额度和一次性令牌，不做任何修改；POST /v1/actions/confirm 才真正执行。令牌与操作、参数以及预览时目标的状态绑定，如果期间目标发生了变化，confirm 会返回 confirm_token_mismatch 和新的 diff，不写入任何内容。可执行的操作包括关键词、竞品、应用和分享链接、评论回复（所有套餐），以及 Studio 上在可编辑的 App Store 版本中修改产品页面文本、Apple Ads 的暂停、恢复和每日预算。完整列表见参考文档。
- 写入权限范围需要主动开启。每类写入都需要对应的权限范围（track:write、reports:write、reviews:write、ads:write、listing:write），创建密钥时默认都不勾选。测试密钥从沙盒返回数据，不会改动你的数据。账单仍在账户设置中管理。
- 请检查观测日期和状态。响应可能包含保留的测量值、已确认的数据缺失、待处理任务或错误。重复请求不会更新旧观测的日期。
- 收入数据有独立的权限范围。十个增长类端点（revenue、subscriptions、funnel、pricing、change-impact、campaigns、ads-keywords、ads-search-terms、ads-commands、search-popularity）只响应带有敏感权限范围 revenue:read / ads:read 的密钥，所以只有你主动选择，密钥才能读到收入数据。GA4 数据在控制台中查看。
- 历史时长跟随套餐。history 和 charts 都使用套餐的时间窗口，同一把密钥通过任一端点能回溯的范围完全相同。

## 错误

| 状态码 | error | 何时出现 |
| --- | --- | --- |
| 401 | missing_api_key | 请求中没有密钥。 |
| 401 | invalid_api_key | 密钥不存在或已被撤销。 |
| 401 | account_deleted | 密钥所属的账户已删除。 |
| 403 | plan_required | 当前套餐不含 API 访问。响应中会带上当前套餐。 |
| 405 | method_not_allowed | 读取用 GET；只有 /v1/actions、/v1/actions/confirm 和 /v1/apps/{id}/validate-listing（草稿放在请求体中）接受 POST。 |
| 400 | unknown_action | 目录中没有这个操作名；响应会列出可用的操作。 |
| 400 | invalid_arguments | 参数缺失或格式错误；响应会指出具体字段。 |
| 409 | confirm_token_expired | 令牌已超过 10 分钟，请重新预览。 |
| 409 | confirm_token_mismatch | 预览之后目标发生了变化；响应中带有新的 diff。 |
| 403 | write_limit_reached | 写入超出了保护限制（预算调整幅度、每日 Apple Ads 操作数、每日写入次数：追踪 200 次 / 评论回复 50 次）。 |
| 403 | test_key_read_only | 测试密钥从不写入。 |
| 404 | job_not_found | 该工作区中没有这个 id 的任务。 |
| 403 | workspace_suspended | 工作区已被暂停；具体原因可咨询支持团队。 |
| 403 | ip_list_required | 该工作区要求每把密钥都设置 IP 允许列表。 |
| 404 | not_found | 该账户中没有这个应用 id。 |
| 404 | unknown_endpoint | /v1 下没有这个路径。 |
| 402 | credits_exhausted | 本月额度已用完；响应中附有额度包的链接。 |
| 429 | rate_limited | 该密钥请求过于频繁；请按 Retry-After 指定的秒数等待。 |
| 429 | daily_hive_limit | 套餐今天的 Hive 额度已用完；在 00:00 UTC 重置。 |
| 404 | not_measured | 请求的应用、关键词或范围没有经过验证的观测记录。缺失数据不等于零。请检查请求参数，并查看响应所链接的文档，了解可用操作。 |
| 400 | bad_query | /v1/search 需要长度为 1–120 个字符的 q。 |
| 400 | bad_id | /v1/fetch 需要与 /v1/search 返回的完全一致的 id。 |
| 403 | asc_required | update_listing 需要已连接的 App Store Connect 密钥。 |
| 403 | asc_role | App Store Connect 密钥需要 Admin 或 App Manager 角色才能编辑元数据。 |
| 409 | no_editable_version | 目前没有可编辑的 App Store 版本；响应会列出现有版本的状态。 |
| 404 | locale_not_found | 该版本中没有这个店面语言；响应会列出已有的语言。 |
| 409 | changed_since_preview | 预览之后产品页面在 App Store Connect 中被修改过；未写入任何内容。 |
| 422 | asc_rejected | App Store Connect 拒绝了这项改动；它自己的错误信息在 detail 中。 |
| 409 | in_progress | 针对同一目标的写入仍在执行中。 |
| 403 | ip_not_allowed | 该密钥设置了 IP 允许列表，而这次请求来自其他地址。 |
| 401 | key_leaked | 该密钥在公开代码仓库中被发现，已自动撤销；请创建新密钥。 |

每个错误都是带有 error 字段的 JSON。plan_required 还会返回 plan，客户端可以直接告诉用户密钥属于哪个套餐，而不必去猜。

## FAQ

Q: 有请求频率限制吗？
A: 有，按密钥计算：按套餐限定的每秒请求数（超出返回 429 和 Retry-After）、在 x-credits-* 响应头中显示的每月额度，以及每日 Hive 额度。每次调用还会更新密钥的使用计数，你可以在 Settings 中看到旧密钥是否仍在使用。

Q: 免费套餐能用吗？
A: 用于 API 的正式密钥从 Pro 开始提供，也随额度包提供。免密钥沙盒和测试密钥所有套餐都能用，远程 MCP 服务器包含在 Free 套餐中，本站的免费工具完全不需要账户，免费套餐每天测量一个应用。

Q: 用 API 还是 MCP 服务器？
A: 脚本适合用 API：结构固定、一次调用、链路中没有模型。AI 助手适合用 MCP 服务器，因为每个工具都自带说明，助手能自己选出合适的调用，不需要你写集成。两者使用同一份测量数据，写入也都走同样的“先预览、再确认”流程。