Loading Light/Dark Toggle
返回博客

Google 搜索 API Python 教程:请求与结果

Alex Johnson
Alex Johnson

Senior Web Scraping Engineer

12-Nov-2026

摘要:

  • Scrapeless Google Search API 将结构化搜索数据返回给 Python。 在已认证的 JSON 请求中提交 q、gl 和 hl。
  • HTTP 200 和 HTTP 201 需要不同的处理方式。 已完成的结果可直接读取;对于仍在处理的任务,保留任务 ID 并检索该已有任务。
  • 成功的 HTTP 响应仍然需要数据检查。 在使用这些行之前验证 organic_results。
  • 保留响应可简化后续分析。 在筛选标题、摘要或链接前先保存 JSON。

介绍:让搜索结果在 Python 中可用

只有当应用程序能区分已完成的数据和仍在运行的任务时,搜索请求对应用程序才有用。一个快速打印 response.text 的脚本可以帮助你起步,但它会把这些状态混在一起。

本 Google Search API Python 教程构建了一个简单客户端,用于调用 Scrapeless Google Search API。你将配置查询、提交请求、处理挂起任务,并保存一个供其他脚本检查的响应。示例使用普通网页搜索。图片、本地、视频和购物有不同的结果部分,需要各自的验证方式。

代码与 Scrapeless 通信;它不是 Google 的 Custom Search JSON API 或 Search Console API。你的应用程序收到的是一次搜索快照,而不是你网站的流量报告。如果你已经使用更通用的 Scrapeless actor 请求模型,那么这个请求封装会很熟悉。

前提条件

你需要 Python、requests 包,以及具有该服务访问权限的 Scrapeless API 密钥。为该项目使用虚拟环境,并通过 python -m pip install requests 安装 Requests。在运行脚本前,在进程环境中设置 SCRAPELESS_API_KEY。不要把密钥放进源码文件、你分享的笔记本或响应日志中。

本地环境变量是为这个脚本选择的一种约定。HTTP 认证头是 x-api-token。它们的职责不同:Python 读取环境变量,然后将其值放入请求头发送到 API 端点。

将下面完整的程序保存为 google_search.py,并用 python google_search.py 运行它。该程序会在工作目录中创建 serp.json。如果你想保留之前的响应,请为每次实验使用单独的目录。

配置 q、gl 和 hl

q 参数提供搜索查询,gl 选择搜索国家,而 hl 选择搜索语言。这些控制项属于 input 内部,与外围请求对象中的 actor 名称并列。

字段 示例 需要检查什么
actor scraper.google.search 将 actor 保持在顶层
input.q coffee 保留你打算比较的精确查询
input.gl us 将请求的国家与结果一起记录
input.hl en 单独记录请求的语言

从这个小输入开始。立即添加位置和搜索过滤器会让你更难判断是哪一个参数改变了输出。在扩展请求时,请随手查阅 当前的 Google Search 参数。

通过 Requests 的 json= 参数发送请求体。它会将 Python 对象序列化为 JSON,并设置合适的内容类型。JSON 对象和数组在 JSON 数据格式 中是不同的结构;一个能成功解析的响应并不一定就是你的应用程序所期望的对象形状。

发送请求并获取挂起任务

客户端提交一个搜索任务,然后仅在该任务仍在处理中时检查结果端点。已完成的响应会以 Python 字典的形式返回给调用方。

Google Search 快速入门 使用 POST /api/v1/scraper/request。对于此 API,HTTP 201 表示处理正在进行中,并包含 taskId。任务结果工作流 通过 GET /api/v1/scraper/result/{taskId} 获取该 ID。
这是对状态码的特定于应用程序的解释。通用的 HTTP 语义规范 定义了状态类别,而服务契约则告诉你的客户端如何处理处于等待中的任务。

程序将结果检查限制为最多十次,每次间隔两秒。这些是示例客户端设置,而不是服务限制或承诺的完成时间。网络超时单独适用于每个请求。如果任务仍处于等待状态,则异常会包含其 ID,以便运维人员可以保留它。

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__":
    query = {"q": "coffee", "gl": "us", "hl": "en"}
    try:
        result = google_search(query)
        Path("serp.json").write_text(
            json.dumps(result, ensure_ascii=False, indent=2), encoding="utf-8"
        )
        rows = organic_rows(result)
        print(f"Saved serp.json; organic rows: {len(rows)}")
        for row in rows:
            print(row.get("position"), row.get("title"), row.get("link"))
    except requests.HTTPError as exc:
        raise SystemExit(f"HTTP request failed: {exc.response.status_code}")
    except requests.RequestException:
        raise SystemExit("Network request did not complete")
    except (ValueError, RuntimeError, TimeoutError, KeyError) as exc:
        raise SystemExit(str(exc))

第一个 raise_for_status() 捕获 HTTP 错误响应。显式的状态检查也会拒绝意外的非错误状态。解析 JSON 在这些检查之后进行,而结果验证器会在 API 表示任务已完成后运行。每个阶段都在回答不同的问题。

使用 Scrapeless 开始抓取

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

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

在不丢失原始响应的前提下读取 organic_results

在已完成的响应中,organic_results 数组包含自然结果记录。从每条记录中读取 position、title、snippet 和 link 等字段,同时保留原始对象以供检查。

在编写本教程时使用的基础 coffee 请求返回了 HTTP 200,以及包含 gl=us 和 hl=en 的八条自然结果记录。这个数量描述的是一次响应。后续针对同一查询的请求中,行数或搜索功能的排列都可能不同。

程序在验证自然结果数组之前先保存 JSON。当已完成的响应具有意外结构时,这一点非常重要:你可以检查实际收到的内容,而不是在验证引发异常时丢失它。Python 的 JSON 编码和解码接口 支持通过 ensure_ascii=False 保持非 ASCII 文本的可读性。

将三种情况分开处理。空数组是一个已观测的集合,只是没有自然结果项。缺失键则没有这样的保证。错误类型的值则是模式(schema)问题。脚本接受第一种情况,而在后两种情况下直接停止,而不是悄悄用空列表替代。

返回的链接也需要上下文。看起来是直接的 URL 可以作为目标候选;Google 的中转链接在将其视作目标网站之前需要进一步处理。本篇入门教程只打印返回的值,而不声称已验证最终目标地址。

在正确的层次处理失败

异常应当标明失败的阶段,同时不暴露认证头部,也不要把失败的请求伪装成看起来有效的空结果。

观察 对该客户端的含义 下一步检查
缺少环境变量 本地未配置认证信息 检查进程环境
HTTP 400 API 拒绝了该请求 检查输入的名称、类型和组合
HTTP 429 服务报告请求受限 检查请求频率和账号配额
其他 HTTP 错误 未接受任何已完成结果 保留状态和请求上下文以便调查
无效 JSON 无法解析响应体 在受控诊断日志中检查响应
缺少自然结果数组 负载与该消费方的预期不符 检查保存的 JSON 和请求的搜索模式
达到等待任务上限 此客户端未观测到完成 保留任务 ID 并将作业标记为未完成

示例代码刻意避免打印完整的请求头或服务器错误正文。在更大的服务中,应使用结构化诊断日志记录查询配置、状态以及可用时的任务 ID。将失败的运行与已完成的观测分开记录,以免下游报表把失败误认为缺失。

结论:让第一个客户端保持小而清晰

一个实用的 Google 搜索 API Python 客户端有一条清晰路径:提交查询、在必要时检索已有任务、保留响应,并验证你的应用实际消费的字段。一旦这条路径运转良好,再一次只增加一个输入维度。
使用 Google Search API 产品详情 来选择服务,并参考当前定价来规划重复采集。在构建更大的数据集之前,将每次保存的响应与其请求配置一并保留。

构建你的搜索数据工作流

加入使用搜索数据进行开发的社区: Discord · Telegram。

创建一个 Scrapeless 账号,先在一个小规模查询集上实践本教程,再计划更大规模的采集任务。

常见问题

问:Python 在没有 SDK 的情况下可以调用 Google Search API 吗?

可以。示例使用 Requests 和文档中的 HTTP 端点。不需要 AI agent 或特定框架的 SDK。

问:HTTP 201 是否包含最终搜索结果?

对于这个 API,HTTP 201 表示任务仍在处理中。保留 taskId 并通过结果端点检索该任务。

问:gl=us 能证明每个结果都来自美国吗?

不能。国家是搜索输入参数,而不是每个返回页面的国籍标签。本地化精度需要单独的验证方法。

问:缺失的 organic_results 键是否应当变成空列表?

不应。当键缺失与显式为空数组是不同的观测现象。在报告“没有返回自然结果记录”之前,应先检查响应结构。

问:需要配置单独的代理吗?

这个基础请求不需要单独的代理配置。API 会处理检索;在添加传输或地理位置设置前,请先查阅参数约定。

问:脚本会验证每个结果链接背后的内容吗?

不会。它只收集一次搜索快照。目标验证和页面内容校验是后续的独立步骤。

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

最受欢迎的文章

目录