获取 Apple App Reviews 高级结果（按任务 ID）

本接口用于按任务 ID 获取 Apple App Store 应用评论的采集结果。返回：评论评分、评论正文、评论资料、评论发布时间，以及应用整体评分信息等。

结果与创建任务时传的 app_id、location_code、language_code 等参数对应。本平台会尽可能高精度模拟任务参数，以便返回结果与任务创建时目标地区、语言下的页面表现保持一致。

你也可以使用响应中的 check_url 自行校验结果性。建议在无痕模式下访问该链接，以减少个性化因素干扰。需要注意的是，用户偏好、搜索历史等个性化因素不会纳采集逻辑。

接口说明

• 请求方式：GET
• 接口地址：https://api.seermartech.cn/v3/app_data/apple/app_reviews/task_get/advanced/$id

计费说明

本接口本身不会因重复取结果而重复计费；费用通常在创建任务时扣除。任务结果可在 30 天重复获取。

扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

路径参数

字段	类型	说明
id	string	任务唯一标识，UUID 格式。可在任务创建后的 30 天随时用来获取结果。

返回结构

接口返回 JSON 数据，顶层 tasks 数组，每个对应一个任务的执行结果。

顶层字段

字段	类型	说明
version	string	当前 API 版本
status_code	integer	通用状态码，完整列表见参考文档 /v3/appendix/errors
status_message	string	通用状态信息，完整列表见参考文档 /v3/appendix/errors
time	string	执行耗时，单位秒
cost	float	本次请求总成本，单位 USD
tasks_count	integer	tasks 数组中的任务数量
tasks_error	integer	返回错误的任务数量
tasks	array	任务结果数组

tasks[] 字段

字段	类型	说明
id	string	任务 ID，UUID 格式
status_code	integer	任务状态码，范围通常为 10000-60000
status_message	string	任务状态信息
time	string	任务执行耗时，单位秒
cost	float	该任务成本，单位 USD
result_count	integer	result 数组中的结果数量
path	array	请求路径
data	object	任务创建时提交的原始参数
result	array	结果数组

result[] 字段

字段	类型	说明
app_id	string	POST 提交时传的应用 ID
type	string	POST 提交时的搜索引擎类型
se_domain	string	POST 提交时的搜索引擎域名
location_code	integer	POST 提交时的位置编码
language_code	string	POST 提交时的语言编码
check_url	string	结果检查链接，可用于人工核对返回结果
datetime	string	结果获取时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00
title	string	应用标题，即当前评论所属应用名称
rating	object	应用整体评分信息
reviews_count	integer	评论总数；该值通常为 null，因为 App Store 通常不展示总评论数
items_count	integer	本次结果中返回的评论数量
items	array	评论明细列表

rating 字段

字段	类型	说明
rating_type	string	评分类型，可为 Max5、Percents、CustomMax
value	float	基于评论计算出的平均评分
votes_count	integer	评分票数
rating_max	integer	当前 rating_type 的满分值

items[] 字段

字段	类型	说明
type	string	评论类型，可能值：app_store_reviews_search
rank_group	integer	在相同 type 分组中的位置
rank_absolute	integer	评论在结果中的绝对位置
position	string	评论展示位置，当前可为 left
version	string	评论对应的应用版本
rating	object	该条评论的评分信息
timestamp	string	评论发布时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00
id	string	评论 ID
title	string	评论标题
review_text	string	评论正文
user_profile	object	评论资料

items[].rating 字段

字段	类型	说明
rating_type	string	评分类型，当前可为 Max5
value	float	评分值
votes_count	integer	反馈数量；此场景下通常为 null
rating_max	integer	满分值，Max5 对应 5

user_profile 字段

字段	类型	说明
profile_name	string	评论昵称
profile_image_url	string	评论头像图片地址

Sandbox

你可以通过以下 Sandbox 地址查看本接口的完整返回结构。Sandbox 不扣费，返回的是结构完整的模拟数据。

https://api.seermartech.cn/v3/app_data/apple/app_reviews/task_get/advanced/00000000-0000-0000-0000-000000000000

调用示例

curl

id="04011058-0696-0199-0000-2196151a15cb"

curl --location --request GET "https://api.seermartech.cn/v3/app_data/apple/app_reviews/task_get/advanced/${id}" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json"

Python

import requests

task_id = "06141103-2692-0309-1000-980b778b6d25"
url = f"https://api.seermartech.cn/v3/app_data/apple/app_reviews/task_get/advanced/{task_id}"

headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)
data = response.json

if data.get("tasks"):
 task = data["tasks"][0]
 if task.get("status_code", 0) >= 40000 or not task.get("result"):
 print(f'error. Code: {task.get("status_code")} Message: {task.get("status_message")}')
 else:
 # 在这里处理结果
 print(data)
else:
 print(f'error. Code: {data.get("status_code")} Message: {data.get("status_message")}')

TypeScript

import axios from "axios";

const taskId = "02231934-2604-0066-2000-570459f04879";

axios({
 method: "get",
 url: `https://api.seermartech.cn/v3/app_data/apple/app_reviews/task_get/advanced/${taskId}`,
 headers: {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 }
})
 .then((response) => {
 // 在这里处理返回结果
 console.log(response.data);
 })
 .catch((error) => {
 console.log(error);
 });

获取结果的常见方式

通常有两种方式获取已完成任务结果：

1. 调用 /v3/app_data/apple/app_reviews/tasks_ready 获取已完成任务列表；
2. 再根据返回的任务 ID 调用 /v3/app_data/apple/app_reviews/task_get/advanced/$id 获取结果。

如果你已经保存了任务创建时返回的 id，也可以直接按 ID 请求结果，无需查 ready 列表。

响应示例

{
 "version": "0.1.20230705",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.1315 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "se_type": "reviews",
 "se": "apple",
 "api": "app_data",
 "function": "app_reviews",
 "app_id": "835599320",
 "location_code": 2840,
 "language_code": "en",
 "depth": 200,
 "device": "desktop",
 "os": "windows"
 },
 "result": [
 {
 }
 ]
 }
 ]
}

状态码与异常处理

建议在接时同时处理两层状态：

1. 顶层状态：status_code、status_message
2. 任务层状态：tasks[].status_code、tasks[].status_message

当任务状态码大于等于 40000，或 result 为空时，应按失败或未就绪处理。完整错误码与状态信息请参考 /v3/appendix/errors。

注意事项

• 结果与创建任务时的 app_id、地区、语言参数严格对应。
• reviews_count 在该数据源下通常为 null，这是因为源站不一定展示总评论数。
• 如果需要更多评论结果，应在创建任务时增加 depth 参数。
• check_url 可用于人工抽样校验结果准确性，建议使用无痕模式打开。

实用场景

• 监控差评波动：持续拉取指定应用的最新评论，及时发现评分下滑、功能障或版本回退问题。
• 分析版本反馈：按评论中的 version 字段拆分用户反馈，定位某个版本引发的崩溃、卡顿或功能争议。
• 提取用户痛点：基于 review_text 汇总高频负面，为产品优化、FAQ 和客服话术提供依据。
• 对比区域口碑：结合 location_code 与 language_code 获取不同市场评论，识别本地化问题与区域需求差异。
• 识别高价值评价样本：结合评分、发布时间和用户资料，筛选适合用于舆预警、竞品对比或训练评论分类模型的数据。