创建 Apple App Info 任务

POST /v3/app_data/apple/app_info/task_post

接口说明

该接口用于提交 Apple App Store 应用信息采集任务。提交成功后，本平台会根据请求中的 app_id 获取对应应用的基础信息。

app_id 可从 App Store 应用链接中提取，即 URL 中 id 后面的数字。例如：

https://apps.apple.com/us/app/id835599320

该应用的 app_id 为：

835599320

请求地址

POST https://api.seermartech.cn/v3/app_data/apple/app_info/task_post

计费说明

创建任务时即会产生费用。

由于原文未给出固定单价，因此无法直接换算参考人民币价格。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求格式

所有 POST 数据使用 JSON（UTF-8 编码）提交。

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

任务提交后，可通过返回的唯一任务 ID id 获取结果；也可以在创建任务时设置 postback_url 或 pingback_url，由本平台在任务完成后主动通知你。

如果你的服务端在 10 秒未响应 回调请求，连接会因时被中止，该任务会转 /v3/app_data/apple/app_info/tasks_ready 列表中你主动拉取。

请求参数

字段名	类型	说明
app_id	string	填。App Store 应用 ID。可从应用 URL 中获取，例如 https://apps.apple.com/us/app/id835599320 中的 835599320。
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 为准。
tag	string	自定义任务标识，可选。最长 255 个字符。可用于将任务与业务系统中的记录，返回结果中的 data 对象会带回该值。
postback_url	string	结果回传地址，可选。任务完成后，本平台会将结果以 gzip 压缩的 POST 请求发送到该地址。支持在 URL 中使用 $id 和 $tag 变量，发送前会自动替换为真实值。示例：http://your-server.com/postbackscript?id=$id 或 http://your-server.com/postbackscript?id=$id&tag=$tag。注意：URL 中特殊字符会进行 URL 编码，例如 # 会被编码为 %23。
postback_data	string	postback_url 的返回数据类型。当填写 postback_url 时填。可选值：advanced
pingback_url	string	任务完成通知地址，可选。任务完成后，本平台会向该地址发送 GET 请求通知。支持在 URL 中使用 $id 和 $tag 变量，发送前会自动替换为真实值。示例：http://your-server.com/pingscript?id=$id 或 http://your-server.com/pingscript?id=$id&tag=$tag。注意：URL 中特殊字符会进行 URL 编码，例如 # 会被编码为 %23。

响应说明

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

顶层响应字段

字段名	类型	说明
version	string	当前 API 版本
status_code	integer	接口通用状态码，完整列表见 /v3/appendix/errors
status_message	string	接口通用状态信息，完整列表见 /v3/appendix/errors
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	结果数组。对于本接口的任务提交动作，此处通常为 null

回调说明

postback_url

适合在任务完成后直接接收完整结果数据：

• 请求方式：POST
• 数据格式：gzip 压缩
• 需要同时传 postback_data
• 当前支持值：advanced

pingback_url

适合只接收任务完成通知，再由你的系统根据任务 ID 主动获取结果：

• 请求方式：GET
• 支持 $id、$tag 变量替换

请求示例

cURL

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

Python

import requests

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

# 请求体为 JSON 数组
data = [
 {
 "app_id": "835599320",
 "location_code": 2840,
 "language_code": "en"
 },
 {
 "app_id": "835599320",
 "location_code": 2840,
 "language_code": "en",
 "priority": 2,
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 },
 {
 "app_id": "835599320",
 "location_code": 2840,
 "language_code": "en",
 "postback_data": "advanced",
 "postback_url": "https://your-server.com/postbackscript"
 }
]

resp = requests.post(url, headers=headers, json=data)
print(resp.status_code)
print(resp.text)

TypeScript

import axios from "axios";

const postData = [
 {
 app_id: "835599320",
 location_code: 2840,
 language_code: "en",
 },
 {
 app_id: "835599320",
 location_code: 2840,
 language_code: "en",
 priority: 2,
 tag: "some_string_123",
 pingback_url: "https://your-server.com/pingscript?id=$id&tag=$tag",
 },
 {
 app_id: "835599320",
 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_info/task_post",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json",
 },
 data: postData,
})
 .then((response) => {
 // 输出接口响应
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error.response?.data || error.message);
 });

响应示例

{
 "version": "0.1.20220422",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0713 sec.",
 "cost": 0.0006,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "app_data",
 "function": "app_info",
 "se": "apple",
 "app_id": "835599320",
 "location_code": 2840,
 "language_code": "en",
 "se_type": "app_info",
 "device": "desktop",
 "os": "windows"
 },
 "result": null
 }
 ]
}

状态码与错误处理

• 顶层 status_code = 20000 表示请求成功受理
• 若单次 POST 中任务数 100，出部分返回 40006
• 建议同时处理：
• HTTP 请求错误
• 顶层接口状态码错误
• 单任务状态码错误
• 回调时或回调地址不可达

完整错误码与状态说明请参考 /v3/appendix/errors。

使用建议

1. 优使用 location_code 和 language_code，名称匹歧义。
2. 如果需要批量处理，建议每次提交控制在 100 个任务。
3. 若业务要求结果实时库，建议 postback_url。
4. 若业务需要自主控制结果获取节奏，建议使用 pingback_url + 结果轮询。
5. 使用 tag 将平台任务与工单、项目或应用记录，便于追踪。

实用场景

• 采集应用基础信息：根据 app_id 拉取 App Store 中指定应用的基础数据，用于竞品档案建设和应用库维护。
• 监控重点竞品页面变化：周期性提交竞品应用任务，跟踪商店信息更新，帮助及时发现标题、描述或地区展示策略变化。
• 校验多地区上架信息一致性：按不同 location_code 与 language_code 创建任务，检查同一应用在不同市场的展示是否一致，化运营。
• 建立应用报回流链路：通过 postback_url 将采集结果自动回传到系统，减少人工轮询和数据同步成本。
• 业务任务与采集结果：使用 tag 绑定项目、客户或分析批次，便于后续结果归档、追踪和审计。