获取 Apple App 榜单任务结果（高级）

本接口用于根据任务 id 获取 Apple App Store 榜单抓取结果。返回榜单中的应用列表，以及应用的 app_id、标题、评分、价格、评论数、图标地址等信息。

结果与创建任务时指定的 app_collection、地区、语言等参数一致。

接口说明

请求方式： GET请求地址：

https://api.seermartech.cn/v3/app_data/apple/app_list/task_get/advanced/{id}

计费说明

该接口本身不重复计费，只有在创建任务时扣费。任务创建后，可在 30 天多次获取结果。

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

路径参数

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

返回结果说明

接口返回 JSON 数据，顶层 tasks 数组，每个任务对象中对应结果。

顶层字段

字段	类型	说明
`version`	string	当前 API 版本
`status_code`	integer	局状态码
`status_message`	string	局状态信息
`time`	string	执行耗时，单位秒
`cost`	float	本次请求总成本，单位 USD
`tasks_count`	integer	`tasks` 数组中的任务数量
`tasks_error`	integer	`tasks` 数组中返回错误的任务数量
`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[] 字段

字段	类型	说明
`keyword`	string	创建任务时传的应用榜单集合（即 `app_collection`）
`se_domain`	string	创建任务时指定的搜索引擎域名
`location_code`	integer	创建任务时指定的地区编码
`language_code`	string	创建任务时指定的语言编码
`check_url`	string	结果直达链接；该接口中通常为 `null`
`datetime`	string	结果抓取时间，UTC 格式：`yyyy-mm-dd hh-mm-ss +00:00`
`se_results_count`	integer	结果总数
`items_count`	integer	当前返回的应用数量
`items`	array	应用列表

如需更多结果，可在创建任务时通过 depth 参数提高返回深度。

items[] 字段

字段	类型	说明
`type`	string	结果类型，可能值：`app_store_search_organic`
`rank_group`	integer	相同 `type` 分组的排名
`rank_absolute`	integer	榜单中的绝对排名
`position`	string	应用在结果中的位置，当前可能值：`left`
`app_id`	string	应用 ID
`title`	string	应用标题
`url`	string	App Store 应用页地址
`icon`	string	应用图标地址
`reviews_count`	integer	应用评论总数
`rating`	object	平均评分信息
`is_free`	boolean	是否
`price`	object	价格信息

rating 对象字段

字段	类型	说明
`rating_type`	string	评分类型，当前可能值：`Max5`
`value`	float	平均评分值
`votes_count`	integer	评分反馈数量；该接口中通常为 `null`
`rating_max`	integer	评分上限；`Max5` 对应上限为 `5`

price 对象字段

字段	类型	说明
`current`	float	当前价格
`regular`	float	常规价格
`max_value`	float	最高价格
`currency`	string	价格对应币种，ISO 货币代码
`is_price_range`	boolean	是否为价格区间
`displayed_price`	string	结果中展示的原始价格字符串

沙箱调试

可通过沙箱接口查看该端点可返回的完整字段结构，字段值为模拟数据，不会产生费用。

沙箱地址：

https://sandbox.本平台.com/v3/app_data/apple/app_list/task_get/advanced/00000000-0000-0000-0000-000000000000

请求示例

cURL

bash

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

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

Python

python

import requests

task_id = "06141103-2692-0309-1000-980b778b6d25"
url = f"https://api.seermartech.cn/v3/app_data/apple/app_list/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

print(data)

TypeScript

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_list/task_get/advanced/${taskId}`,
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json",
 },
}).then((response) => {
 // 输出任务结果
 console.log(response.data);
}).catch((error) => {
 console.error(error);
});

响应示例

json

{
 "version": "0.1.20220422",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0793 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "se_type": "app_list",
 "se": "apple",
 "api": "app_data",
 "function": "app_list",
 "app_collection": "top_free_ios",
 "location_code": 2840,
 "language_code": "en",
 "depth": 200,
 "app_category": "games",
 "device": "desktop",
 "os": "windows"
 },
 "result": [
 {
 }
 ]
 }
 ]
}

状态码与错误处理

status_code = 20000 表示请求成功。
任务级别的 status_code 用于判断该任务是否执行成功。
若 tasks_error 大于 0，说明部分任务返回异常。
建议同时检查：
顶层 status_code
tasks[].status_code
tasks[].result 是否为空

错误码完整定义可参考错误码附录文档。

使用建议

通过创建任务接口创建 Apple App 榜单抓取任务。
再通过本接口按 id 获取指定任务结果。
如果需要批量拉取已完成任务，可调用 /v3/app_data/apple/app_list/tasks_ready 获取可读取的任务列表。
若希望返回更多应用条目，请在创建任务时提高 depth 参数。

实用场景

监控榜单变化：定期拉取 top_free_ios、top_paid_ios 等榜单，追踪应用排名波动，市场竞争分析。
分析竞品表现：提取竞品的评分、评论数、价格和榜单位置，快速评估当前市场热度与用户口碑。
筛选高潜应用：结合分类、地区、语言维度抓取榜单应用，识别增长中的细分赛道和高热度产品。
评估定价策略：对比应用、付费应用及价格区间分布，判断目标市场的主流变现模式。
构建应用报库：将应用 ID、标题、评分、价格、图标等结构化库，为 ASO、投放和行业研究提供基础数据。

获取 Apple App 榜单任务结果（高级） ​

接口说明 ​

计费说明 ​

路径参数 ​

返回结果说明 ​

顶层字段 ​

tasks[] 字段 ​

result[] 字段 ​

items[] 字段 ​

rating 对象字段 ​

price 对象字段 ​

沙箱调试 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应示例 ​

状态码与错误处理 ​

使用建议 ​

实用场景 ​