Google 搜索 API：从搜索查询到结构化 JSON

Emily Chen

Advanced Data Extraction Specialist

09-Sep-2026

TL;DR:

无废品的 Google 搜索 API 以结构化 JSON 的形式返回搜索结果。 在研究工具、SEO 报告和源发现工作流程中使用自然结果字段。
搜索上下文与结果密切相关。 将查询、国家、语言和观察时间放在一起，以便后续比较具有明确的意义。
待处理任务与空结果集不同。 在尝试读取 organic_results 或创建 CSV 之前，请单独处理 HTTP 201。

当团队能够将每个结果与产生该结果的问题和市场连接时，Google 搜索数据就变得有用。复制到电子表格中的标题和 URL 丧失了许多上下文。结构化响应使应用程序从一开始就能够保留这些信息。

更新后的无废品 Google 搜索 API 提供了一条从搜索查询到 JSON 的管理路径。您的应用程序发送请求，并决定如何使用返回的数据。代理和 CAPTCHA 处理在服务端运行，减少了您的团队需要维护的采集基础设施。

本指南遵循该交接：选择搜索上下文，提交请求，读取响应，并保存另一个人可以理解的数据集。

Google 搜索 API 返回的内容

Google 搜索 API 返回结构化搜索数据，当存在时，自然结果可在顶级 organic_results 数组中找到。自然结果可以包括 position、title、link 和 snippet。响应还可以包含分页信息和其他搜索模块，具体取决于查询和返回的结果。

在提取子集之前，请保留原始响应。扁平表格便于分析，但无法在没有故意映射的情况下表示每个嵌套对象。JSON 数据模型 区分数组、对象、字符串、数字、布尔值和 null；保留这些区别可以使后续处理更加容易。

片段是搜索结果的摘录。它不提供目标页面的完整内容。如果研究应用需要文章的证据，应用程序必须单独获取和审查该页面。

准备一个小的首次请求

首次请求需要一个无废品 API 密钥、一个查询和一个能够通过 HTTP 发送 JSON 的客户端。使用可以访问 Google 搜索 API 的帐户，并将密钥保存在 SCRAPELESS_API_KEY 环境变量中。

在下面的 Python 示例中，在您的项目环境中安装 requests 包。其余模块来自 Python 的标准库。将脚本保存为 google_search_export.py，然后在通过本地 shell 或密钥管理器设置环境变量后，用 python3 google_search_export.py 运行它。

该示例使用中立的查询 coffee、国家 us 和语言 en。在引入关键字列表或计划作业之前，请先使用此小输入。首先检查响应的形状；下游数据模型依赖于此。

经过认证的请求是需要您自己帐户密钥的前提条件。该示例的请求形状遵循当前 API 参考；没有以捕获的实时帐户运行的形式呈现。

选择国家、语言和输入模式

国家、语言和位置描述搜索请求的不同部分。gl 选择搜索国家，hl 选择搜索语言，location 指定搜索应该从何处发起。google_domain 选择 Google 域名。当前设备选项支持桌面。

Google 搜索 API 参数模型还有两个输入规则，影响您构造请求的方式：

使用 q 作为通过单个参数表达的查询。或者，提供完整的 Google 搜索 url；当提供 url 时，其他输入参数将被忽略。
选择 location 或 uule。这两者不能一起使用。

为了跨市场进行比较，请保存每个响应的完整输入对象。设置相同的国家和语言使预期上下文明确，但不能保证在观察之间结果相同，也不能重现特定人员的登录搜索历史。
查询可以包括操作符，例如 site:、inurl: 和 intitle:。使用它们来缩小研究问题。 站点限制搜索 并不是索引页面的完整清单，因此其结果不应成为确切的索引覆盖计数。

请求 JSON 和导出自然结果

请求使用 POST https://api.scrapeless.com/api/v1/scraper/request、scraper.google.search 参与者和 x-api-token 头。该脚本在 HTTP 200 后保存响应及其输入和接收时间，然后将自然结果导出为 CSV。

注意：网络请求需要您的 Scrapeless API 密钥，并且未使用此文章的实时帐户执行。该脚本保留了 HTTP 201 任务响应以供检查；它不实现任务结果的检索。

python Copy

import csv
import json
import os
from datetime import datetime, timezone
from pathlib import Path

import requests


def spreadsheet_text(value):
    text = "" if value is None else str(value)
    if text.lstrip().startswith(("=", "+", "-", "@")) or text.startswith(("\t", "\r")):
        return "'" + text
    return text


def export_results(payload, context, received_at, output_path):
    results = payload.get("organic_results")
    if not isinstance(results, list):
        print("No usable organic_results array; inspect the saved JSON.")
        return
    fields = ["q", "gl", "hl", "received_at", "position", "title", "link", "snippet"]
    with output_path.open("w", encoding="utf-8", newline="") as stream:
        writer = csv.DictWriter(stream, fieldnames=fields)
        writer.writeheader()
        for item in results:
            if not isinstance(item, dict):
                raise ValueError("Unexpected organic result item; inspect the saved JSON.")
            row = {name: item.get(name) for name in ("position", "title", "link", "snippet")}
            row.update(context, received_at=received_at)
            writer.writerow({name: spreadsheet_text(row.get(name)) for name in fields})
    print(f"Exported {len(results)} organic results to {output_path}")


def main():
    context = {"q": "coffee", "gl": "us", "hl": "en"}
    response = requests.post(
        "https://api.scrapeless.com/api/v1/scraper/request",
        headers={"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
        json={"actor": "scraper.google.search", "input": context},
        timeout=120,
    )
    response.raise_for_status()
    received_at = datetime.now(timezone.utc).isoformat()
    run_id = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%fZ")
    payload = response.json()
    record = {"input": context, "received_at": received_at,
              "http_status": response.status_code, "response": payload}
    output = Path(f"google-search-{run_id}.json")
    output.write_text(json.dumps(record, ensure_ascii=False, indent=2), encoding="utf-8")
    if response.status_code == 201:
        print(f"Task pending. Inspect taskId in {output}; no CSV was created.")
        return
    if response.status_code != 200 or not isinstance(payload, dict):
        raise ValueError(f"Unexpected response; inspect {output}")
    export_results(payload, context, received_at, output.with_suffix(".csv"))


if __name__ == "__main__":
    main()