获取 Apple App 搜索结果（高级版）

通过本接口，你可以根据任务 ID 获取 Apple App Store 搜索结果。返回指定 keyword 下的应用排名列表，以及每个应用的扩展信息，例如应用 ID、图标、评论数、评分、价格等。

结果与创建任务时提交的、地区、语言等参数强。你可以在任务创建后的 30 天反复获取结果，且不会重复计费。

接口说明

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

计费说明

该类接口在创建任务时计费，获取已完成任务结果通常不重复收费。任务结果支持在 30 天读取。

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

路径参数

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

沙盒测试

你可以使用沙盒地址查看该接口支持返回的字段结构。沙盒返回的是模拟数据，不会产生费用。

https://sandbox.seermartech.cn/v3/app_data/apple/app_searches/task_get/advanced/00000000-0000-0000-0000-000000000000

返回结构

API 返回 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	创建任务时提交的。
`se_domain`	string	创建任务时使用的搜索引擎域名。
`location_code`	integer	创建任务时指定的地区代码。
`language_code`	string	创建任务时指定的语言代码。
`check_url`	string	结果检查链接；当前场景下该值为 `null`。
`datetime`	string	结果获取时间，UTC 格式，例如 `2019-11-15 12:57:46 +00:00`。
`se_results_count`	integer	结果总数。
`items_count`	integer	`items` 数组中的数量。
`items`	array	应用列表。

`items` 数组字段

字段	类型	说明
`type`	string	结果类型。当前可能值：`app_store_search_organic`
`rank_group`	integer	在同类 `type`素中的排名。不同 `type` 的不会计该排名。
`rank_absolute`	integer	所有应用中的绝对排名。
`position`	string	素在结果页中的位置。当前可能值：`left`
`app_id`	string	返回应用的 ID。
`title`	string	应用标题。
`url`	string	App Store 应用页链接。
`icon`	string	应用图标链接。
`reviews_count`	integer	应用累计评论数。
`rating`	object	应用平均评分信息。
`rating_type`	string	评分类型。当前可能值：`Max5`
`value`	float	评分值。
`votes_count`	integer	反馈数量；当前场景下该值为 `null`。
`rating_max`	integer	对应 `rating_type` 的最大值；例如 `Max5` 的最大值为 `5`。
`is_free`	boolean	是否为应用。
`price`	object	应用价格信息。
`current`	float	当前价格。
`regular`	float	常规价格。
`max_value`	float	最高价格。
`currency`	string	价格币种，ISO 货币代码。
`is_price_range`	boolean	是否为价格区间。
`displayed_price`	string	结果中展示的原始价格字符串。

获取结果的推荐流程

通常建议按以下流程使用：

通过任务创建接口提交查询任务；
使用 GET /v3/app_data/apple/app_searches/tasks_ready 获取已完成任务列表；
再通过本接口 GET /v3/app_data/apple/app_searches/task_get/advanced/$id 按任务 ID 拉取详细结果。

请求示例

cURL

bash

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

curl --location --request GET "https://api.seermartech.cn/v3/app_data/apple/app_searches/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_searches/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_searches/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.response?.data || error.message);
 });

响应示例

json

{
 "version": "0.1.20220422",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.1347 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "se_type": "organic",
 "se": "apple",
 "api": "app_data",
 "function": "app_searches",
 "keyword": "vpn",
 "location_code": 2840,
 "language_code": "en",
 "depth": 200,
 "device": "desktop",
 "os": "windows"
 },
 "result": [
 {}
 ]
 }
 ]
}

状态码说明

状态码	说明
`20000`	请求成功。
`10000-60000`	任务级状态码范围，含义请结合 `status_message` 处理。

建议同时处理顶层 status_code 与任务级 tasks[].status_code，因单任务异常导致结果误判。

使用建议

本接口适合拉取已完成的 Apple App 搜索结果；
若需批量处理，请通过 tasks_ready 获取可读取任务，再逐个按 ID 请求；
建议保存 keyword、location_code、language_code 与返回结果，便于后续做应用排名对比；
如需完整字段结构验证，可优使用沙盒接口联调。

实用场景

监控品牌词排名：跟踪自家 App 在品牌词或核心功能词下的自然排名变化，及时评估商店投放和 ASO 优化效果。
分析竞品搜索表现：抓取竞品在目标下的排序、评分、评论量和价格信息，制定应用商店竞争策略。
筛选高价值：对比不同下的结果数量、头部应用特征和价格分布，识别更值得重点优化的搜索词。
评估多地区本地化效果：按不同 location_code 与 language_code 获取结果，判断本地化标题、描述和视觉素材是否提升搜索。
构建 App 榜单数据库：持续沉淀搜索结果、应用评分和价格数据，用于 ASO 报表、趋势分析和 BI 看板。

获取 Apple App 搜索结果（高级版） ​

接口说明 ​

计费说明 ​

路径参数 ​

沙盒测试 ​

返回结构 ​

顶层字段 ​

tasks 数组字段 ​

result 数组字段 ​

items 数组字段 ​

获取结果的推荐流程 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应示例 ​

状态码说明 ​

使用建议 ​

实用场景 ​