SeerMarTech API 文档

主题

Apple App 搜索任务提交 ​

接口说明 ​

该接口用于提交 Apple App Store 搜索任务。任务完成后，可返回指定 keyword 在 App Store 搜索结果中的应用排名列表，结果会受到地区与语言参数影响。

你可以通过任务 id 轮询获取结果；也可以在创建任务时 postback_url 或 pingback_url，由本平台在任务完成后主动通知或推送结果。

  • 请求方法：POST
  • 接口路径：/v3/app_data/apple/app_searches/task_post
  • 完整地址：https://api.seermartech.cn/v3/app_data/apple/app_searches/task_post

计费说明 ​

该接口的费用由两部分组成：

  1. 创建任务本身的费用
  2. 返回结果数量对应的费用

按每 100 条结果 为一个计费单位计费。例如：

  • 设置 "depth": 100，按 100 条结果计费
  • 设置 "depth": 101，按 200 条结果计费

建议将 depth 设置为 100 的整数倍，以便更符合平台处理方式。

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

请求规则 ​

  • 请求体为 UTF-8 编码的 JSON
  • POST 请求体格式为 JSON 数组：[{ ... }]
  • 单次 POST 最多可提交 100 个任务
  • 接口速率上限：每分钟最多 2000 次 API 调用
  • 如果单次 POST 中任务数 100，出的任务会返回错误 40006

结果获取方式 ​

任务提交成功后，可通过以下方式获取结果：

  1. 使用返回的任务 id 调用对应结果接口查询
  2. 创建任务时传 pingback_url，任务完成后本平台会向该地址发送 GET 通知
  3. 创建任务时传 postback_url，任务完成后本平台会向该地址发送结果数据的 POST 请求，数据采用 gzip 压缩格式

如果你的服务器在 10 秒未响应回调请求，连接会因时中断，该任务会被转 /v3/app_data/apple/app_searches/tasks_ready 列表，后续可从就绪任务列表中获取结果。

请求参数 ​

任务对象字段说明 ​

字段名类型说明
keywordstring。填。最长 700 个字符。所有 %## 会被解码，字符 + 会被解码为空格。如果中需要保留 %，请写为 %25；如需保留 +，请写为 %2B。
location_namestring搜索地区完整名称。未提供 location_code 时填。使用该字段时无需再传 location_code。可通过 /v3/app_data/apple/locations 获取支持的地区列表。示例：West Los Angeles,California,United States
location_codeinteger搜索地区编码。未提供 location_name 时填。使用该字段时无需再传 location_name。可通过 /v3/app_data/apple/locations 获取支持的地区列表。示例：9061121
language_namestring搜索语言完整名称。未提供 language_code 时填。使用该字段时无需再传 language_code。可通过 /v3/app_data/apple/languages 获取支持语言。示例：English
language_codestring搜索语言编码。未提供 language_name 时填。使用该字段时无需再传 language_name。可通过 /v3/app_data/apple/languages 获取支持语言。示例：en
priorityinteger任务优级，可选。1 = 普通优级（默认），2 = 高优级。高优级任务会额外收费。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。
depthinteger抓取深度，可选。表示返回的 App Store 搜索结果数量。默认值：100；最大值：700。建议使用 100 的整数倍。 100 时，若搜索结果足够多，可能产生额外费用。
tagstring自定义任务标识，可选。最长 255 个字符。可用于业务侧任务追踪与结果匹。返回时会出现在响应的 data 对象中。
postback_urlstring结果推送地址，可选。任务完成后，本平台会向该地址发送 POST 请求，并附带 gzip 压缩后的结果。支持在 URL 中使用 $id 和 $tag 变量，发送时会替换为真实值。示例：http://your-server.com/postbackscript?id=$id&tag=$tag。注意：URL 中特殊字符会被编码，例如 # 会编码为 %23。
postback_datastringpostback_url 的数据类型。设置 postback_url 时填。当前可用值：advanced
pingback_urlstring完成通知地址，可选。任务完成后，本平台会向该地址发送 GET 请求。支持在 URL 中使用 $id 和 $tag 变量，发送时会替换为真实值。示例：http://your-server.com/pingscript?id=$id&tag=$tag。注意：URL 中特殊字符会被编码，例如 # 会编码为 %23。

响应结构 ​

接口返回 JSON 数据，顶层 tasks 数组，用于描述本次提交的任务状态。

顶层字段 ​

字段名类型说明
versionstring当前 API 版本
status_codeinteger接口通用状态码。完整错误码可参考 /v3/appendix/errors
status_messagestring接口通用状态信息
timestring执行耗时，单位秒
costfloat本次请求总费用，单位 USD
tasks_countintegertasks 数组中的任务数量
tasks_errorintegertasks 数组中返回错误的任务数量
tasksarray任务数组

tasks[] 字段 ​

字段名类型说明
idstring平台唯一任务 ID，UUID 格式
status_codeinteger任务状态码，范围通常为 10000–60000
status_messagestring任务状态信息
timestring任务执行耗时，单位秒
costfloat单个任务费用，单位 USD
result_countintegerresult 数组中的数量
patharray请求路径
dataobject回显的任务参数，通常与提交一致
resultarray|null任务提交接口中该值通常为 null，结果需通过结果接口或回调获取

请求示例 ​

cURL ​

bash
curl --location --request POST "https://api.seermartech.cn/v3/app_data/apple/app_searches/task_post" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "keyword": "vpn",
 "location_code": 2840,
 "language_code": "en",
 "depth": 200
 }
]'

Python ​

python
import requests

url = "https://api.seermartech.cn/v3/app_data/apple/app_searches/task_post"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

data = [
 {
 "keyword": "vpn",
 "location_code": 2840,
 "language_code": "en",
 "depth": 200
 },
 {
 "keyword": "vpn",
 "location_code": 2840,
 "language_code": "en",
 "depth": 200,
 "priority": 2,
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 },
 {
 "keyword": "vpn",
 "location_code": 2840,
 "language_code": "en",
 "postback_data": "advanced",
 "postback_url": "https://your-server.com/postbackscript"
 }
]

response = requests.post(url, headers=headers, json=data)
print(response.json)

TypeScript ​

typescript
import axios from "axios";

const postArray = [
 {
 keyword: "vpn",
 location_code: 2840,
 language_code: "en",
 depth: 200,
 },
 {
 keyword: "vpn",
 location_code: 2840,
 language_code: "en",
 depth: 200,
 priority: 2,
 tag: "some_string_123",
 pingback_url: "https://your-server.com/pingscript?id=$id&tag=$tag",
 },
 {
 keyword: "vpn",
 location_code: 2840,
 language_code: "en",
 postback_data: "advanced",
 postback_url: "https://your-server.com/postbackscript",
 },
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/app_data/apple/app_searches/task_post",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json",
 },
 data: postArray,
})
 .then((response) => {
 // 输出任务提交结果
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error);
 });

响应示例 ​

json
{
 "version": "0.1.20220422",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0628 sec.",
 "cost": 0.0024,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0031 sec.",
 "cost": 0.0024,
 "result_count": 0,
 "path": [
 "v3",
 "app_data",
 "apple",
 "app_searches",
 "task_post"
 ],
 "data": {
 "api": "app_data",
 "function": "app_searches",
 "se": "apple",
 "keyword": "vpn",
 "location_code": 2840,
 "language_code": "en",
 "depth": 200,
 "se_type": "organic",
 "device": "desktop",
 "os": "windows"
 },
 "result": null
 }
 ]
}

状态码与错误处理 ​

建议在接时同时处理接口级和任务级两层状态：

  • 顶层 status_code：表示整个请求是否成功
  • tasks[].status_code：表示单个任务是否创建成功

常见处理建议：

  • 20000：请求成功
  • 20100：任务创建成功
  • 40006：单次 POST 提交的任务数 100
  • 错误码：参考 /v3/appendix/errors

此外，如果了 postback_url 或 pingback_url，请确保回调服务在 10 秒响应，否则任务可能不会立即完成回传，而会 /v3/app_data/apple/app_searches/tasks_ready 列表后续拉取。

使用建议 ​

  • 优使用 location_code 与 language_code，便于程序稳定传参
  • depth 建议按 100、200、300 这样的步长设置
  • 若需要实时处理结果，优使用 postback_url
  • 若只需要任务完成通知，可使用 pingback_url
  • 使用 tag 项目、分组或批次编号，便于后续追踪

实用场景 ​

  • 监控品牌词搜索表现：查询品牌词在 App Store 下的应用排名，及时发现自家应用是否被竞品挤压。
  • 对比竞品覆盖：围绕核心功能词提交搜索任务，分析同类应用在不同下的强弱。
  • 评估本地化投放效果：按不同 location_code 和 language_code 获取排名结果，验证多地区、多语言 ASO 策略效果。
  • 批量跟踪榜单：为一组高价值批量创建任务，建立 App Store 排名监控看板。
  • 触发自动化数据回流：结合 postback_url 在任务完成后自动接收结果，写数据仓库或监控系统。

统一入口：官网 · LLM API · 控制台

© 2026 SeerMarTech · GEO · SEO 营销数据 API