Google Dataset Search 任务创建

GET /v3/serp/google/dataset_search/task_post

接口说明

通过本接口可提交 Google Dataset Search 采集任务，获取与指定的数据集搜索结果。默认返回前 20 条结果，并支持语言、更新时间、文件格式、使用权限、是否、主题等筛选条件。

接口采用异步任务模式：

• 调用本接口创建任务；
• 再通过任务 id 获取结果；
• 或在创建任务时 pingback_url / postback_url，由本平台在任务完成后主动通知或推送结果。

请求方式

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

计费说明

该接口按任务创建计费。

• 默认深度为 20
• 每个最多 20 条结果的 SERP 计费一次
• 当 depth 大于 20 且搜索引擎返回 20 条结果时，可能产生额外费用
• 若设置的 depth 高于返回结果数量，差额会自动退回余额
• 高优级任务 priority=2 会额外加价

参考价约 ¥0.0096 / 次 扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求限制

• 每分钟最多提交 2000 次 API 调用
• 单次 POST 最多 100 个任务 -过 100 个任务时，出部分会返回 40006 错误

回调说明

任务完成后可通过以下两种方式接收通知：

• pingback_url：任务完成后，本平台向该地址发送 GET 请求
• postback_url：任务完成后，本平台向该地址发送结果的 POST 请求，数据使用 gzip 压缩

注意事项：

• 如果回调服务在 10 秒未响应，请求会因时中断 -时后，任务会可提取结果列表，您仍可通过任务查询接口获取结果
• pingback_url 和 postback_url 中可使用：
• $id：任务 ID
• $tag：URL 编码后的自定义标签
• 回调 URL 中的特殊字符会自动进行 URL 编码，例如 # 会编码为 %23

---

请求参数

主要参数

字段	类型	说明
keyword	string	填。搜索，最长 700 个字符。%## 会被解码，字符 + 会被解码为空格。若中需要保留 %，请写为 %25；若需要保留 +，请写为 %2B。
language_code	string	可选。搜索语言代码。可选值：en
depth	integer	可选。解析深度，即返回结果数量。默认 20，最大 700。 20 可能触发额外计费。
priority	integer	可选。任务优级。1 = 普通优级（默认），2 = 高优级。高优级会额外计费。
device	string	可选。设备类型。可选值：desktop
pingback_url	string	可选。任务完成通知地址，本平台会向该地址发送 GET 请求。支持 $id 和 $tag 变量。
postback_url	string	可选。任务结果推送地址，本平台会向该地址发送 gzip 压缩的 POST 结果。支持 $id 和 $tag 变量。
postback_data	string	当指定 postback_url 时填。回传数据类型支持：advanced

附加参数

字段	类型	说明
language_name	string	可选。搜索语言名。设置后可不传 language_code。可选值：English
os	string	可选。设备操作系统。可选值：windows、macos。默认：windows
tag	string	可选。自定义任务标识，最长 255 字符。可用于请求结果匹，响应的 data 对象中会返回该值。
last_updated	string	可选。数据集最后更新时间。可选值：1m、1y、3y
file_formats	array	可选。数据集文件格式筛选。可选值：other、archive、text、image、document、tabular
usage_rights	string	可选。数据集使用权限。可选值：commercial、noncommercial
is_free	boolean	可选。是否显示数据集。可选值：true、false
topics	array	可选。数据集主题分类。可选值：humanities、social_sciences、life_sciences、agriculture、natural_sciences、geo、computer、architecture_and_urban_planning、engineering

---

请求体格式

POST 请求体为 JSON 数组：

[
 {
 "keyword": "water quality",
 "last_updated": "1m",
 "file_formats": ["text", "tabular"],
 "usage_rights": "noncommercial",
 "is_free": true,
 "topics": ["natural_sciences", "geo"]
 }
]

---

请求示例

cURL

curl --location --request POST 'https://api.seermartech.cn/v3/serp/google/dataset_search/task_post' \
--header 'Authorization: Bearer smt_live_YOUR_KEY' \
--header 'Content-Type: application/json' \
--data-raw '[
 {
 "keyword": "water quality",
 "last_updated": "1m",
 "file_formats": ["text", "tabular"],
 "usage_rights": "noncommercial",
 "is_free": true,
 "topics": ["natural_sciences", "geo"]
 },
 {
 "keyword": "water quality",
 "last_updated": "1m",
 "file_formats": ["text", "tabular"],
 "usage_rights": "noncommercial",
 "is_free": true,
 "topics": ["natural_sciences", "geo"],
 "priority": 2,
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 }
]'

Python

import requests

url = "https://api.seermartech.cn/v3/serp/google/dataset_search/task_post"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
data = [
 {
 "keyword": "water quality",
 "last_updated": "1m",
 "file_formats": ["text", "tabular"],
 "usage_rights": "noncommercial",
 "is_free": True,
 "topics": ["natural_sciences", "geo"]
 },
 {
 "keyword": "water quality",
 "last_updated": "1m",
 "file_formats": ["text", "tabular"],
 "usage_rights": "noncommercial",
 "is_free": True,
 "topics": ["natural_sciences", "geo"],
 "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

import axios from "axios";

const postData = [
 {
 keyword: "water quality",
 last_updated: "1m",
 file_formats: ["text", "tabular"],
 usage_rights: "noncommercial",
 is_free: true,
 topics: ["natural_sciences", "geo"]
 },
 {
 keyword: "water quality",
 last_updated: "1m",
 file_formats: ["text", "tabular"],
 usage_rights: "noncommercial",
 is_free: true,
 topics: ["natural_sciences", "geo"],
 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_search/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 编码结果，顶层 tasks 数组。

顶层字段

字段	类型	说明
version	string	API 当前版本
status_code	integer	通用状态码
status_message	string	通用状态信息
time	string	执行耗时，单位秒
cost	float	本次请求总费用，单位 USD
tasks_count	integer	tasks 数组中的任务数量
tasks_error	integer	返回错误的任务数量
tasks	array	任务数组

tasks 数组字段

字段	类型	说明
id	string	任务唯一标识，UUID 格式
status_code	integer	任务状态码，范围通常为 10000-60000
status_message	string	任务状态说明
time	string	任务执行耗时
cost	float	单任务费用，单位 USD
result_count	integer	result 数组中的数量
path	array	URL 路径
data	object	您在请求中提交的任务参数
result	array / null	任务创建接口中通常返回 null，结果需后续查询

建议在系统中完整处理状态码和异常。错误码可参考 /v3/appendix/errors。

---

响应示例

{
 "version": "0.1.20220819",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0469 sec.",
 "cost": 0.0006,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "018b7f7e-6c8d-4d2e-9c1e-1234567890ab",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0000 sec.",
 "cost": 0.0006,
 "result_count": 0,
 "path": [
 "v3",
 "serp",
 "google",
 "dataset_search",
 "task_post"
 ],
 "data": {
 "api": "serp",
 "function": "task_post",
 "se": "google",
 "se_type": "dataset_search",
 "keyword": "water quality",
 "last_updated": "1m",
 "file_formats": ["text", "tabular"],
 "usage_rights": "noncommercial",
 "is_free": true,
 "topics": ["natural_sciences", "geo"],
 "device": "desktop",
 "os": "windows"
 },
 "result": null
 }
 ]
}

---

状态与错误处理

常见规则如下：

• 20000：请求成功
• 单个任务创建成功时，任务级状态通常会返回成功状态码，例如 20100
• 如果单次请求任务数 100，出部分会返回 40006
• 回调地址时或异常时，任务不会丢失，可改为通过任务结果接口主动拉取

完整错误码请参考 /v3/appendix/errors。

使用建议

• 批量提交时，建议每次控制在 100 个任务
• 若对时效要求较高，可使用 priority=2，但需额外费用
• 如需按业务单回溯任务，请为每个任务设置 tag
• 如需构建自动化流水线，优使用 postback_url 接收结果推送
• keyword 中若 % 或 +，请按编码规则显式转义

实用场景

• 监控科研数据：按持续采集特定主题的数据集搜索结果，评估机构、实验室或项目数据在搜索中的可见性。
• 筛选可商用数据源：结合 usage_rights 与 is_free 参数，快速定位可商用或数据集，降低数据采购与合规筛查成本。
• 追踪最新数据发布：通过 last_updated 条件锁定近 1 个月或近 1 年更新的数据集，及时发现新发布的数据资源与研究趋势。
• 细分垂类主题研究：使用 topics 参数聚焦农业、地理、计算机、生命科学等领域，支持行业研究和选题策划。
• 锁定可用文件格式：通过 file_formats 过滤表格、文本、文档等格式，便于下游分析系统直接消费和处理数据。