Google SERP API 分页:使用 start 收集结果
Senior Web Scraping Engineer
摘要:
- 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
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,我们仅访问公开可用的数据,并严格遵循适用的法律、法规和网站隐私政策。本博客中的内容仅供演示之用,不涉及任何非法或侵权活动。我们对使用本博客或第三方链接中的信息不做任何保证,并免除所有责任。在进行任何抓取活动之前,请咨询您的法律顾问,并审查目标网站的服务条款或获取必要的许可。



