SeerMarTech API 文档

主题

设置 Google Play 应用评论任务 ​

POST /v3/app_data/google/app_reviews/task_post

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

/v3/app_data/google/app_reviews/task_post

用于创建 Google Play 应用评论抓取任务。接口将根据 app_id 获取指定应用的评论，并请求中的语言和地区返回对应结果。

例如，Telegram 应用在 Google Play 中的地址为：

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

，应用 ID 为 org.telegram.messenger。

评论数量按每 150 条为一个计费单位。比如将 depth 设置为 151，通常会按 300 条评论计费。

计费说明 ​

创建任务会产生任务费用，同时根据任务返回的评论数量计费。建议将 depth 设置为 150 的倍数。

示例响应中的任务成本 0.0015 美，按参考汇率折算约为 ¥0.0108。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

高优级任务会产生额外费用，扣费同样以响应头 X-SeerMarTech-Charge-CNY 为准。

请求限制 ​

  • 请求体使用 UTF-8 编码的 JSON 格式。
  • 请求体是 JSON 数组，例如 [{ ... }]。 平台限流以认证说明中的 30/60/120 次/分钟规则为准。
  • 每次请求最多 100 个任务。
  • 单次请求 100 个任务时，出部分将返回错误码 40006。
  • 创建任务后，可以通过返回的任务 ID 查询任务结果。
  • 也可以通过 postback_url 或 pingback_url 接收任务完成通知。
  • 如果回调服务器在 10 秒未返回响应，请求将因时中断，任务会转移到“已就绪任务”列表。

请求参数 ​

参数类型说明
app_idstring填。Google Play 应用 ID，可从应用页 URL 中获取。例如：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。示例：en。
priorityinteger任务优级，可选值：1：普通优级，默认值；2：高优级。高优级任务会产生额外费用。
depthinteger抓取深度，即需要返回的评论数量。默认值为 150，最大值为 100000。系统按每 150 条评论处理和计费，建议设置为 150 的倍数。
ratinginteger按星级筛选评论。可选值：5、4、3、2、1，分别表示返回对应星级的评论。未设置时返回所有星级的评论。
sort_bystring评论排序方式。newest：按最新评论排序；most_relevant：按最评论排序。默认值为 most_relevant。
tagstring用户自定义任务标识，最长 255 个字符。该值会原样出现在响应的 data 对象中，可用于匹任务与结果。
postback_urlstring任务完成后的结果回调地址。任务完成后，本平台将以 POST 方式向该地址发送结果，使用 gzip 压缩。URL 中可使用 $id 和 $tag 占位符，平台发送请求前会替换为任务 ID 和 URL 编码后的标签。
postback_datastring当指定 postback_url 时填。回调数据类型，可选值：advanced、html。
pingback_urlstring任务完成通知地址。任务完成后，本平台将向该地址发送 GET 请求。URL 中可使用 $id 和 $tag 占位符，平台发送请求前会替换为值。

回调地址示例 ​

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

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

请求示例 ​

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

response = requests.post(url, headers=headers, json=payload)
print(response.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);
  });

PHP ​

php
<?php

$url = 'https://api.seermartech.cn/v3/app_data/google/app_reviews/task_post';

$payload = [
    [
        'app_id' => 'org.telegram.messenger',
        'location_code' => 2840,
        'language_code' => 'en',
        'depth' => 150,
    ],
    [
        'app_id' => 'org.telegram.messenger',
        'depth' => 150,
        'priority' => 2,
        'location_code' => 2840,
        'language_code' => 'en',
    ],
    [
        'app_id' => 'org.telegram.messenger',
        'location_code' => 2840,
        'language_code' => 'en',
        'postback_data' => 'html',
        'postback_url' => 'https://your-server.com/postbackscript',
    ],
];

$ch = curl_init($url);

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer smt_live_YOUR_KEY',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_SLASHES),
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

C# ​

csharp
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

public static class Demo
{
    public static async Task CreateAppReviewTask()
    {
        using var httpClient = new HttpClient();

        httpClient.DefaultRequestHeaders.Authorization =
            new AuthenticationHeaderValue(
                "Bearer",
                "smt_live_YOUR_KEY"
            );

        var payload = new[]
        {
            new
            {
                app_id = "org.telegram.messenger",
                location_code = 2840,
                language_code = "en",
                depth = 150
            },
            new
            {
                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"
            },
            new
            {
                app_id = "org.telegram.messenger",
                location_code = 2840,
                language_code = "en",
                postback_data = "html",
                postback_url = "https://your-server.com/postbackscript"
            }
        };

        var content = new StringContent(
            JsonConvert.SerializeObject(payload),
            Encoding.UTF8,
            "application/json"
        );

        var response = await httpClient.PostAsync(
            "https://api.seermartech.cn/v3/app_data/google/app_reviews/task_post",
            content
        );

        var result = await response.Content.ReadAsStringAsync();
        Console.WriteLine(result);
    }
}

响应说明 ​

接口返回 JSON 数据用于描述任务创建结果的 tasks 数组。由于该接口负责创建任务，任务对象中的 result 通常为 null。完成后的评论数据需要通过任务结果接口或的回调地址获取。

顶层响应字段 ​

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

tasks 中的任务字段 ​

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

响应示例 ​

json
{
  "version": "0.1.20220420",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.0703 sec.",
  "cost": 0.0108,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "726eboxe-4c8d-4f3f-9e67-123456789abc",
      "status_code": 20100,
      "status_message": "Task Created.",
      "time": "0.0120 sec.",
      "cost": 0.0108,
      "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
    }
  ]
}

错误处理 ​

请在客户端实现状态码和异常处理机制：

  • 检查顶层 status_code 是否为 20000。
  • 检查 tasks_error 是否大于 0。
  • 对每个任务分别检查 tasks[].status_code 和 tasks[].status_message。
  • 当单次提交任务 100 个时，出部分会返回错误码 40006。
  • 任务创建成功不代表评论结果已经生成，应根据任务 ID 查询结果，或回调通知。

实用场景 ​

  • 抓取竞品应用评论，按指定地区、语言和评论深度收集用户反馈，为竞品功能分析和产品定位提供依据。
  • 筛选特定星级评论，单独获取一星或五星评论，定位应用的主要负面问题或高满意度功能。
  • 按最新评论监测口碑变化，使用 sort_by: newest 持续获取近期评论，及时发现版本更新后的用户反馈变化。
  • 批量创建多地区评论任务，针对不同国家和语言提交任务，比较应用在各市场的评分表现与用户点。
  • 通过回调自动接收任务结果， postback_url 或 pingback_url，减少轮询开销并将评论数据接舆监测、产品分析流程。

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

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