SeerMarTech API 文档

主题

设置 Apple App Store 搜索任务 ​

POST /v3/app_data/apple/app_searches/task_post

本接口使用 POST 方法，通过 /v3/app_data/apple/app_searches/task_post 创建 Apple App Store 搜索任务。接口将返回指定、地区和语言下的 App Store 排名应用列表任务信息。

任务创建后，可通过返回的任务 id 获取结果；也可以在请求中设置 postback_url 或 pingback_url，由本平台在任务完成后主动通知。

> 请求地址：POST https://api.seermartech.cn/v3/app_data/apple/app_searches/task_post

计费说明 ​

  • 任务费用根据任务创建及最终返回的结果数量计算。
  • 每 100 条结果作为一个计费单位。例如，设置 "depth": 101 时，可能按 200 条结果计费。
  • 建议将 depth 设置为 100 的整数倍，因为系统按每 100 条结果处理。
  • 使用高优级任务（priority: 2）可能产生额外费用。
  • 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求限制 ​

  • 请求体使用 UTF-8 编码的 JSON 格式。
  • 每个 POST 请求最多 100 个任务。 平台限流以认证说明中的 30/60/120 次/分钟规则为准。
  • 单次请求 100 个任务时，出部分将返回错误码 40006。
  • 任务完成后，可通过任务 id 调用对应的任务结果接口获取数据。
  • 如果了 postback_url 或 pingback_url，本平台将在任务完成后发送通知。
  • 如果接收通知的服务器在 10 秒未返回响应，请求将因时中止，任务会转任务就绪列表。

请求参数 ​

请求体为 JSON 数组，每个数组代表一个任务。

参数类型说明
keywordstring填。 要查询的，最多 700 个字符。中的编码会被解码：% 字符需要写成 %25，+ 字符需要写成 %2B。
location_namestring搜索地区的完整名称。未指定 location_code 时填。使用此参数后无需再传 location_code。
location_codeinteger搜索地区代码。未指定 location_name 时填。使用此参数后无需再传 location_name。
language_namestring搜索语言的完整名称。未指定 language_code 时填。
language_codestring搜索语言代码。未指定 language_name 时填，例如 en。
priorityinteger任务优级。1：普通优级，默认值；2：高优级，可能产生额外费用。
depthinteger需要解析的 App Store 搜索结果数量。默认值为 100，最大值为 700。建议设置为 100 的整数倍。
tagstring用户自定义任务标识，最长 255 个字符。该值会原样返回在响应的 data 对象中。
postback_urlstring任务完成后接收结果的 URL。平台将以 POST 方式发送 gzip 压缩后的结果。支持使用 $id 和 $tag 占位符。
postback_datastring使用 postback_url 时填。目前支持 advanced。
pingback_urlstring任务完成后的通知 URL。平台将向该地址发送 GET 请求。支持使用 $id 和 $tag 占位符。

地区与语言参数 ​

location_name 与 location_code 二选一；language_name 与 language_code 二选一。

可通过以下接口获取可用地区：

text
GET https://api.seermartech.cn/v3/app_data/apple/locations

地区示例：

text
location_name: West Los Angeles,California,United States
location_code: 9061121

可通过以下接口获取可用语言：

text
GET https://api.seermartech.cn/v3/app_data/apple/languages

语言示例：

text
language_name: English
language_code: en

postback_url 占位符 ​

示例：

text
https://your-server.com/postbackscript?id=$id&tag=$tag

任务完成后，平台会将 $id 替换为任务 ID，并将 $tag 替换为经过 URL 编码的任务标签。

postback_url 和 pingback_url 中的特殊字符会进行 URL 编码，例如 # 会编码为 %23。

请求示例 ​

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
    },
    {
      "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"
    }
  ]'

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",
}

payload = [
    {
        "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=payload)
result = response.json()

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        "请求失败，错误码：%s，错误信息：%s"
        % (result.get("status_code"), result.get("status_message"))
    )

TypeScript ​

typescript
import axios from "axios";

const payload = [
  {
    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
  .post(
    "https://api.seermartech.cn/v3/app_data/apple/app_searches/task_post",
    payload,
    {
      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 对象 tasks 数组每个已创建任务的信息。

参数类型说明
versionstring当前 API 版本。
status_codeinteger请求级状态码。成功时通常为 20000。
status_messagestring请求级状态信息。
timestring请求执行耗时，单位为秒。
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
tasks_countintegertasks 数组中的任务数量。
tasks_errorintegertasks 数组中创建失败的任务数量。
tasksarray已创建任务列表。

tasks 数组字段 ​

参数类型说明
idstring任务唯一标识，采用 UUID 格式。
status_codeinteger任务级状态码，通常在 10000 至 60000 范围。
status_messagestring任务级状态信息。
timestring任务执行耗时，单位为秒。
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
result_countintegerresult 数组中的数量。创建任务时通常为 0。
patharray请求路径信息。
dataobject创建任务时提交的参数。
resultarray任务结果。任务创建接口返回时为 null。

完整状态码和错误信息请参考错误码文档。

响应示例 ​

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": "00000000-0000-0000-0000-000000000000",
      "status_code": 20100,
      "status_message": "Task Created.",
      "time": "0.0100 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
    }
  ]
}

任务结果获取 ​

创建任务成功后，可使用响应中的 id 调用任务结果接口获取已完成的 App Store 搜索结果。也可以使用任务就绪列表接口批量查询已完成任务。

任务结果接口：

text
GET /v3/app_data/apple/app_searches/task_get/{id}

任务就绪列表接口：

text
GET /v3/app_data/apple/app_searches/tasks_ready

实用场景 ​

  • 监控排名：批量提交目标，获取 App Store 中的应用排名，评估应用在不同市场的自然表现。
  • 对比竞品可见性：针对同一、地区和语言创建任务，比较自有应用与竞品的排名差异。
  • 分析多地区市场机会：切换不同 location_code 和 language_code，识别应用在海外市场的覆盖机会。
  • 评估 ASO 优化效果：在标题、描述或调整前后定期提交相同任务，量化优化带来的排名变化。
  • 构建排名监控系统：结合 postback_url 或 pingback_url 接收任务完成通知，自动更新 ASO 报表和告警数据。

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

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