gl vs hl vs location:Google 搜索 API 区域设置
Senior Web Scraping Engineer
摘要:
- gl、hl 和 location 描述的是不同的搜索输入。 请将国家、语言和搜索来源分开处理。
- 七个成功的国家请求仅证明返回了数据。 它们并不能用来推导城市级准确率的百分比。
- 有效的本地化测试一次只变更一个变量。 固定查询和其他设置,然后再比较输出。
- 请求的设置应与观察到的证据并列保存。 在有独立校验支持前,请将某个位置标记为“未验证”。
引言:国家代码只是搜索的一部分
搜索结果不仅取决于关键词。国家偏好、语言设置和本地来源都会提供上下文,并可能产生不同的效果。
本指南解释 Scrapeless Google Search API 中 gl、hl 和 location 之间的区别。它展示了一个七国请求矩阵,以及一个独立检查本地行为的方法。它不会把“非空响应”当作“某个特定城市已被准确表示”的证明。
Google 搜索参数约定 是可接受控制项的参考文档。Actor 请求工作流 在你把这些控制项放入 input 内部并进行修改时依然保持不变。
各参数分别控制什么
gl 参数用来选择搜索国家,hl 用来选择搜索语言,而 location 用来指定请求的搜索来源。这些输入应在采集记录中分别存储。
| Parameter | Example | What Not to Infer |
|---|---|---|
gl |
us |
每一条结果都一定属于美国机构 |
hl |
en |
每个目标页面都一定是英文 |
location |
Austin, Texas, United States |
每条本地结果都已经被独立做过地理编码 |
google_domain |
google.com |
仅凭域名就足以确定城市级准确性 |
请使用 API 接受的取值,而不是通过无关的本地化库自动翻译标签。例如,目前的参考文档为联合王国使用 uk。通用的语言或地区标准与特定 API 所接受的取值并不总是完全一致。
语言标签标准 说明了语言标识如何可以包含多个子标签,但它并不会扩展 hl 所接受的取值。同样,Unicode 本地化约定 有助于描述 locale 数据,但不会替代某个服务的参数约定。
将国家偏好与语言限制区分开来
搜索语言输入不应被理解为“每一份结果文档都使用该语言”的保证。语言设置、对文档语言的限制以及用某种语言撰写的查询,是三类不同的控制项。
Google 在 语言如何影响搜索结果 的说明中,把语言影响视为涉及多种信号。在你的实验中,请记录查询所使用的语言以及 hl。用英文写的查询与翻译成日文的查询是两组不同的实验,即使其他输入保持一致。
避免在对比中同时翻译查询并更改国家和城市。如果结果发生差异,你将无法判断是哪一项有意变更的输入导致了这种差异。先隔离单一变量;再测试你的应用程序所需的完整配置。
七国可用性示例
针对 coffee 发起的七个请求,在都使用 hl=en 的前提下,仅通过更改 gl 所对应的国家,就得到了非空的 organic 数组。每个请求都以 HTTP 200 完成。
| Country | gl | hl | Returned Organic Records |
|---|---|---|---|
| United States | us | en | 8 |
| United Kingdom | uk | en | 9 |
| Germany | de | en | 9 |
| France | fr | en | 10 |
| Japan | jp | en | 10 |
| Canada | ca | en | 9 |
| Australia | au | en | 9 |
这些计数表明:在这些配置请求下,数据得到了返回。它们并不能衡量国家准确度、语言准确度或城市准确度。这些请求在 location 中未包含城市,而且返回的目标站点也未被赋予独立的地理真值。
不同的计数也不能证明是地理位置导致了差异。每次调用都是一次独立的搜索快照。要做出因果或准确性的结论,受控研究需要重复观察和预先定义的度量方式。
使用 Scrapeless 开始抓取
使用 Scrapeless 提升你的网页抓取和自动化工作流!
立即注册即可获得 $5 免费额度 —— 无需信用卡。现在就在 Scrapeless 控制台 领取你的免费额度。
保存可复现的国家矩阵
下面的程序为每个国家保留完全相同的输入和完整响应,并明确标记位置验证为未完成。这样可以避免把一次成功的网络请求错误地转化为不受支持的准确性评分。
前提条件是安装 Python、Requests,并在环境中设置 SCRAPELESS_API_KEY。使用 python -m pip install requests 安装 Requests,将程序保存为 country_matrix.py,并运行 python country_matrix.py。每次运行都会在 country-runs 下创建一个单独的目录。
该辅助工具通过已文档化的结果工作流 处理挂起任务。循环是顺序执行的,因此示例不对账号的并发限制做任何假设。
python
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__":
from datetime import datetime, timezone
run_dir = Path("country-runs") / datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%fZ")
run_dir.mkdir(parents=True)
summary = []
for country in ("us", "uk", "de", "fr", "jp", "ca", "au"):
query = {"q": "coffee", "gl": country, "hl": "en"}
data = google_search(query)
(run_dir / f"{country}.json").write_text(json.dumps({"input": query, "response": data}, ensure_ascii=False, indent=2), encoding="utf-8")
rows = organic_rows(data)
summary.append({"gl": country, "hl": "en", "rows": len(rows), "location_verified": False})
(run_dir / "summary.json").write_text(json.dumps(summary, indent=2), encoding="utf-8")
print(json.dumps(summary))
即使返回了数据,代码也会让 location_verified 保持为 false。该字段是应用层的决策,而不是 API 响应中声称存在的字段。只有在完成你定义的独立验证之后,才应修改它。
独立验证城市
城市级验证应将请求的来源与返回页面中的位置证据以及独立基线进行比较。仅仅存在非空的自然搜索结果,并不能证明这种匹配关系。
从一个具有本地意图的公开查询开始,例如 coffee shops。保持 q、gl、hl、搜索模式以及其他过滤条件不变。使用一个完全指定的奥斯汀位置发起请求,再用一个完全指定的西雅图位置发起请求。API 的端点指南 推荐使用城市级位置,并将 location 和 uule 视为互斥。
针对这两个城市名称的准备请求各自返回了 9 条自然结果记录。这证明在配置好的输入条件下有可用数据,但并不能证明可见搜索位置或每条结果都与目标城市相匹配。
在收集更大样本之前,先定义你的验证表。实用的列包括请求城市、可见位置证据、在可用情况下的本地商家地址样本、独立基线方法、观察时间和审核结论。在存在 metadata.rawUrl 时将其保存下来,以便后续检查页面。
使用具备明确设置说明的人工基线,或一种独立且可信的度量方式。审核者应检查证据本身,而不是仅通过国家代码域名来推断位置。全国性媒体可以出现在本地搜索中,本地商家也可能使用通用域名。
将结果标记为确认、冲突或证据不足。不要把不确定的观察硬塞进“通过”类别里。若要公布准确率百分比,应在查看结果之前先定义分母和裁决规则。
保持持续对比的可比性
本地化数据集需要稳定的输入和可见的采集上下文。即使响应中包含自己的元数据,也要保存请求设置;这两部分信息回答的是不同的问题。
精确记录查询、请求的国家和语言、任何位置字符串、搜索模式、采集时间以及响应结果。将仅限国家的基线与特定城市的实验区分开来。不要把桌面网页搜索结果与 Local 模式结果进行比较,并假定只有城市发生了变化。
在生产工作流中,应预先决定当位置证据缺失时该怎么处理。将该条观察保留待审,比把它当作已验证的城市快照展示更有价值。使用当前定价 为重复观察和独立检查分别做预算。
结论:验证你声称的位置
国家、语言和城市输入让搜索采集更具目的性,但最强有力的位置结论必须与证据相符。先从一个小的配置矩阵开始,保留响应,并在构建城市级报表之前验证目标地理位置。
Google 搜索 API 产品页面 介绍了该服务;参数约定决定了实现方式。将一次成功响应视为验证的起点,而不是终点。
构建你的搜索数据工作流
加入在社区中使用搜索数据的开发者: Discord · Telegram。
创建一个 Scrapeless 账号,先在一个小规模查询集合上应用本教程,再去计划更大规模的数据采集。
常见问题
问:gl 和 hl 可以互换吗?
不能。gl 选择搜索国家,hl 选择搜索语言。请分别存储并单独测试它们。
问:hl=en 会把所有结果都限制为英文吗?
不要把它当作对每个结果文档的保证。搜索语言设置与文档语言限制是不同的概念。
问:location 和 uule 可以同时提供吗?
不能。当前的参数约定使它们互斥。请选择与你的配置相匹配的受支持控制项。
问:七个非空的国家响应能证明七个国家都准确吗?
不能。它们只表明针对七个请求配置返回了数据。准确性需要独立检查的位置信息证据。
问:仅凭国家代码域名足以证明本地相关性吗?
不能。仅靠域名命名无法确定页面的地理位置或 SERP 所代表的来源。
问:示例是否需要浏览器或 AI 代理?
不需要。它使用的是 Python 和 HTTP API。独立的可视化验证可能会用到浏览器,但那是一个单独的验证步骤。
在Scrapeless,我们仅访问公开可用的数据,并严格遵循适用的法律、法规和网站隐私政策。本博客中的内容仅供演示之用,不涉及任何非法或侵权活动。我们对使用本博客或第三方链接中的信息不做任何保证,并免除所有责任。在进行任何抓取活动之前,请咨询您的法律顾问,并审查目标网站的服务条款或获取必要的许可。



