设置 Apple App 评论任务

POST /v3/app_data/apple/app_reviews/task_post

本接口使用 POST 方法，路径为：

/v3/app_data/apple/app_reviews/task_post

用于创建 Apple App Store 应用评论采集任务。接口将根据 app_id、语言和地区参数，返回指定应用在 App Store 发布的评论数据。任务创建成功后，可通过任务 ID 查询结果，也可以 postback_url 或 pingback_url 接收任务完成通知。

接口信息

请求方法：POST
请求地址：https://api.seermartech.cn/v3/app_data/apple/app_reviews/task_post
请求格式：JSON
请求体格式：JSON 数组，每个代表一个任务
单次请求任务数：最多 100 个平台限流以认证说明中的 30/60/120 次/分钟规则为准

如果单次请求 100 个任务，出部分将返回错误码 40006。

App ID 获取方式

app_id 是 App Store 应用 URL 中 id 后面的数字。

例如，TikTok 应用地址为：

text

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

对应的 app_id 为：

text

835599320

计费说明

创建任务会产生任务费用。
评论结果按每 25 条为一个计费单位。即使设置 "depth": 26，也会按 50 条评论计费。
建议将 depth 设置为 25 的倍数。
高优级任务（priority: 2）会产生额外费用。
参考价约 ¥0.0432 / 次（按示例响应中的 0.006 计费单位换算供参考）。
实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数

参数	类型	填	说明
`app_id`	string	是	App Store 应用 ID，即应用 URL 中 `id` 后面的数字。例如：`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	否	任务优级：<br>`1`：普通优级，默认值；<br>`2`：高优级，额外收费。
`depth`	integer	否	返回的评论数量。默认值为 `25`，最大值为 `500`。建议设置为 25 的倍数。
`sort_by`	string	否	评论排序方式：<br>`most_recent`：按最新评论排序；<br>`most_helpful`：按最有帮助的评论排序。默认值为 `most_helpful`。
`tag`	string	否	自定义任务标识，最长 255 个字符。该值会原样返回在响应任务的 `data` 对象中。
`postback_url`	string	否	任务完成后，本平台向该地址发送结果的 POST 请求，数据以 gzip 格式压缩。支持使用 `$id` 和 `$tag` 占位符。
`postback_data`	string	条件填	使用 `postback_url` 时填。当前支持值：`advanced`。
`pingback_url`	string	否	任务完成后，本平台向该地址发送 GET 请求通知。支持使用 `$id` 和 `$tag` 占位符。

`postback_url` 和 `pingback_url` 占位符

$id：任务 ID
$tag：经过 URL 编码的任务标签

示例：

text

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

注意：

postback_url 和 pingback_url 中的特殊字符会进行 URL 编码。
例如，# 会被编码为 %23。
如果回调服务器在 10 秒未响应，连接将因时中止，任务会转移到任务就绪列表。

请求示例

curl

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/app_data/apple/app_reviews/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",
      "depth": 200
    }
  ]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/app_data/apple/app_reviews/task_post"

headers = {
    "Authorization": "Bearer smt_live_YOUR_KEY",
    "Content-Type": "application/json"
}

payload = [
    {
        "app_id": "835599320",
        "location_code": 2840,
        "language_code": "en",
        "depth": 200
    },
    {
        "app_id": "835599320",
        "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_id": "835599320",
        "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 = [
  {
    app_id: "835599320",
    location_code: 2840,
    language_code: "en",
    depth: 200,
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/app_data/apple/app_reviews/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 数组。每个任务对象任务创建状态和任务参数。任务创建接口不会直接返回评论，result 的值为 null。任务完成后，需要使用返回的任务 ID 获取结果，或通过回调地址接收结果。

顶层响应字段

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	整体响应状态码。完整错误码请参考 `/v3/appendix/errors`。
`status_message`	string	整体响应说明。
`time`	string	请求执行耗时，例如 `0.0683 sec.`。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`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 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`result_count`	integer	`result` 数组中的数量。创建任务时通常为 `0`。
`path`	array	请求路径信息。
`data`	object	创建任务时提交的参数。
`result`	array \| null	任务结果。创建任务接口返回 `null`。

响应示例

json

{
  "version": "0.1.20220422",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.0683 sec.",
  "cost": 0.006,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20100,
      "status_message": "Task Created.",
      "time": "0.0100 sec.",
      "cost": 0.006,
      "result_count": 0,
      "path": [
        "v3",
        "app_data",
        "apple",
        "app_reviews",
        "task_post"
      ],
      "data": {
        "api": "app_data",
        "function": "app_reviews",
        "se": "apple",
        "app_id": "835599320",
        "location_code": 2840,
        "language_code": "en",
        "depth": 200,
        "se_type": "reviews",
        "device": "desktop",
        "os": "windows"
      },
      "result": null
    }
  ]
}

任务结果获取

任务创建成功后，请保存响应中的 tasks[].id，并使用该 ID 调用对应的任务结果接口获取评论数据。

如果提交任务时了：

postback_url：任务完成后接收 POST 结果通知；
pingback_url：任务完成后接收 GET 完成通知。

当回调服务器 10 秒未响应时，任务会转移到任务就绪列表。回调错误码和错误信息取决于服务器。

实用场景

采集竞品应用的最新评论，监控用户反馈变化并识别产品功能、稳定性或服务质量问题。
按国家和语言抓取应用评论，比较不同市场的用户满意度，为本地化运营和 ASO 优化提供依据。
按“最有帮助”排序分析评论，优提取高互动价值的用户意见，产品需求评估。
批量提交多个应用评论任务，建立竞品评论数据库，支持周期性舆监测和趋势分析。
回调地址自动接收任务结果，减少轮询开销，加快评论数据 SEO、ASO 和客户分析系统的速度。

设置 Apple App 评论任务 ​

接口信息 ​

App ID 获取方式 ​

计费说明 ​

请求参数 ​

postback_url 和 pingback_url 占位符 ​

请求示例 ​

curl ​

Python ​

TypeScript ​

响应说明 ​

顶层响应字段 ​

tasks 中的任务字段 ​

响应示例 ​

任务结果获取 ​

实用场景 ​

设置 Apple App 评论任务

接口信息

App ID 获取方式

计费说明

请求参数

`postback_url` 和 `pingback_url` 占位符

请求示例

curl

Python

TypeScript

响应说明

顶层响应字段

`tasks` 中的任务字段

响应示例

任务结果获取

实用场景