创建 Apple App 榜单采集任务

该接口用于创建 Apple App Store 榜单应用采集任务，返回指定榜单集合下的应用列表。结果会受到 app_collection、语言参数和地区参数的影响。

接口路径：

POST /v3/app_data/apple/app_list/task_post

完整请求地址：

https://api.seermartech.cn/v3/app_data/apple/app_list/task_post

接口说明

本接口用于提交异步任务。任务创建成功后，接口会返回唯一任务 ID。你可以通过该 ID 后续获取结果；也可以在创建任务时传 postback_url 或 pingback_url，由本平台在任务完成后主动通知你的系统。

计费说明

任务创建会产生费用；
同时会按返回结果数量计费；
每返回 100 条结果 计为一个计费单位；
例如设置 "depth": 101 时，将按 200 条结果计费。

参考价约 ¥0.0384 / 次。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

提交限制

所有 POST 数据使用 JSON（UTF-8）
请求体格式为 JSON 数组：[{ ... }]
每分钟最多可发送 2000 次 API 调用
单次 POST 最多 100 个任务
如果单次请求 100 个任务，出的任务会返回错误 40006

回调说明

你可以通过以下两种方式接收任务完成通知：

pingback_url：任务完成后，本平台向该地址发送 GET 请求
postback_url：任务完成后，本平台向该地址发送带结果数据的 POST 请求，结果以 gzip 压缩格式发送

支持在回调地址中使用以下变量：

$id：任务 ID
$tag：你提交的 tag 值（URL 编码后）

示例：

http://your-server.com/pingscript?id=$id
http://your-server.com/pingscript?id=$id&tag=$tag

注意事项：

若你的服务器在 10 秒未响应，连接会因时中断；
此时任务会转 /v3/app_data/apple/app_list/tasks_ready 列表，可改为轮询获取结果；
postback_url 和 pingback_url 中的特殊字符会进行 URL 编码，例如 # 会编码为 %23。

请求参数

顶层请求体示例

json

[
 {
 "app_collection": "top_free_ios",
 "location_code": 2840,
 "language_code": "en",
 "depth": 200,
 "app_category": "games"
 }
]

参数说明

字段名	类型	说明
`app_collection`	string	填。要采集的 App Store 榜单集合。可选值：`top_free_ios`、`top_paid_ios`、`top_grossing_ios`、`new_ios`、`new_free_ios`、`new_paid_ios`
`location_name`	string	搜索地区完整名称。未指定 `location_code` 时填。使用该字段时无需再传 `location_code`。可通过 `/v3/app_data/apple/locations` 获取可用地区。例如：`West Los Angeles,California,United States`
`location_code`	integer	搜索地区编码。未指定 `location_name` 时填。使用该字段时无需再传 `location_name`。可通过 `/v3/app_data/apple/locations` 获取可用地区。例如：`9061121`
`language_name`	string	搜索语言完整名称。未指定 `language_code` 时填。使用该字段时无需再传 `language_code`。可通过 `/v3/app_data/apple/languages` 获取可用语言。例如：`English`
`language_code`	string	搜索语言代码。未指定 `language_name` 时填。使用该字段时无需再传 `language_name`。可通过 `/v3/app_data/apple/languages` 获取可用语言。例如：`en`
`priority`	integer	任务优级，可选。`1` 表示普通优级（默认），`2` 表示高优级。高优级任务会额外收费。扣费以响应头 `X-SeerMarTech-Charge-CNY` 为准。
`depth`	integer	采集深度，可选。表示要返回的应用数量。默认值：`100`；最大值：`1000`。建议按 100 的倍数设置，因为系统按每 100 条结果分段处理和计费。
`app_category`	string	App Store 应用分类，可选。用于按分类过滤结果。例如：`lifestyle`。可通过 `/v3/app_data/apple/categories` 获取可用分类。
`tag`	string	自定义任务标识，可选，最长 255 个字符。可用于业务系统中任务与结果。响应中的 `data` 对象会回传该值。
`postback_url`	string	结果推送地址，可选。任务完成后，本平台会将结果以 POST 请求发送到该地址。支持 `$id` 和 `$tag` 变量。
`postback_data`	string	`postback_url` 的数据类型。指定 `postback_url` 时填。当前可用值：`advanced`
`pingback_url`	string	完成通知地址，可选。任务完成后，本平台会向该地址发送 GET 请求。支持 `$id` 和 `$tag` 变量。

响应说明

接口返回 JSON 格式数据，任务提交状态及任务信息。

顶层响应字段

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

`tasks` 数组字段

字段名	类型	说明
`id`	string	任务唯一标识，UUID 格式
`status_code`	integer	任务状态码，范围通常为 `10000-60000`
`status_message`	string	任务状态说明
`time`	string	任务执行时间，单位秒
`cost`	float	单个任务费用，单位 USD
`result_count`	integer	`result` 数组中的数量
`path`	array	请求路径
`data`	object	回显你提交的任务参数
`result`	array \| null	结果数组。对于任务提交接口，该值通常为 `null`

请求示例

cURL

bash

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

Python

python

import requests

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

data = [
 {
 "app_collection": "top_free_ios",
 "location_code": 2840,
 "language_code": "en",
 "depth": 200
 },
 {
 "app_collection": "top_free_ios",
 "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"
 },
 {
 "app_collection": "top_free_ios",
 "location_code": 2840,
 "language_code": "en",
 "postback_data": "advanced",
 "postback_url": "https://your-server.com/postbackscript"
 }
]

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

if result.get("status_code") == 20000:
 print(result)
else:
 print(f'error. Code: {result.get("status_code")} Message: {result.get("status_message")}')

TypeScript

typescript

import axios from "axios";

const postArray = [
 {
 app_collection: "top_free_ios",
 location_code: 2840,
 language_code: "en",
 depth: 200
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/app_data/apple/app_list/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.0768 sec.",
 "cost": 0.0024,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "01894217-1535-0000-0000-8b7f0a4e9abc",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0021 sec.",
 "cost": 0.0024,
 "result_count": 0,
 "path": [
 "v3",
 "app_data",
 "apple",
 "app_list",
 "task_post"
 ],
 "data": {
 "api": "app_data",
 "function": "app_list",
 "se": "apple",
 "app_collection": "top_free_ios",
 "location_code": 2840,
 "language_code": "en",
 "depth": 200,
 "app_category": "games",
 "se_type": "app_list",
 "device": "desktop",
 "os": "windows"
 },
 "result": null
 }
 ]
}

状态与错误处理

建议根据顶层 status_code 以及 tasks[].status_code 同时进行判断。

常见规则：

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

建议在接时处理以下异常：

请求格式不合法 -填参数缺失
location_name / location_code、language_name / language_code 互斥或缺失
回调地址不可达或时 -出频率限制或单次任务数限制

结果获取方式

创建任务后，你可以通过以下方式拿到最终结果：

使用返回的 id 调用对应结果查询接口；
使用 /v3/app_data/apple/app_list/tasks_ready 获取已完成任务列表；
创建任务时 pingback_url 或 postback_url，由本平台主动通知。

实用场景

监控榜单变化：定期抓取 top_free_ios、top_paid_ios 等榜单，追踪竞品排名波动与市场热度变化。
筛选细分类目头部应用：结合 app_category 获取如 games、lifestyle 等分类榜单，快速定位细分赛道头部产品。
比较不同地区榜单差异：按 location_code 拉取多地区榜单，分析同一应用在不同国家或城市市场的表现差异。
分析本地化影响：切换 language_code 观察不同语言环境下的榜单结果，评估本地化投放与策略价值。
搭建异步采集流水线：使用 pingback_url 或 postback_url 自动接收完成通知，降低轮询成本并提升批量采集效率。

创建 Apple App 榜单采集任务 ​

接口说明 ​

计费说明 ​

提交限制 ​

回调说明 ​

请求参数 ​

顶层请求体示例 ​

参数说明 ​

响应说明 ​

顶层响应字段 ​

tasks 数组字段 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应示例 ​

状态与错误处理 ​

结果获取方式 ​

实用场景 ​