SeerMarTech API 文档

主题

提交 Google Play 应用评论采集任务 ​

接口说明 ​

该接口用于提交一个评论采集任务，获取指定应用在 Google Play 平台上的用户评论。

返回结果会严格受以下参数影响：

  • app_id：目标应用 ID
  • language_code 或 language_name：评论语言
  • location_code 或 location_name：评论所属地区

，app_id 可从应用页 URL 中提取。例如：

https://play.google.com/store/apps/details?id=org.telegram.messenger

上述应用的 app_id 为：

org.telegram.messenger

请求地址 ​

POST https://api.seermartech.cn/v3/app_data/google/app_reviews/task_post

计费说明 ​

本接口会按以下两部分计费：

  • 创建任务本身
  • 实返回的评论数量

评论按每 150 条 为一个计费单。例如：

  • depth = 150：按 150 条计费
  • depth = 151：按 300 条计费

因此，建议将 depth 设置为 150 的倍数，以便更好控制成本。

参考价以响应中的 cost 字段为准；若参考单价发生变化，请以返回扣费为准。

请求格式 ​

  • 请求方法：POST
  • 请求体格式：JSON
  • 编码：UTF-8
  • 请求体为 JSON 数组，格式如下：
json
[
 {
 "app_id": "org.telegram.messenger",
 "location_code": 2840,
 "language_code": "en",
 "depth": 150
 }
]

并发与限制 ​

  • 每分钟最多可发送 2000 次 API 调用
  • 单次 POST 请求最多 100 个任务
  • 若单次请求中任务数 100，出部分会返回错误 40006

结果获取方式 ​

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

  1. 使用任务唯一 ID 获取结果
  2. 在创建任务时设置 postback_url
  3. 在创建任务时设置 pingback_url

回调说明 ​

  • postback_url：任务完成后，本平台会向该地址发送 POST 请求，并附带 gzip 压缩后的结果数据
  • pingback_url：任务完成后，本平台会向该地址发送 GET 通知请求

支持在回调 URL 中使用变量：

  • $id：任务 ID
  • $tag：任务标签（URL 编码后）

示例：

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

注意事项：

  • 若您的服务端在 10 秒未响应，连接会因时被中断 -时后，任务会被转 /v3/app_data/google/app_reviews/tasks_ready 列表，可后续主动拉取
  • postback_url 和 pingback_url 中的特殊字符会被 URL 编码，例如 # 会被编码为 %23

请求参数 ​

字段名类型说明
app_idstring应用 ID。填。即 Google Play 应用页 URL 中 id= 后的值。示例：org.telegram.messenger
location_namestring地区名称。未提供 location_code 时填。使用该字段时无需再传 location_code。可通过 /v3/app_data/google/locations 获取可用地区列表。示例：West Los Angeles,California,United States
location_codeinteger地区编码。未提供 location_name 时填。使用该字段时无需再传 location_name。可通过 /v3/app_data/google/locations 获取可用地区列表。示例：9061121
language_namestring语言名称。未提供 language_code 时填。使用该字段时无需再传 language_code。可通过 /v3/app_data/google/languages 获取可用语言列表。示例：English
language_codestring语言编码。未提供 language_name 时填。使用该字段时无需再传 language_name。可通过 /v3/app_data/google/languages 获取可用语言列表。示例：en
priorityinteger任务优级，可选。1 表示普通优级（默认），2 表示高优级。高优级任务会产生额外费用，扣费以响应头 X-SeerMarTech-Charge-CNY 为准。
depthinteger采集深度，可选。表示希望返回的评论数量。默认值：150；最大值：100000。系统按每 150 条评论为一个处理/计费单， 150 可能触发额外扣费。建议设置为 150 的倍数。
ratinginteger按评分过滤评论，可选。支持：5、4、3、2、1。默认返回所有评分的评论。
sort_bystring评论排序方式，可选。newest：按最新评论排序；most_relevant：按最排序。默认值：most_relevant
tagstring自定义任务标识，可选。最长 255 个字符。可用于业务侧请求与结果，返回时会出现在响应的 data 对象中。
postback_urlstring结果推送地址，可选。任务完成后，本平台将向该地址发送结果的 POST 请求（gzip 压缩）。支持 $id 和 $tag 变量。
postback_datastringpostback_url 的数据类型。指定 postback_url 时填。可选值：advanced、html
pingback_urlstring完成通知地址，可选。任务完成后，本平台将向该地址发送 GET 请求。支持 $id 和 $tag 变量。

响应结构 ​

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

顶层字段 ​

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

tasks 数组中的字段 ​

字段名类型说明
idstring任务唯一标识，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/google/app_reviews/task_post" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "app_id": "org.telegram.messenger",
 "location_code": 2840,
 "language_code": "en",
 "depth": 150
 }
]'

Python ​

python
import requests

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

payload = [
 {
 "app_id": "org.telegram.messenger",
 "location_code": 2840,
 "language_code": "en",
 "depth": 150
 },
 {
 "app_id": "org.telegram.messenger",
 "location_code": 2840,
 "language_code": "en",
 "depth": 150,
 "priority": 2,
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 },
 {
 "app_id": "org.telegram.messenger",
 "location_code": 2840,
 "language_code": "en",
 "postback_data": "html",
 "postback_url": "https://your-server.com/postbackscript"
 }
]

resp = requests.post(url, headers=headers, json=payload)
print(resp.json)

TypeScript ​

typescript
import axios from "axios";

const payload = [
 {
 app_id: "org.telegram.messenger",
 location_code: 2840,
 language_code: "en",
 depth: 150
 }
];

axios.post(
 "https://api.seermartech.cn/v3/app_data/google/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
{
 "version": "0.1.20220420",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0703 sec.",
 "cost": 0.0015,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "12345678-1234-1234-1234-1234567890ab",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0020 sec.",
 "cost": 0.0015,
 "result_count": 0,
 "path": [
 "v3",
 "app_data",
 "google",
 "app_reviews",
 "task_post"
 ],
 "data": {
 "api": "app_data",
 "function": "app_reviews",
 "se": "google",
 "app_id": "org.telegram.messenger",
 "location_code": 2840,
 "language_code": "en",
 "depth": 150,
 "rating": 5,
 "se_type": "reviews",
 "device": "desktop",
 "os": "windows"
 },
 "result": null
 }
 ]
}

状态码与异常处理 ​

  • 20000：请求成功
  • 40006：单次 POST 中任务数量限（ 100 个）
  • 状态码请参考 /v3/appendix/errors

建议在接时实现以下异常处理机制：

  • 顶层 status_code 非成功时，记录整次请求失败原因
  • 遍历 tasks 数组，逐个检查任务级别的 status_code
  • 对回调时、网络波动、服务端异常建立重试或补偿机制
  • 对 tasks_ready 列表建立底拉取流程，漏数

使用建议 ​

  • 优使用 location_code 与 language_code，可减少名称匹歧义
  • depth 建议按 150、300、450 这类倍数设置
  • 若业务需要实时性，可合 priority=2 与 pingback_url/postback_url
  • 若只某类口碑问题，可使用 rating=1 或 rating=2 聚焦低分评论
  • 若最近版本反馈，可使用 sort_by=newest

实用场景 ​

  • 监控低分评论：按 rating=1 或 rating=2 拉取差评，快速定位应用崩溃、登录失败、支付异常等问题，帮助产品和客服团队及时响应。
  • 分析版本口碑变化：结合 sort_by=newest 定期抓取最新评论，观察版本发布后用户反馈走势，评估更新效果与风险。
  • 对比地区评论差异：按不同 location_code 创建任务，对比各国家或城市的评论倾向，为本地化运营和投放优化提供依据。
  • 筛选指定语言反馈：通过 language_code 获取目标语言评论，支持海外市场精细化分析，多语言评论混杂影响判断。
  • 构建应用口碑数据库：批量提交多个应用评论任务，沉淀竞品与自家产品的评论数据，用于感分析、主题聚类和 ASO 研究。

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

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