本指南使用 Web Scraper API(Datasets)一次请求返回 Google SERP 第 1-100 位。您可以控制语言、地理定位、分页深度和设备类型。
前置条件
开始前,请确保您拥有:
一个有效的 Bright Data 账户
API key(在仪表盘 API Tokens 中可找到)
Dataset ID:gd_mfz5x93lmsjjjylob
计费说明: 一次成功的 API 调用 = 一次计费请求,无论分页深度如何。包含重试,无额外带宽费用。详情请参见 SERP 定价与计费 。
快速开始
尝试以下示例,一次请求获取前 100 条结果。将 ${API_KEY} 替换为您的实际 API key。
基本示例
该示例返回大约 100 条结果(10 页 × 每页约 10 条):
curl -X POST "https://api.brightdata.com/datasets/v3/trigger?dataset_id=gd_mfz5x93lmsjjjylob&include_errors=true" \
-H "Authorization: Bearer ${ API_KEY }" \
-H "Content-Type: application/json" \
-d '[{
"url": "https://www.google.com/",
"keyword": "pizza",
"language": "en",
"country": "US",
"start_page": 1,
"end_page": 10
}]'
关键参数
参数 类型 描述 示例 keywordstring 搜索关键词 "pizza"languagestring UI 语言(ISO 639-1) "en", "de"countrystring 地理位置(ISO 3166-1) "US", "DE"start_pageinteger 起始页 1end_pageinteger 结束页 10(约前 100 条)
分页范围: 使用 start_page 和 end_page 控制深度:
1..2 ≈ 前 20 条结果
1..5 ≈ 前 50 条结果
1..10 ≈ 前 100 条结果
较小范围完成更快,返回的 payload 更小。
AI Overview 提取
当搜索查询可用时,API 会自动捕获 Google AI Overview 。
什么是 AI Overview?
AI Overview 是 Google 自动生成的摘要,显示在搜索结果顶部,提供来自多个来源的快速答案。
返回字段
AI Overview 文本返回在 aio_text 字段中:
{
"keyword" : "does honey expire?" ,
"aio_text" : "No, pure honey does not expire , as its high sugar content, low moisture, and acidity create an environment hostile to bacteria. While pure honey can last indefinitely, commercial honey may have a \" best by \" date for quality rather than safety..." ,
"organic" : [ ... ],
"people_also_ask" : [ ... ]
}
AI Overview 可用性: 如果搜索结果没有显示 AI Overview,则 aio_text 字段为空或 null。
示例处理
const results = await response . json ();
results . forEach ( result => {
if ( result . aio_text ) {
console . log ( 'AI Overview:' , result . aio_text );
// 拆分成多个段落
const sections = result . aio_text . split ( ' \n\n ' );
sections . forEach ( section => console . log ( section ));
}
});
理解异步工作流
Web Scraper API 为异步工作模式,工作流程如下:
触发请求 → 获取 snapshot_id
监控进度 → 使用 snapshot_id 查看状态
下载结果 → 完成后获取数据
API 端点
操作 方法 端点 触发请求 POST /datasets/v3/trigger?dataset_id=gd_mfz5x93lmsjjjylob检查进度 GET /datasets/v3/progress/{snapshot_id}下载结果 GET /datasets/v3/snapshot/{snapshot_id}
完整工作流示例
import fetch from "node-fetch" ;
const API_KEY = process . env . API_KEY ;
const DATASET_ID = "gd_mfz5x93lmsjjjylob" ;
// 步骤 1:触发请求
const triggerRes = await fetch (
`https://api.brightdata.com/datasets/v3/trigger?dataset_id= ${ DATASET_ID } &include_errors=true` ,
{
method: "POST" ,
headers: {
"Content-Type" : "application/json" ,
Authorization: `Bearer ${ API_KEY } ` ,
},
body: JSON . stringify ([
{
url: "https://www.google.com/" ,
keyword: "pizza" ,
language: "en" ,
country: "US" ,
start_page: 1 ,
end_page: 10 ,
},
]),
}
);
const { snapshot_id } = await triggerRes . json ();
// 步骤 2:轮询完成状态
let progress ;
do {
await new Promise (( resolve ) => setTimeout ( resolve , 5000 )); // 等待 5 秒
const progressRes = await fetch (
`https://api.brightdata.com/datasets/v3/progress/ ${ snapshot_id } ` ,
{
headers: { Authorization: `Bearer ${ API_KEY } ` },
}
);
progress = await progressRes . json ();
} while ( progress . status !== "ready" );
// 步骤 3:下载结果
const downloadRes = await fetch (
`https://api.brightdata.com/datasets/v3/snapshot/ ${ snapshot_id } ?format=json` ,
{
headers: { Authorization: `Bearer ${ API_KEY } ` },
}
);
const results = await downloadRes . json ();
console . log ( results );
高级配置
批量多个查询
一次请求处理多个搜索查询:
[
{
"url" : "https://www.google.com/" ,
"keyword" : "pizza" ,
"language" : "en" ,
"country" : "US" ,
"start_page" : 1 ,
"end_page" : 10
},
{
"url" : "https://www.google.com/" ,
"keyword" : "coffee" ,
"language" : "de" ,
"country" : "DE" ,
"start_page" : 1 ,
"end_page" : 10
},
{
"url" : "https://www.google.com/" ,
"keyword" : "running shoes" ,
"language" : "en" ,
"country" : "GB" ,
"start_page" : 1 ,
"end_page" : 5
}
]
移动端搜索结果
添加 "brd_mobile": true 获取移动端 SERP 数据:
curl -X POST "https://api.brightdata.com/datasets/v3/trigger?dataset_id=gd_mfz5x93lmsjjjylob&include_errors=true" \
-H "Authorization: Bearer ${ API_KEY }" \
-H "Content-Type: application/json" \
-d '[{
"url": "https://www.google.com/",
"keyword": "running shoes",
"language": "en",
"country": "US",
"start_page": 1,
"end_page": 10,
"brd_mobile": true
}]'
包含 HTML 快照
同时捕获原始 HTML 以便审计或自定义解析:
{
"url" : "https://www.google.com/" ,
"keyword" : "pizza" ,
"language" : "en" ,
"country" : "US" ,
"start_page" : 1 ,
"end_page" : 10 ,
"include_paginated_html" : true
}
启用后,结果中每页将包含 pagination[].page_html。
本地化示例
通过语言和国家组合定位特定市场:
// 德语,德国
{
"keyword" : "laufschuhe" ,
"language" : "de" ,
"country" : "DE" ,
"start_page" : 1 ,
"end_page" : 5
}
// 英语,英国
{
"keyword" : "trainers" ,
"language" : "en" ,
"country" : "GB" ,
"start_page" : 1 ,
"end_page" : 10
}
// 西班牙语,墨西哥
{
"keyword" : "zapatos deportivos" ,
"language" : "es" ,
"country" : "MX" ,
"start_page" : 1 ,
"end_page" : 10
}
常见问题
您可以选择返回所有页面的解析字段。若要同时包含每页的原始 HTML,请在请求中添加 "include_paginated_html": true。这样会在解析字段旁返回 pagination[].page_html。
我可以控制 AI Overview (AIO) 的显示吗?
当 Google 显示 AI Overview 且输出字段中包含该字段时,它会返回。未来将提供开关以显式包含或排除 AIO。
我们现在使用浏览器工作器进行 SERP 抓取。这减少了重复结果,提高了分页间的会话连续性,并支持更丰富的输出(例如 AI Overview)。所有现有请求仍向后兼容。
一次成功的 API 调用 = 一次计费请求,即使它返回了 10 页共 100+ 结果。重试请求自动包含在内,无额外带宽费用。完整详情请参见 SERP 计费 。
language 和 country 参数有什么区别?
language:控制 Google 使用的界面语言(例如 "en"、"de"、"es")
country:控制结果的地理位置(例如 "US"、"DE"、"MX")
这两个参数可以独立组合,以针对特定市场。
时间取决于查询复杂度和页面深度。较小的页面范围(例如 1..2)完成速度快于较大范围(例如 1..10)。可使用 Progress API 监控请求状态。
下一步