Loading Light/Dark Toggle
返回博客

Google 搜索 API JSON 响应:organic_results 详解

Alex Johnson
Alex Johnson

Senior Web Scraping Engineer

12-Nov-2026

摘要:

  • organic_results 是有机搜索记录的集合。 读取每条记录的返回位置、标题、摘要和链接时,不要与其他搜索模块混在一起。
  • 返回位置和值在数组中的顺序是两个独立的数值。 在准备数据集时要同时保留这两者。
  • 返回的链接并不自动等同于已验证的最终 URL。 要把中间状态和候选目标状态区分开来。
  • 缺失字段必须保持可见。 没有摘要、空字符串和格式错误的记录需要不同的处理方式。

引言:在扁平化之前先阅读响应

Google 搜索 API 的 JSON 响应中,除了有机结果外,还可能包含知识面板、本地模块、相关问题以及其他依赖查询的模块。把每个包含 title 字段的对象都扁平化,会得到一个语义混合的数据集。

本教程聚焦于 Scrapeless Google Search API 中的 organic_results。目标是针对标题、摘要、位置和链接构建一种精简、易检查的记录格式。它既不会实现一个排名追踪器,也不会声称每个返回链接都已与最终目标 URL 进行过核对。

Google 搜索响应示例 和 actor 请求工作流 提供了外围的请求上下文。在这里,有用的工作从完整响应被保存之后才开始。

organic_results 包含什么

organic_results 字段是一个有机结果对象数组,其中各字段的可用性需要在每个条目上单独检查。一条记录并不是目标页面的完整拷贝。

Field 数据集中的含义 处理规则
position API 返回的位置 原样保留,不要重新计算
title 结果标题 保持 null 或缺失值与文本可区分
snippet 搜索结果摘要 将其视作搜索观察,而不是完整页面内容
link 返回的结果 URL 在下游目标匹配前先进行分类
redirect_link 存在时的额外重定向形式链接 单独存储;不要自动替换 link
source 可用时显示的来源标签 不要假定它是可注册域名

该表描述的是应检查的字段,而不是保证每个条目都包含每个键。参数参考 定义了请求控制;它不应被解读为不同查询之间结果模块完全一致的承诺。

JSON 允许的值包括 null、字符串和数组,如 JSON 规范 所述。灵活的响应格式仍然需要一个有意设计的消费契约。决定你的应用可以保留哪些缺失值,以及哪些缺失值应当终止处理。

在不发明“排名”的前提下保留位置

在合并多页结果时,将返回的 position、数组索引以及请求偏移量作为三个独立字段保留。每个值都在描述观察的不同部分。

数组索引记录条目在返回数组中的位置;返回位置是 API 提供的数值;请求偏移量记录你请求的是第几页。在没有先确定位置语义的情况下就把偏移量加到位置上,可能会导致偏移量被重复计算,或者暗示响应中并未声明的排名。

不要在一个统一序列中同时统计广告、知识图谱和有机记录,除非你已经定义并验证了这种自定义度量。需要有机排名的开发者应保留足够上下文,以检查生成该记录的搜索页面。

即使数据库只需要少数字段,也要保存未经修改的 JSON。你之后可能会需要最初归一化脚本丢弃的某个字段,或者需要区分缺失字段与由你自己的转换引入的值。

在解析链接之前先对它们分类

URL 分类是为进一步验证做的路由决策;它并不是最终目标的证明。coffee 的基线响应在同一条有机记录中同时包含了直接的 link 值和独立的 Google redirect_link 值。
检查 scheme、hostname 和 path,而不是仅仅测试字符串是否包含单词 Google。URI 组件模型将这些部分明确分离。URL 的 path 中出现熟悉的品牌名称,并不意味着该 URL 一定由该品牌托管。

有用的分类包括:缺失值、相对链接、已观察到的 Google 中介,以及绝对 URL 候选项。在 /goto?url=... 链接中保留不透明值。不透明参数不是你可以通过猜测解码方案来恢复的目标地址。

开始使用 Scrapeless 进行抓取

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

现在就在 Scrapeless 控制面板 领取你的免费额度。

规范化已保存的 JSON 响应

下面的程序在不访问任何结果 URL 的情况下创建规范化记录。它保留两个链接字段,并附加本地分类以供后续审查。

先决条件是 Python,以及保存为 serp.json 的已完成 Google 搜索响应。保存 API 的响应对象本身,而不是包含日志元数据的自定义封装。快速开始请求提供了该响应。将脚本保存为 normalize_organic.py,并在 JSON 文件旁运行 python normalize_organic.py。

示例中设置的主机名覆盖了此响应系列中观察到的 Google 主机。它有意不作为所有 Google 域名的全局注册表。仅在你的实际响应证明有必要时再扩展它。其他绝对 URL 仍然是未经验证的候选项。

python Copy
import json
from pathlib import Path
from urllib.parse import urlsplit


def classify_link(value):
    if not isinstance(value, str) or not value.strip():
        return "missing"
    if value.startswith("/"):
        return "relative_review"
    try:
        parts = urlsplit(value)
        host = (parts.hostname or "").lower()
    except ValueError:
        return "invalid_review"
    if parts.scheme not in ("https", "http") or not host:
        return "invalid_review"
    # These are observed Google hosts, not a global Google-domain registry.
    google_hosts = {"google.com", "www.google.com"}
    if host in google_hosts and parts.path in ("/url", "/goto"):
        return "google_intermediary"
    if host in google_hosts:
        return "google_page_review"
    return "absolute_candidate"


data = json.loads(Path("serp.json").read_text(encoding="utf-8"))
if not isinstance(data, dict) or not isinstance(data.get("organic_results"), list):
    raise ValueError("Expected an object with an organic_results array")
normalized = []
for index, row in enumerate(data["organic_results"], start=1):
    if not isinstance(row, dict):
        raise ValueError(f"Invalid result at index {index}")
    normalized.append({
        "array_index": index,
        "returned_position": row.get("position"),
        "title": row.get("title"),
        "snippet": row.get("snippet"),
        "link": row.get("link"),
        "redirect_link": row.get("redirect_link"),
        "link_state": classify_link(row.get("link")),
    })
Path("organic-normalized.json").write_text(
    json.dumps(normalized, ensure_ascii=False, indent=2), encoding="utf-8"
)
counts = {}
for row in normalized:
    state = row["link_state"]
    counts[state] = counts.get(state, 0) + 1
print(json.dumps({"rows": len(normalized), "link_states": counts}))

Python 的 URL 解析函数会分离各个组件,但仅有解析并不能验证信任或网络可达性。因此脚本中的 absolute_candidate 状态只精确表示:存在一个带有主机名的绝对 HTTP URL。

决定何时需要最终 URL

当你的结论依赖于目标页面的身份时,就有必要进行最终 URL 验证。关键词发现可以保留候选链接,供之后检查;目标域排名、归因和引文交付则需要更强的证据。

下游任务 返回的链接可以支持的内容 额外工作
主题发现 片段旁边的候选来源 在依赖其论断之前审查该页面
搜索响应审计 API 返回的链接文本 在需要时保留原始响应和 HTML
域匹配 初步候选分类 解析并验证目标域名
已验证引文 候选参考文献 检查最终 URL、可访问内容及其对论断的支持

如果你构建一个目标解析器,请将原始 URL 和最终 URL 保持为不同的列。记录重定向链和解析结果。不要将 Scrapeless 的 API 密钥发送到结果网站,也不要将网络失败视为页面不存在的证据。

避免不加区分地剥离查询参数。有些参数是页面身份的一部分。即便是删除结尾斜杠,也可能会合并在源站被区别对待的 URL。从保守的比较规则开始,然后记录你的数据集所采用的任何规范化策略。

诊断缺失或意外字段

字段质量报告应展示实际到达的数据,而不是悄悄制造替代值。将非空字符串与仅存在键但无内容的情况分开计数。

对于 snippet,要区分缺失的键、null 值、空字符串和非空文本。这些状态会影响某行是否能支持文本分析。如果缺少摘要片段但标题仍对你的任务有用,可以保留该行,但要标记缺失内容,以便分析人员理解其局限性。

在采集层面,缺失的 organic 数组不等同于空的 organic 数组。对于类型错误的条目,严格的消费端应停止处理,或将其记录在拒绝报告中。无论哪种选择,都不应在不告知的情况下提高成功率指标。

结论:保持每个字段的含义

一个可靠的 Google 搜索 API JSON 响应解析器会保留来源字段,只添加自己能够解释的转换。位置、数组顺序和 URL 状态应保持可见,而不被支持的目标假设则应排除在记录之外。
从 Scrapeless Google Search API 开始,根据当前定价选择采集频率,并在确定数据库 schema 之前验证少量已保存的响应。

构建你的搜索数据工作流

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

创建一个 Scrapeless 账号,并在计划大规模采集之前,将本教程应用在一个小规模查询集上。

常见问题

问:organic_results 是否包含 SERP 上所有可见的区块?

不会。其他搜索功能可能会出现在单独的响应字段中。organic 数组的解析器不应悄悄吞并这些模块。

问:position 和条目的数组索引是同一个东西吗?

不要假设它们可以互换。务必分别保留返回的 position 和数组索引,尤其是在处理分页请求时。

问:redirect_link 是否应该替代 link?

不会。当二者都存在时要同时保留。根据目标 URL 的实际状态和下游任务,选择合适的目标处理策略。

问:经过编码的 Google 链接能否被当作解码后的目标地址?

不能。要保留这些不透明值,并在需要确定最终目标身份时使用经过验证的解析流程。

问:非空 snippet 能否证明摘要是准确的?

不能。非空文本只说明字段是可用的。准确性和论断支撑需要检查源内容。

问:归一化是否需要一个 AI 代理或独立代理服务?

不需要。这个归一化脚本只对已保存的 JSON 进行处理,不会发起任何网络请求。

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

最受欢迎的文章

目录