跳转到主要内容
本指南使用 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"
languagestringUI 语言(ISO 639-1)"en", "de"
countrystring地理位置(ISO 3166-1)"US", "DE"
start_pageinteger起始页1
end_pageinteger结束页10(约前 100 条)
分页范围: 使用 start_pageend_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 为异步工作模式,工作流程如下:
  1. 触发请求 → 获取 snapshot_id
  2. 监控进度 → 使用 snapshot_id 查看状态
  3. 下载结果 → 完成后获取数据

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
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
当 Google 显示 AI Overview 且输出字段中包含该字段时,它会返回。未来将提供开关以显式包含或排除 AIO。
我们现在使用浏览器工作器进行 SERP 抓取。这减少了重复结果,提高了分页间的会话连续性,并支持更丰富的输出(例如 AI Overview)。所有现有请求仍向后兼容。
一次成功的 API 调用 = 一次计费请求,即使它返回了 10 页共 100+ 结果。重试请求自动包含在内,无额外带宽费用。完整详情请参见 SERP 计费
  • language:控制 Google 使用的界面语言(例如 "en""de""es"
  • country:控制结果的地理位置(例如 "US""DE""MX"
这两个参数可以独立组合,以针对特定市场。
时间取决于查询复杂度和页面深度。较小的页面范围(例如 1..2)完成速度快于较大范围(例如 1..10)。可使用 Progress API 监控请求状态。

下一步