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 标准库。
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:返回数量可能不同。
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")
python3 localized-search.py
比较不同市场前,先查看输出结果
JSON 文件包含一个 pages 条目,对应每个已完成的请求,以及一个 organic 数组,其中包含不重复的链接。保留 requestedParams 和 reportedParams,与你的数据一同保存。未返回的字段应保持缺失或 null;如果响应未报告国家或地点,不要自行填造相应值。
比较两个市场时,请保持查询和请求页数预算一致,并有意识地调整国家、语言和位置。如果需要进行历史比较,请在应用中记录采集时间。不同结果集只是这些请求的观测结果,并不能证明排名发生了永久变化。
为什么某一页的结果数量可能较少?
搜索结果除自然搜索链接外,还可能包含丰富的展示内容;数据源返回的自然搜索条目可能少于请求数量。请统计返回数组的长度。对于这个小脚本,遇到没有自然搜索结果的页面即可合理地停止;但这并不意味着 Google 没有其他相关页面。
遇到 401/403 错误时,请检查 API 密钥和权限。遇到积分或速率限制错误时,请先解决账户或请求速率问题。网络超时并不能证明付费请求从未执行;再次提交前,请检查请求历史记录。
继续阅读 Google Search API 参数参考, 异步与批量请求指南,或 Google Search 产品概览.