Apple App Store App Reviews
Apple App Store 应用评价是公开的用户反馈记录，包含文字内容、评分、评价者身份、发布时间以及被评价应用的链接。这些记录可用于分析反馈、比较评分、补全应用目录和按时间监测评价变化。
主要特性
- 按已知应用 URL 批量输入在一个任务中提交一个或多个 apps.apple.com 商品页 URL，并用同一个 results_limit 控制此次请求保存的评价总数。
- 标准化公开评价记录通过统一评价结构读取评价文本、数值评分、评价者身份、选填媒体和稳定的记录字段。
- 应用与采集上下文在字段可用时将评价关联到应用标识或应用 URL，并保留发布时间与采集时间，形成可追溯的快照。
参数
| 参数 | 必填 | 描述 |
|---|---|---|
urls | 必填 | 必填列表，包含一个或多个解析后主机名为 apps.apple.com 或其子域的非空应用引用；Playground 接受绝对形式和省略协议的 // 形式，并支持用逗号或换行分隔。 |
results_limit | 可选 | 选填整数，范围为 1 到 2,000，用于限制当前任务保存的评价总数；backend 默认值为 100。 |
如何使用
提交已知应用 URL，跟踪异步任务，再分页读取该任务已经保存的评价记录。
- 准备至少一个解析后主机名为 apps.apple.com 的应用引用，并可选设置 1 到 2,000 的 results_limit。
- 向 /v1/apple-app-store/app-reviews 发送 POST 请求，并保存返回的 task_id。
- 轮询 GET /v1/tasks/{task_id}，直到状态变为 succeeded 或 failed。
- 从 data.results.items 读取记录，并在 has_more 为 true 时继续使用 next_cursor。
curl -X POST "https://api.socq.ai/v1/apple-app-store/app-reviews" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://apps.apple.com/us/app/chatgpt/id6448311069"]}'
# 轮询 GET /v1/tasks/{task_id}
# 读取 data.results.items；has_more 为 true 时继续使用 next_cursor最佳使用场景
- 检查应用反馈： 结合评价文本、评分和评价者信息，查看已知应用页面返回的公开用户反馈。
- 比较多个应用的评分： 按应用标识或应用 URL 对标准化记录分组，再比较本次提交中不同应用的评分分布。
- 保存评价时间快照： 将发布时间、采集时间和评价 ID 一同保留，以便区分新采集记录与较早快照。
使用建议
- 提交前逐项确认解析后的主机名为 apps.apple.com；子域与省略协议的 // 形式可以使用，其他主机会被拒绝。
- 按整个任务而不是单个应用设置 results_limit；省略时使用 100，可接受范围最高为 2,000。
- next_cursor 只用于继续读取 SocQ 已保存结果，不会请求另一个 provider 页面，也不会继续上游采集。
- 评价文本、评价者、评分、应用关联或媒体缺失时应视为未知，并在下游展示中省略 null 字段。
相关 API
需要其他类型的 Apple App Store 公开数据时，可以使用以下 API。
- Apple App Store App Detail API — 通过已知 App Store 商品页 URL 获取标准化公开应用标识、介绍信息、开发者与分类上下文、可见评分、价格和媒体。
- Apple App Store Rankings API — 从受支持的 Apple App Store URL 采集公开分类榜单条目，返回来源排名、应用身份、开发者、评分、评价数、价格和媒体字段。