Loading Light/Dark Toggle
返回博客

Google SERP API 分页:使用 start 收集结果

Alex Johnson
Alex Johnson

Senior Web Scraping Engineer

12-Nov-2026

摘要:

  • Google 网页搜索分页使用起始偏移量(start offset)。 在请求 0、10、20 等偏移量时保持查询和本地化设置不变。
  • 十个页面并不意味着一百条自然结果。 一次实际的 coffee 采集在十个页面中共返回了 95 条记录。
  • 去重需要一个明确的定义。 这 95 条记录中只包含 85 个不同的返回链接字符串,但这并不等于 85 个经过验证的、唯一的目标页面。
  • 有界循环必须记录停止原因。 空数组、重复页面、错误以及页面数量上限代表不同的结果。

引言:采集不止第一页的结果

Google SERP API 分页是一系列相关的观测结果。每次请求都在同一次搜索中索取另一个偏移量的结果,每个响应都需要自己的上下文。

本教程使用 Scrapeless Google Search API 来请求最多十页网页搜索结果。它保留每个响应,把偏移量与每条保留记录一起存下,并区分原始行与去重后的链接字符串。这个示例有助于更深入地探索主题、检查搜索覆盖情况。它并没有建立一个完整的前一百名排名数据集。

Google Search 端点控制 定义了网页搜索的偏移量,而 actor 请求模式 说明了外围的 API 调用方式。整个采集过程中应保持搜索模式不变。

start 如何改变请求

start 参数选择网页搜索请求的结果偏移量。普通的分页序列是 0、10、20 等。

偏移量是一个请求控制参数,而不是一个「前一页返回了多少条自然结果」的计数。如果某一页只返回了九条自然结果,在这个示例中下一次请求仍然使用下一个配置好的偏移量。如果按 len(organic_results) 递增,就会把响应记录数量与分页契约混在一起。

保持 q、gl、hl 以及任意显式过滤条件不变。如果在运行到一半时更换国家,那么合并后的数组就不再描述一个单一的搜索配置。把完整的输入对象与每一页一起存储,这样这种错误仍然是可检测的。

该示例省略了 num 和 tbm。它是一个网页搜索分页示例;其他模式必须单独检查。请查阅 当前参数定义,而不是在不同模式之间直接套用偏移量。

十页且每页大小不均的示例

一个针对 q=coffee、gl=us 和 hl=en 的采集,在所有十个请求偏移量上都返回了自然结果。在本样本中,每次请求都以 HTTP 200 成功完成。

start 返回的自然结果数量
0 9
10 9
20 9
30 9
40 10
50 10
60 10
70 9
80 10
90 10
总计 95

对返回的 link 字符串做严格相等比较后,得到 85 个不同值。这个计算不会跟踪重定向、比较 canonical 标签,也不会确定内容是否相同。两个不同的链接可以指向同一个页面;两个不同页面也可以共享同一个域名。无论是按主机名分组还是直接对原始字符串做比较,都不能证明目标页面覆盖是唯一的。

这个示例表明,在一次采集中配置的偏移量确实返回了数据。这并不保证每个查询都能暴露十个非空页面。在多次请求组成的采集过程中,搜索结果可能会发生变化。

构建一个有界的分页采集器

该采集器最多进行十次搜索提交,保存每个完成的响应,当发现自然结果数组为空或结果页面完全相同时会提前停止。它会把错误按错误记录下来,同时保留已采集到的数据。

前提条件是安装好 Python、Requests,并在环境中设置 SCRAPELESS_API_KEY。使用 python -m pip install requests 安装 Requests,把程序保存为 paginate_google.py,然后运行 python paginate_google.py。输出将写入 pagination-runs 下的新目录中。
请求助手同时处理已完成和待处理的任务。它对每次搜索只提交一次请求,并在必要时使用现有任务的结果端点。待处理任务工作流定义了这种区分;代码中的限制是本地策略选择。

python Copy
import json
import os
import time
from pathlib import Path
from urllib.parse import quote

import requests

BASE = "https://api.scrapeless.com/api/v1/scraper"


def google_search(query):
    headers = {"x-api-token": os.environ["SCRAPELESS_API_KEY"]}
    response = requests.post(
        BASE + "/request", headers=headers,
        json={"actor": "scraper.google.search", "input": query},
        timeout=(10, 60), allow_redirects=False,
    )
    task_id = None
    for poll in range(11):
        response.raise_for_status()
        if response.status_code not in (200, 201):
            raise RuntimeError(f"Unexpected HTTP status: {response.status_code}")
        data = response.json()
        if not isinstance(data, dict):
            raise ValueError("Expected a JSON object")
        if response.status_code == 200:
            return data
        if task_id is None:
            task_id = data.get("taskId")
        if not isinstance(task_id, str) or not task_id:
            raise ValueError("Pending response has no taskId")
        if poll == 10:
            raise TimeoutError(f"Task still pending; retain taskId={task_id}")
        time.sleep(2)
        response = requests.get(
            BASE + "/result/" + quote(task_id, safe=""),
            headers=headers, timeout=(10, 30), allow_redirects=False,
        )


def organic_rows(data):
    rows = data.get("organic_results")
    if not isinstance(rows, list):
        raise ValueError("organic_results is missing or is not an array")
    if not all(isinstance(row, dict) for row in rows):
        raise ValueError("organic_results contains a non-object item")
    return rows


if __name__ == "__main__":
    from datetime import datetime, timezone
    run_dir = Path("pagination-runs") / datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%fZ")
    run_dir.mkdir(parents=True)
    seen_links = set()
    seen_pages = set()
    collected = []
    summary = []
    stop_reason = "page_limit"
    try:
        for start in range(0, 100, 10):
            query = {"q": "coffee", "gl": "us", "hl": "en", "start": start}
            data = google_search(query)
            (run_dir / f"page-{start}.json").write_text(
                json.dumps({"input": query, "response": data}, ensure_ascii=False, indent=2),
                encoding="utf-8",
            )
            rows = organic_rows(data)
            signature = json.dumps(rows, sort_keys=True, ensure_ascii=False)
            repeat = bool(rows) and signature in seen_pages
            seen_pages.add(signature)
            new_count = 0
            for index, row in enumerate(rows, start=1):
                link = row.get("link")
                usable_link = isinstance(link, str) and bool(link.strip())
                if usable_link and link in seen_links:
                    continue
                if usable_link:
                    seen_links.add(link)
                collected.append({"start": start, "array_index": index, "result": row})
                new_count += 1
            summary.append({"start": start, "returned": len(rows), "kept": new_count})
            if not rows:
                stop_reason = "empty_organic_array"
                break
            if repeat:
                stop_reason = "identical_result_page"
                break
    except (requests.RequestException, ValueError, RuntimeError, TimeoutError) as exc:
        stop_reason = "error:" + type(exc).__name__
        raise
    finally:
        (run_dir / "collected.json").write_text(json.dumps(collected, ensure_ascii=False, indent=2), encoding="utf-8")
        report = {"pages": summary, "stop_reason": stop_reason, "kept_rows": len(collected)}
        (run_dir / "summary.json").write_text(json.dumps(report, indent=2), encoding="utf-8")
        print(json.dumps(report))

即使后续页面失败,finally 块仍然会写出摘要。失败的页面不会作为空页面被加入。之前保存的页面文件仍然可供检查,而抛出的异常依旧会让程序以可见的方式失败。

开始使用 Scrapeless 抓取数据

使用 Scrapeless 强化你的网页抓取和自动化工作流!
立即注册即可获得 $5 免费额度 —— 无需信用卡。

现在前往 Scrapeless 控制台 领取你的免费额度。

选择保守的去重规则

收集器会对非空的返回链接字符串做精确去重,并保留缺失链接的行。该策略易于审计,因为它不会重写 URL 组件。

URI 规范化模型 解释了为什么 URL 比较需要显式规则。盲目删除查询字符串、更改路径大小写或折叠斜杠变体,可能抹去有意义的差异。只有在验证相关目标网站之后,才增加更强的规范化。

所有原始页面记录都会保留在页面文件中,即便合并输出只保留重复链接的第一次出现。若要进行出现频次分析,请读取这些页面文件,而不是去重后的集合。否则你会丢失链接在多个偏移量出现的证据。

重复页面保护机制比较的是序列化后的结果记录。它检测的是完全重复的数据;它并不声称能识别每一个近似重复的 SERP。仍然需要一个有界的页面上限,因为字段中的小改动就可能让两个视觉上相似的响应在比较时不同。

解释空页面和部分运行

在此收集器中,空的 organic 数组是一个停止条件,而不是证明 Google 不再有关于该主题的索引页面。缺失的数组和格式错误的记录依旧被视为验证失败。

Stop Reason What the Collector Observed Safe Interpretation
page_limit 达到了配置的页面预算 采集在其配置的预算范围内是完整的
empty_organic_array 一个完成的响应没有任何 organic 记录 本次运行在该偏移量停止
identical_result_page organic 记录完全重复 后续采集被保护机制停止
error:... 某个请求或解析步骤失败 数据集是不完整的

通用的 HTTP 状态语义 有助于区分传输结果,而你的应用仍需记录采集是否完整。一个成功的首页响应并不能让后续失败的页面变得成功。

对于计划任务,为每次运行分配一个运行标识符,并保留时间戳、输入、偏移量和停止原因。这符合 数据溯源 的实际目的:后续使用者应当能够将派生数据集追溯到生成它的观测和转换过程。

结论:分别报告深度和覆盖率

分页报告应显示请求的偏移量、已完成页面、原始行数以及去重规则。这些度量回答的是不同问题,在代码和文案中都应保持区分。

在为更深的采集制定预算时,请使用 Google Search API 产品页面 了解服务细节,并查看当前定价。十页预算是一个采集设置,而不是承诺最终一定会得到一百个 URL。

构建你的搜索数据工作流

加入我们的社区,与使用搜索数据的开发者一起交流:Discord · Telegram。

创建一个 Scrapeless 账户,并在安排更大规模采集之前,先将本教程应用到一个较小的查询集上。

常见问题

问:start 应该按照返回行数递增吗?
不。请遵循网页搜索的偏移序列。包含九条自然结果的页面不会改变下一个已配置的偏移量。

问:十页的集合是否总是返回一百条结果?

不会。这个示例集合返回了 95 条自然结果。每个响应都必须单独测量页面大小和可用性。

问:85 个不同的链接字符串是否等同于 85 个唯一网页?

不是。对完全相同字符串的去重并不能验证重定向、规范化身份或页面内容。

问:是否应该将 HTTP 错误存储为一个空页面?

不应该。应单独存储失败并将本次运行标记为部分完成。一个空的 completed 数组有不同的含义。

问:pagination.next 是否需要直接从 Google 获取?

不需要。此客户端将请求保持在 Scrapeless 端点上,并提供已配置的 start 值。它不会直接获取 Google 的导航 URL。

问:采集器可以在没有 AI 代理的情况下运行吗?

可以。它是一个独立的 Python 程序,使用有界的顺序分页循环。

在Scrapeless,我们仅访问公开可用的数据,并严格遵循适用的法律、法规和网站隐私政策。本博客中的内容仅供演示之用,不涉及任何非法或侵权活动。我们对使用本博客或第三方链接中的信息不做任何保证,并免除所有责任。在进行任何抓取活动之前,请咨询您的法律顾问,并审查目标网站的服务条款或获取必要的许可。

最受欢迎的文章

目录