SeerMarTech API 文档

主题

设置 Google Dataset Info 任务 ​

本接口用于创建 Google Dataset Info 查询任务。创建任务后，平台 API 会返回你指定数据集的信息。该结果并非普通 SERP 列表项，而是数据集页信息，通常数据集说明、、许可证以及在搜索结果中的描述信息。

接口支持两种执行优级：

  • 1：普通优级（默认）
  • 2：高优级

接口地址 ​

POST https://api.seermartech.cn/v3/serp/google/dataset_info/task_post

计费说明 ​

该接口按“创建任务”计费，而不是按获取结果计费。

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

根据原始参考价格换算，普通任务参考价约为：

  • 参考价约 ¥0.0096 / 次

说明：上方价格基于示例响应换算，费用请以接口返回的 cost 字段为准。

请求说明 ​

  • 请求方法：POST -类型：application/json
  • 编码：UTF-8
  • 请求体格式：JSON 数组 [{ ... }]

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

你可以通过任务唯一标识 id 轮询获取结果；也可以在创建任务时指定 postback_url 或 pingback_url，由系统在任务完成后主动通知你的服务。

如果你的服务端在 10 秒未响应回调请求，该连接会因时中止，任务会转“Tasks Ready”结果列表中你后续拉取。错误码和错误消息取决于你的服务器。

请求参数 ​

主要参数 ​

字段名类型说明
dataset_idstring填。数据集 ID。可从数据集 URL 或 Google Dataset Search 结果中的 dataset 字段获取。示例：L2cvMTFqbl85ZHN6MQ==
language_codestring可选。搜索引擎语言代码。设置后无需再传 language_name。可选值：en
priorityinteger可选。任务优级。1 = 普通优级（默认），2 = 高优级。高优级会额外收费。
devicestring可选。设备类型。当前可选值：desktop
pingback_urlstring可选。任务完成后用于接收通知的 URL。系统会向该地址发起 GET 请求。可在 URL 中使用 $id 作为任务 ID 占位符，使用 $tag 作为 URL 编码后的任务标签占位符。示例：http://your-server.com/pingscript?id=$id 或 http://your-server.com/pingscript?id=$id&tag=$tag。注意：pingback_url 中的特殊字符会被 URL 编码，例如 # 会被编码为 %23。
postback_urlstring可选。任务完成后用于接收结果数据的 URL。系统会向该地址发起 POST 请求，并以 gzip 压缩格式发送结果。可在 URL 中使用 $id 和 $tag 占位。示例：http://your-server.com/postbackscript?id=$id 或 http://your-server.com/postbackscript?id=$id&tag=$tag。注意：特殊字符会被 URL 编码。
postback_datastring当指定 postback_url 时填。表示发送到你服务端的数据类型。可选值：advanced

附加参数 ​

字段名类型说明
language_namestring可选。搜索引擎语言名。设置后无需再传 language_code。可选值：English
osstring可选。设备操作系统。可选值：windows、macos。默认值：windows
tagstring可选。自定义任务标识，最长 255 个字符。可用于将任务与业务系统中的对象。返回结果中会在 data 对象中带回该值。

结果获取方式 ​

创建任务后，接口不会立即返回数据集，而是返回任务受理结果。 你可以通过以下方式获取最终结果：

  1. 使用返回的任务 id 查询任务结果；
  2. 在创建任务时 pingback_url，任务完成后接收通知；
  3. 在创建任务时 postback_url，任务完成后直接接收结果数据。

响应结构 ​

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

顶层字段 ​

字段名类型说明
versionstring当前 API 版本
status_codeinteger通用状态码
status_messagestring通用状态消息
timestring执行耗时，单位秒
costfloat本次请求总费用，单位 USD
tasks_countintegertasks 数组中的任务总数
tasks_errorintegertasks 数组中返回错误的任务数量
tasksarray任务数组

tasks 数组字段 ​

字段名类型说明
idstring平台唯一任务 ID，UUID 格式
status_codeinteger任务状态码，范围通常为 10000-60000
status_messagestring任务状态消息
timestring执行耗时，单位秒
costfloat该任务费用，单位 USD
result_countintegerresult 数组中的数量
patharrayURL 路径
dataobject与提交时请求参数一致的数据对象
resultarray / null结果数组。对于任务创建接口，此处通常为 null

建议在接时实现完整的状态码与异常处理机制，以便应对请求失败、参数错误、额限制和回调异常等。

请求示例 ​

cURL ​

bash
curl --location --request POST 'https://api.seermartech.cn/v3/serp/google/dataset_info/task_post' \
--header 'Authorization: Bearer smt_live_YOUR_KEY' \
--header 'Content-Type: application/json' \
--data-raw '[
 {
 "dataset_id": "L2cvMTFqbl85ZHN6MQ=="
 },
 {
 "dataset_id": "L2cvMTFqbl85ZHN6MQ==",
 "priority": 2,
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 }
]'

Python ​

python
import requests

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

data = [
 {
 # 示例 1：最简任务，只传 dataset_id
 "dataset_id": "L2cvMTFqbl85ZHN6MQ=="
 },
 {
 # 示例 2：附带高优级、标签和回调地址
 "dataset_id": "L2cvMTFqbl85ZHN6MQ==",
 "priority": 2,
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 }
]

response = requests.post(url, headers=headers, json=data)
print(response.json)

TypeScript ​

typescript
import axios from "axios";

const postData = [
 {
 // 示例 1：提交填参数
 dataset_id: "L2cvMTFqbl85ZHN6MQ=="
 },
 {
 // 示例 2：附加优级、业务标签和 pingback 回调
 dataset_id: "L2cvMTFqbl85ZHN6MQ==",
 priority: 2,
 tag: "some_string_123",
 pingback_url: "https://your-server.com/pingscript?id=$id&tag=$tag"
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/serp/google/dataset_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);
 });

响应示例 ​

json
{
 "version": "0.1.20221214",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0825 sec.",
 "cost": 0.0006,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "serp",
 "function": "task_post",
 "se": "google",
 "se_type": "dataset_info",
 "dataset_id": "L2cvMTFqbl85ZHN6MQ==",
 "device": "desktop",
 "os": "windows"
 },
 "result": null
 }
 ]
}

响应示例说明 ​

以上响应表示任务已成功创建：

  • 顶层 status_code: 20000 表示请求已成功受理
  • cost: 0.0006 表示本次请求扣费为 USD 0.0006
  • tasks[0].result: null 表示这里只是任务创建结果，并非最终数据集
  • 后续需要通过任务 ID 获取结果，或回调推送

按换算规则，该示例对应费用约为：

  • 参考价约 ¥0.0096 / 次

错误处理说明 ​

常见错误处理建议如下：

  • 当单次 POST 请求 100 个任务时，出部分返回 40006
  • 当 postback_url 已填写但未传 postback_data 时，请求会因参数不完整而失败
  • 如果回调地址在 10 秒未正确响应，回调连接会时中止，任务需改为后续主动拉取
  • 请结合 status_code、status_message、tasks_error 以及各任务级别状态码进行处理

更多错误码请参考 /v3/appendix/errors。

使用建议 ​

  • 批量创建任务时，将每次请求控制在 100 个任务
  • 若需要更快结果返回，可使用 priority=2，但要注意额外成本
  • 如果你的业务链路依赖异步处理，建议使用 tag 任务编号
  • 使用 postback_url 时，请确保服务端支持接收 gzip 压缩的 POST 数据
  • 使用 pingback_url 时，请确保 URL 参数可正确接收 $id 和 $tag 替换值

实用场景 ​

  • 识别数据集版权归属：抓取数据集、许可证和描述信息，用于判断可用性与合规风险
  • 补数据集页信息：根据 dataset_id 拉取结构化，丰富站数据目录或知识库页面
  • 监控重点数据资产展示：定期查询核心数据集在搜索结果中的呈现，评估质量
  • 建立数据集报看板：批量创建任务收集多个数据集信息，为竞品研究和资源盘点提供依据
  • 异步采集流程：通过 pingback_url 或 postback_url 接收任务完成通知，接自动化 SEO/数据管道

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

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