Google Dataset Search 实时结果（高级）

POST /v3/serp/google/dataset_search/live/advanced

接口说明

该接口用于实时获取 Google Dataset Search 的搜索结果，默认返回前 20 条数据集结果。结果与指定精确对应，并支持附加筛选条件，例如更新时间、文件格式、使用权限、是否、主题分类等。

请求方式：POST
请求地址：https://api.seermartech.cn/v3/serp/google/dataset_search/live/advanced

计费说明

该接口按请求计费。

参考价约 ¥0.0320 / 次。若设置 depth 大于 20，当搜索引擎返回 20 条结果时，可能产生额外扣费。如果设置的 depth 高于返回结果数量，差额会自动退回余额。

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

请求要求

所有 POST 数据使用 JSON（UTF-8）
请求体格式为 JSON 数组：[{ ... }]
每次 Live SERP 请求 只能 1 个任务
频率限制：最高 2000 次请求/分钟

请求参数

主要参数

字段名	类型	说明
`keyword`	string	填。搜索，最长 700 个字符。 `%##` 会被解码，`+` 会被解码为空格。如需在中保留 `%`，请写为 `%25`；如需保留 `+`，请写为 `%2B`。
`language_code`	string	搜索语言代码。可选。如未传 `language_name`，可使用该字段。可选值：`en`
`depth`	integer	解析深度，即返回的结果数量。可选。默认值：`20`；最大值：`700`
`device`	string	设备类型。可选。当前可选值：`desktop`

附加参数

字段名	类型	说明
`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`

返回结构

接口返回 JSON 对象，顶层 tasks 数组，每个任务对应一次获取结果。

顶层字段

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

tasks 数组中的字段

字段名	类型	说明
`id`	string	任务唯一标识，UUID 格式
`status_code`	integer	任务状态码，范围通常为 `10000-60000`，完整列表见 `/v3/appendix/errors`
`status_message`	string	任务状态信息
`time`	string	任务耗时，单位秒
`cost`	float	当前任务费用，单位 USD
`result_count`	integer	`result` 数组数量
`path`	array	URL 路径
`data`	object	与请求中提交参数一致的回显数据
`result`	array	获取结果数组

result 数组中的字段

字段名	类型	说明
`keyword`	string	请求中的。返回时 `%##` 已解码，`+` 会被解码为空格
`se_domain`	string	请求中的搜索引擎域名
`language_code`	string	请求中的语言代码
`check_url`	string	可直接打开的搜索结果页 URL，用于校验结果准确性
`datetime`	string	抓取结果时间，UTC 格式：`yyyy-mm-dd hh-mm-ss +00:00`
`spell`	object	搜索引擎自动纠错信息。如被自动修正，会返回修正后的及纠错类型
`refinement_chips`	object	搜索细化筛选项
`item_types`	array	当前 SERP 中识别到的结果类型列表。该接口可能值为 `dataset`
`se_results_count`	integer	SERP 总结果数
`items_count`	integer	`items` 数组中的结果数量
`items`	array	搜索结果列表

字段名	类型	说明
`type`	string	素类型，固定为 `refinement_chips`
`xpath`	string	素的 XPath
`items`	array	细化筛选项列表

字段名	类型	说明
`type`	string	素类型，固定为 `refinement_chips_element`
`title`	string	筛选项标题
`url`	string	带筛选参数的搜索 URL
`domain`	string	SERP 中显示的域名
`options`	array	更进一步的筛选选项

字段名	类型	说明
`type`	string	素类型，固定为 `refinement_chips_option`
`title`	string	选项标题
`url`	string	带筛选参数的搜索 URL
`domain`	string	SERP 中显示的域名

items 数组字段说明

items 中每个代表一个数据集搜索结果。

字段名	类型	说明
`type`	string	素类型，固定为 `dataset`
`rank_group`	integer	分组排名。在相同 `type`素组的位置
`rank_absolute`	integer	绝对排名。在整个 SERP 中的位置
`position`	string	页面位置。可选值：`left`、`right`
`xpath`	string	素 XPath
`dataset_id`	string	数据集 ID
`title`	string	数据集标题
`image_url`	string	图片 URL。可能指向原站图片，也可能为平台缓存地址
`scholarly_citations_count`	integer	学术引用数量
`scholarly_articles_url`	string	学术文章链接，通常为 Scholar 查询地址
`unique_identifier`	string	数据集数字唯一标识，例如 DOI
`related_article`	string	已发表文章链接
`links`	array	数据集下方显示的附加链接；如果没有则为 `null`
`dataset_providers`	array	数据集提供机构列表
`formats`	array	数据集文件格式列表
`authors`	array	数据集列表
`licenses`	array	数据集许可证列表
`updated_date`	string	数据集最近更新时间，UTC 格式：`yyyy-mm-dd hh-mm-ss +00:00`
`area_covered`	array	数据覆盖区域列表，例如 `Africa`、`Global`
`period_covered`	object	数据覆盖时间范围
`dataset_description`	object	数据集描述信息

`links`素字段

字段名	类型	说明
`type`	string	素类型，固定为 `link_element`
`title`	string	链接标题
`description`	string	链接描述
`url`	string	链接地址
`domain`	string	链接域名

`dataset_providers`素字段

字段名	类型	说明
`type`	string	素类型，固定为 `dataset_providers_element`
`title`	string	提供机构名称
`url`	string	提供机构站点链接
`domain`	string	提供机构域名

`formats`素字段

字段名	类型	说明
`type`	string	素类型，固定为 `formats_element`
`format`	string	文件格式，例如 `zip`、`html`、`csv`
`size`	string	文件大小，字节数

`authors`素字段

字段名	类型	说明
`type`	string	素类型，固定为 `authors_element`
`name`	string	名称
`url`	string	链接
`domain`	string	链接域名

`licenses`素字段

字段名	类型	说明
`type`	string	素类型，固定为 `licenses_element`
`title`	string	许可证名称
`url`	string	许可证链接
`domain`	string	许可证页面域名

`period_covered` 字段说明

字段名	类型	说明
`start_date`	string	起始时间，UTC 格式：`yyyy-mm-dd hh-mm-ss +00:00`
`end_date`	string	结束时间，UTC 格式：`yyyy-mm-dd hh-mm-ss +00:00`
`displayed_date`	string	搜索结果页展示的时间范围文本

`dataset_description` 字段说明

字段名	类型	说明
`text`	string	数据集描述文本
`links`	array	描述文本中的链接列表

dataset_description.links 的结构与通用 link_element 一致：

字段名	类型	说明
`type`	string	素类型，固定为 `link_element`
`title`	string	链接锚文本
`description`	string	链接说明
`url`	string	链接地址
`domain`	string	链接域名

请求示例

cURL

bash

curl --location --request POST "https://api.seermartech.cn/v3/serp/google/dataset_search/live/advanced" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "keyword": "water quality",
 "last_updated": "1m",
 "file_formats": ["tabular", "document"],
 "usage_rights": "noncommercial",
 "is_free": true,
 "topics": ["natural_sciences", "geo"]
 }
]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/serp/google/dataset_search/live/advanced"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
data = [
 {
 "keyword": "water quality",
 "last_updated": "1m",
 "file_formats": ["tabular", "document"],
 "usage_rights": "noncommercial",
 "is_free": True,
 "topics": ["natural_sciences", "geo"]
 }
]

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

TypeScript

typescript

import axios from "axios";

async function main {
 const response = await axios.post(
 "https://api.seermartech.cn/v3/serp/google/dataset_search/live/advanced",
 [
 {
 keyword: "water quality",
 last_updated: "1m",
 file_formats: ["tabular", "document"],
 usage_rights: "noncommercial",
 is_free: true,
 topics: ["natural_sciences", "geo"]
 }
 ],
 {
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 }
 }
 );

 console.log(response.data);
}

main.catch(console.error);

响应示例

json

{
 "version": "0.1.20230825",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "3.0987 sec.",
 "cost": 0.002,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "f3f0d0f8-7f8a-4b19-9ac9-123456789abc",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "3.0123 sec.",
 "cost": 0.002,
 "result_count": 1,
 "path": [
 "v3",
 "serp",
 "google",
 "dataset_search",
 "live",
 "advanced"
 ],
 "data": {
 "api": "serp",
 "function": "live",
 "se": "google",
 "se_type": "dataset_search",
 "keyword": "water quality",
 "last_updated": "1m",
 "file_formats": ["tabular", "document"],
 "usage_rights": "noncommercial",
 "is_free": true,
 "topics": ["natural_sciences", "geo"],
 "device": "desktop",
 "os": "windows"
 },
 "result": [
 {
 "keyword": "water quality",
 "se_domain": "google.com",
 "language_code": "en",
 "datetime": "2023-10-25 12:00:00 +00:00",
 "item_types": ["dataset"],
 "se_results_count": 27,
 "items_count": 20,
 "items": [
 {
 "type": "dataset",
 "rank_group": 1,
 "rank_absolute": 1,
 "position": "left",
 "xpath": null,
 "dataset_id": "L2cvMTExMTExMTExMQ==",
 "title": "Watershed Water Quality - Wastewater",
 "image_url": null,
 "scholarly_citations_count": null,
 "scholarly_articles_url": null,
 "unique_identifier": null,
 "related_article": null,
 "links": null,
 "dataset_providers": null,
 "formats": [],
 "authors": [],
 "licenses": [],
 "updated_date": "2023-10-03 03:00:00 +00:00",
 "area_covered": null,
 "period_covered": null,
 "dataset_description": {
 "text": "该数据集长期废水处理监测结果，可用于水质趋势分析与环境研究。",
 "links": null
 }
 },
 {
 "type": "dataset",
 "rank_group": 2,
 "rank_absolute": 2,
 "position": "left",
 "xpath": null,
 "dataset_id": "L2cvMjIyMjIyMjIyMg==",
 "title": "Georgian Bay Water Quality",
 "image_url": "https://encrypted-tbn3.gstatic.com/images?q=tbn:ANd9GcSqDwx-mgL3ad2LqHoJnRHdauU8eFxZr0vxuVzMxnDWOKp2JiGd",
 "scholarly_citations_count": 4,
 "scholarly_articles_url": "https://scholar.google.com/scholar?q=%22georgian%20bay%20water%20quality%22",
 "unique_identifier": null,
 "related_article": null,
 "links": [],
 "dataset_providers": [],
 "formats": [],
 "authors": null,
 "licenses": [],
 "updated_date": "2023-10-18 03:00:00 +00:00",
 "area_covered": ["Canada"],
 "period_covered": {
 "start_date": "2003-01-01 02:00:00 +00:00",
 "end_date": "2005-12-31 02:00:00 +00:00",
 "displayed_date": "Jan 1, 2003 - Dec 31, 2005"
 },
 "dataset_description": {
 "text": "该数据集记录多个监测点的水质状况，可用于区域环境质量评估。",
 "links": null
 }
 }
 ]
 }
 ]
 }
 ]
}

错误处理

建议对以下两层状态做统一处理：

顶层状态：status_code / status_message
任务级状态：tasks[].status_code / tasks[].status_message

状态码完整列表请参考：/v3/appendix/errors

常见处理建议：

20000：请求成功
非 20000：按错误码执行重试、告警或参数修正
当 tasks_error > 0 时，说明部分或任务失败，应逐个检查 tasks状态

建议在生产环境中为网络异常、频控限制、参数错误、服务返回异常设计完整的底机制。

使用建议

若只需标准第一页结果，保持 depth=20 即可，成本更可控
通过 last_updated、file_formats、usage_rights、is_free、topics 可显著提升结果性
若需要识别可商用、可下载、近期更新的数据源，可优组合使用：
usage_rights=commercial
is_free=true
last_updated=1m
file_formats=["tabular"]

实用场景

筛选可复用数据集资源：按检索并结合 usage_rights、is_free、file_formats 过滤，快速定位可商用或可的数据资源。
追踪行业新发布数据：使用 last_updated 限定最近 1 个月或 1 年更新的数据集，及时发现新上线研究数据和资料。
建设垂直数据资源库：针对科研、农业、地理、工程等主题批量查询 topics，沉淀行业数据目录页面，提升自然搜索覆盖。
分析竞品的数据引用来源：提取 dataset_providers、unique_identifier、scholarly_articles_url 等字段，识别高价值数据源与引用链路。
挖掘长尾数据搜索需求：围绕核心主题词持续抓取 Dataset Search 结果，分析标题、描述、格式和覆盖周期，发现用户更的数据类型与方向。

Google Dataset Search 实时结果（高级）

接口说明

计费说明

请求要求

请求参数

主要参数

附加参数

返回结构

顶层字段

tasks 数组中的字段

result 数组中的字段

refinement_chips 字段说明

refinement_chips 对象

refinement_chips.items素

refinement_chips.items.options素

items 数组字段说明

`links`素字段

`dataset_providers`素字段

`formats`素字段

`authors`素字段

`licenses`素字段

`period_covered` 字段说明

`dataset_description` 字段说明

请求示例

cURL

Python

TypeScript

响应示例

错误处理

使用建议

实用场景

Google Dataset Search 实时结果（高级） ​

接口说明 ​

计费说明 ​

请求要求 ​

请求参数 ​

主要参数 ​

附加参数 ​

返回结构 ​

顶层字段 ​

tasks 数组中的字段 ​

result 数组中的字段 ​

refinement_chips 字段说明 ​

refinement_chips 对象 ​

refinement_chips.items素 ​

refinement_chips.items.options素 ​

items 数组字段说明 ​

links素字段 ​

dataset_providers素字段 ​

formats素字段 ​

authors素字段 ​

licenses素字段 ​

period_covered 字段说明 ​

dataset_description 字段说明 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应示例 ​

错误处理 ​

使用建议 ​

实用场景 ​

Google Dataset Search 实时结果（高级）

接口说明

计费说明

请求要求

请求参数

主要参数

附加参数

返回结构

顶层字段

tasks 数组中的字段

result 数组中的字段

refinement_chips 字段说明

refinement_chips 对象

refinement_chips.items素

refinement_chips.items.options素

items 数组字段说明

`links`素字段

`dataset_providers`素字段

`formats`素字段

`authors`素字段

`licenses`素字段

`period_covered` 字段说明

`dataset_description` 字段说明

请求示例

cURL

Python

TypeScript

响应示例

错误处理

使用建议

实用场景