跳转到正文
中文
获取 API 密钥

Google 搜索 / Python

Google Search API:在 Python 中设置国家/地区、语言和分页

使用 gl、hl 和 location 请求本地化 Google 结果,安全分页,并使用 Python 保存返回的搜索设置。

FlashData · 发布于

围绕地球展示的本地化搜索结果及多个结果页面

Google 查询词只是搜索请求的一部分。研究伦敦和研究新加坡的人,可能需要同一组查询词返回不同的结果。本指南展示如何指定国家、界面语言和城市,然后获取少量结果页,且不会重复计算相同的 URL。

您将构建一个 Python 3 脚本,保存 API 返回的结果和搜索设置。如果这是您的首次请求,请先参考 将 Google 搜索结果导出为 CSV.

gl、hl 和 location 控制什么

  • gl 是双字母国家代码,例如 gb, us 或 sg.

  • hl 选择 Google 界面语言,例如 en 或 de。这并不保证每个返回的页面都以该语言撰写。

  • location 指定搜索地点。请使用明确的城市名称,例如 London, England, United Kingdom,适用于本地背景信息很重要的情况。

如需明确指定搜索配置,请组合使用这些参数。位置参数只是向搜索数据源提出的请求,并不保证结果与某个用户浏览器中的结果完全一致。搜索类型、查询、时间和可用数据都可能影响响应。请检查 results[0].searchParameters ,不要假定服务原样应用了每个参数值。

准备 API 密钥并规划请求预算

创建一个 API 密钥 ,并确保账户有可用积分。将密钥保存在环境变量中,不要提交到版本控制系统或放在浏览器 JavaScript 中。代码仅使用 Python 标准库。

bash
export FLASHDATA_API_KEY='your-api-key'
export SEARCH_QUERY='coworking spaces'
export SEARCH_COUNTRY='gb'
export SEARCH_LANGUAGE='en'
export SEARCH_LOCATION='London, England, United Kingdom'
export SEARCH_MAX_PAGES='3'

num 请求 1–100 条结果, page 接受 1–100。返回数量可能少于请求数量。每页都是单独计费的请求。此示例最多请求三页,遇到空页时停止,且不会自动重试提交失败的请求。

收集本地化结果并保留其上下文

将此内容保存为 localized-search.py。它会随每条结果记录所请求的页码,并保留原始的 position (如果返回了该字段),且仅移除完全相同的重复 URL。它有意不根据以下字段计算全局排名: (page - 1) × num:返回数量可能不同。

python
import json
import os
from pathlib import Path
from urllib.error import HTTPError
from urllib.request import Request, urlopen

key = os.environ["FLASHDATA_API_KEY"]
max_pages = int(os.getenv("SEARCH_MAX_PAGES", "3"))
if not 1 <= max_pages <= 100:
    raise ValueError("SEARCH_MAX_PAGES must be between 1 and 100")

query = os.getenv("SEARCH_QUERY", "coworking spaces")
settings = {
    "gl": os.getenv("SEARCH_COUNTRY", "gb"),
    "hl": os.getenv("SEARCH_LANGUAGE", "en"),
    "location": os.getenv("SEARCH_LOCATION", "London, England, United Kingdom"),
    "num": 10,
}
rows, pages, seen = [], [], set()
for page in range(1, max_pages + 1):
    payload = {"source": "google_search", "query": query,
               "params": {**settings, "page": page}}
    request = Request(
        "https://data.flashdata.dev/v1/queries/realtime",
        data=json.dumps(payload).encode(), method="POST",
        headers={"Content-Type": "application/json", "X-API-Key": key},
    )
    try:
        with urlopen(request, timeout=60) as response:
            body = json.load(response)
    except HTTPError as error:
        raise RuntimeError(f"Search failed: HTTP {error.code}. Check the request and account before resubmitting.") from error
    if body.get("error") or body.get("status") != "done":
        raise RuntimeError("Search did not complete. Check Request History before resubmitting.")
    if not isinstance(body.get("results"), list) or not body["results"]:
        raise RuntimeError("Expected a search result object")
    result = body["results"][0]
    organic = result.get("organic", [])
    pages.append({"requestedPage": page, "requestedParams": payload["params"],
                  "reportedParams": result.get("searchParameters"),
                  "returnedCount": len(organic), "usage": body.get("usage")})
    for item in organic:
        link = item.get("link")
        if link and link not in seen:
            seen.add(link)
            rows.append({"requestedPage": page, **item})
    if not organic:
        break

Path("localized-results.json").write_text(
    json.dumps({"query": query, "pages": pages, "organic": rows}, indent=2),
    encoding="utf-8",
)
print(f"Saved {len(rows)} unique URLs from {len(pages)} pages")
bash
python3 localized-search.py

比较不同市场前,先查看输出结果

JSON 文件包含一个 pages 条目,对应每个已完成的请求,以及一个 organic 数组,其中包含不重复的链接。保留 requestedParams 和 reportedParams,与你的数据一同保存。未返回的字段应保持缺失或 null;如果响应未报告国家或地点,不要自行填造相应值。

比较两个市场时,请保持查询和请求页数预算一致,并有意识地调整国家、语言和位置。如果需要进行历史比较,请在应用中记录采集时间。不同结果集只是这些请求的观测结果,并不能证明排名发生了永久变化。

为什么某一页的结果数量可能较少?

搜索结果除自然搜索链接外,还可能包含丰富的展示内容;数据源返回的自然搜索条目可能少于请求数量。请统计返回数组的长度。对于这个小脚本,遇到没有自然搜索结果的页面即可合理地停止;但这并不意味着 Google 没有其他相关页面。

遇到 401/403 错误时,请检查 API 密钥和权限。遇到积分或速率限制错误时,请先解决账户或请求速率问题。网络超时并不能证明付费请求从未执行;再次提交前,请检查请求历史记录。

继续阅读 Google Search API 参数参考, 异步与批量请求指南,或 Google Search 产品概览.