business_data/trustpilot/search/task_post：提交 Trustpilot 商家搜索任务

POST /v3/business_data/trustpilot/search/task_post

本接口使用 POST 方法提交 Trustpilot 商家搜索任务：

POST https://api.seermartech.cn/v3/business_data/trustpilot/search/task_post

接口根据指定的 keyword 返回 Trustpilot 平台上的商家资料。

> 计费说明： 每返回最多 10 条搜索结果计费一次。例如，将 depth 设置为 11 时，可能 20 条搜索结果计费。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求说明

请求格式为 UTF-8 编码的 JSON。
请求体是 JSON 数组，数组中的每个代表一个任务。
每分钟最多提交 30 次请求。
每次请求最多 100 个任务； 100 个的任务将返回错误码 40006。
任务提交成功后，可通过返回的任务 id 获取结果。
也可以在提交任务时设置 postback_url 或 pingback_url，任务完成后由本平台主动通知。
如果通知服务器在 10 秒未响应，连接将因时中断，任务会转移到任务就绪列表。错误码和错误信息取决于通知服务器的。

计费

任务费用由任务提交费用和返回结果数量决定。设置高优级任务（priority: 2）可能产生额外费用。

扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数

每个任务对象支持以下字段：

字段	类型	填	说明
`keyword`	string	是	搜索，应填写商家类别或名称。最多 700 个字符。
`priority`	integer	否	任务执行优级：`1` 为普通优级，默认值；`2` 为高优级。高优级任务可能产生额外费用。
`depth`	integer	否	解析深度，即希望返回的搜索结果数量。默认值为 `10`，最大值为 `140`。建议使用 20 的倍数，因为系统会按批次处理搜索结果。
`tag`	string	否	用户自定义任务标识，最多 255 个字符。该值会原样出现在响应对象的 `data` 中，便于将任务与业务记录匹。
`postback_url`	string	否	任务完成后，本平台向该地址发送任务结果的 POST 请求，采用 gzip 压缩格式。
`pingback_url`	string	否	任务完成后，本平台向该地址发送 GET 请求进行通知。

`keyword` 编码规则

keyword 中的百分号编码会被解码。
加号（+）会被解码为空格。
如果本身需要使用百分号字符，应将编码为 %25。
长度上限为 700 个字符。

`postback_url` 和 `pingback_url` 占位符

可以在 URL 中使用以下占位符：

$id：任务完成后替换为任务 ID。
$tag：任务完成后替换为经过 URL 编码的任务标签。

示例：

text

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

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

请求示例

curl

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/business_data/trustpilot/search/task_post" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "keyword": "pizza restaurant"
    },
    {
      "keyword": "pizza restaurant",
      "depth": 20,
      "priority": 2,
      "tag": "some_string_123",
      "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
    },
    {
      "keyword": "pizza restaurant",
      "postback_url": "https://your-server.com/postbackscript"
    }
  ]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/business_data/trustpilot/search/task_post"

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

post_data = [
    {
        "keyword": "pizza restaurant",
    },
    {
        "keyword": "pizza restaurant",
        "depth": 20,
        "priority": 2,
        "tag": "some_string_123",
        "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag",
    },
    {
        "keyword": "pizza restaurant",
        "postback_url": "https://your-server.com/postbackscript",
    },
]

response = requests.post(url, headers=headers, json=post_data)
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 postData = [
  {
    keyword: "pizza restaurant",
  },
  {
    keyword: "pizza restaurant",
    depth: 20,
    priority: 2,
    tag: "some_string_123",
    pingback_url:
      "https://your-server.com/pingscript?id=$id&tag=$tag",
  },
  {
    keyword: "pizza restaurant",
    postback_url: "https://your-server.com/postbackscript",
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/business_data/trustpilot/search/task_post",
    postData,
    {
      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 数组。每个任务对象任务提交状态和任务参数。

顶层响应字段

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	请求级状态码。`20000` 表示请求成功。
`status_message`	string	请求级状态信息。
`time`	string	请求执行耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`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 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`result_count`	integer	`result` 数组中的数量。任务提交接口通常为 `0`。
`path`	array	当前任务对应的 API 路径信息。
`data`	object	提交任务时使用的参数。
`result`	array \| null	任务结果数组。提交任务成功后通常为 `null`，需通过任务查询接口获取结果。

响应示例

json

{
  "version": "0.1.20220208",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.0970 sec.",
  "cost": 0.00075,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "13900000-0000-0000-0000-000000000000",
      "status_code": 20100,
      "status_message": "Task Created.",
      "time": "0.0120 sec.",
      "cost": 0.00075,
      "result_count": 0,
      "path": [
        "v3",
        "business_data",
        "trustpilot",
        "search",
        "task_post"
      ],
      "data": {
        "api": "business_data",
        "function": "search",
        "keyword": "pizza restaurant",
        "se_type": "organic",
        "se": "trustpilot",
        "device": "desktop",
        "os": "windows"
      },
      "result": null
    }
  ]
}

说明

任务提交成功并不代表搜索结果已经生成，需使用返回的 id 查询任务结果。
使用 postback_url 时，本平台会以 POST 方式发送结果，并使用 gzip 格式压缩请求。
使用 pingback_url 时，本平台只发送任务完成通知，业务系统随后可根据任务 ID 查询完整结果。
建议在业务系统中同时处理请求级状态码和任务级状态码，并针对异常状态进行重试或告警。

实用场景

检索目标行业商家：按“餐”“”“软件服务”等类别批量搜索商家资料，为行业市场规模评估和竞品分析提供数据。
发现潜在品牌客户：使用名称或品牌查找商家档案，支持销售线索挖掘和客户名单扩。
批量构建商家数据集：一次提交多个任务，集中采集不同行业或地区的商家搜索结果，提升数据采集效率。
跟踪商家评价平台覆盖：定期提交品牌并保存任务结果，分析目标商家在评价平台上的和覆盖变化。
接异步数据处理流程： postback_url 或 pingback_url，在任务完成后自动触发数据库、报表更新或 SEO 监控告警。

business_data/trustpilot/search/task_post：提交 Trustpilot 商家搜索任务 ​

请求说明 ​

计费 ​

请求参数 ​

keyword 编码规则 ​

postback_url 和 pingback_url 占位符 ​

请求示例 ​

curl ​

Python ​

TypeScript ​

响应说明 ​

顶层响应字段 ​

tasks 子字段 ​

响应示例 ​

说明 ​

实用场景 ​