gl vs hl vs location: Google 検索 API のロケール設定
Senior Web Scraping Engineer
要約:
- gl、hl、location は異なる検索入力を表します。 国、言語、検索発信元は分けて管理します。
- 7件の国別リクエストはデータが返ることを示すだけです。 都市レベルの精度パーセンテージを示してはいません。
- 有用なローカライズテストでは、一度に変える変数は1つだけです。 クエリと他の設定を固定してから出力を比較します。
- 要求した設定は観測された証拠のそばに記録します。 独立した検証が得られるまでは、そのロケーションは未検証として扱います。
はじめに:国コードは検索の一部にすぎない
検索結果はキーワードだけで決まりません。国のプリファレンス、言語設定、ローカルな発信元がそれぞれコンテキストを与え、異なる効果を生むことがあります。
本ガイドでは、Scrapeless Google Search API における gl、hl、location の違いを説明します。7か国に対するリクエスト行列と、ローカル挙動を独立して確認する方法を示します。非空レスポンスが、特定都市が正確に反映された証拠であるとはみなしません。
Google Search パラメータ契約は、受け付けられる制御項目のリファレンスです。アクターのリクエストワークフローは、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 ロケール規約はロケールデータの記述に役立ちますが、サービスのパラメータ契約の代わりにはなりません。
国のプリファレンスと言語制限は分けて考える
検索言語入力は、「すべての結果ドキュメントがその言語で記述される」という保証として解釈すべきではありません。言語設定、ドキュメント言語の制限、特定の言語で書かれたクエリは、それぞれ別個の制御です。
Google は、言語が検索結果に与える影響を複数のシグナルが関与するものとして説明しています。実験では、hl と同時にクエリ言語も記録してください。英語で書かれたクエリと、日本語に翻訳されたクエリは、他の入力が同じでも別々の実験です。
クエリを翻訳すると同時に、同一比較内で国と都市も変更することは避けてください。結果が異なっても、どの意図的な入力変更が差異に寄与したのか分からなくなります。まずは単一の変数を分離し、そのうえでアプリケーションが必要とする完全な構成をテストします。
7か国での利用可能性の例
hl=en を使用した coffee に対する 7件のリクエストでは、gl を下記の各国にわたって変更したところ、いずれもオーガニック配列が空ではありませんでした。各リクエストは 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、検索モード、その他のフィルタは固定したままにします。完全に指定したオースティンのロケーションで 1 回、完全に指定したシアトルのロケーションで 1 回、リクエストを実行します。API のエンドポイントガイダンスでは、都市レベルのロケーションを推奨しており、location と uule は相互排他的なものとして扱われます。
これら 2 つの都市名に対する準備リクエストはいずれも、オーガニックレコードを 9 件返しました。これは、設定された入力に対してデータが利用可能であることを確認するものです。ただし、表示される検索ロケーションやすべての結果が、意図した都市と一致していることを証明するものではありません。
より大きなサンプルを収集する前に、検証シートを定義してください。有用な列として、要求した都市、可視のロケーション証拠、入手できる場合のローカルビジネスのサンプル住所、独立したベースライン手法、観測時刻、レビュアーの判定結果などがあります。ページを検査できるよう、存在する場合は関連する metadata.rawUrl を保存します。
ドキュメント化された設定を用いた手作業のベースライン、あるいは独立した信頼できる計測を使用します。レビュアーは、国別ドメインだけからロケーションを推測するのではなく、証拠を確認する必要があります。全国規模のパブリッシャーがローカル検索に現れることもあれば、ローカルビジネスが汎用ドメインを使用していることもあります。
結果は「確定」「矛盾」「証拠不十分」としてマークします。不確実な観測値を無理に合格カテゴリに入れないでください。精度パーセンテージを公開する場合は、結果を見る前に分母と裁定ルールを定義しておきます。
継続的な比較を比較可能な状態に保つ
ローカライゼーションデータセットには、安定した入力と明示的な収集コンテキストが必要です。レスポンス側にメタデータが含まれていても、リクエストした設定は保存してください。両者は異なる問いに答える記録だからです。
クエリ文字列、要求した国と言語、任意のロケーション文字列、検索モード、収集時刻、レスポンス結果を正確に記録します。国レベルのみのベースラインと、都市レベルの実験は区別しておきます。デスクトップの Web 検索結果と Local モードの結果を、都市だけが変わったかのように比較してはいけません。
本番ワークフローでは、ロケーション証拠が欠落している場合にどう扱うかを決めておきましょう。その観測値をレビュー待ちとして保持するほうが、検証済みの都市スナップショットとして提示するよりも情報価値が高くなります。現在の料金を用いて、繰り返し観測と独立検証のコストを別々に見積もってください。
結論: 主張するロケーションを検証する
国、言語、都市の入力により、検索収集はより意図的なものになりますが、最も強いロケーションの主張は証拠と一致していなければなりません。小さな設定マトリクスから始め、レスポンスを保存し、都市レベルのレポーティングを構築する前に、意図した地理条件を検証してください。
Google 検索 API プロダクトページ ではサービスが紹介されており、パラメータ契約が実装を制御します。成功レスポンスは、終了ではなく検証の開始とみなしてください。
検索データのワークフローを構築する
検索データを扱う開発者コミュニティに参加してください: Discord · Telegram。
Scrapeless アカウント を作成し、より大きなデータ収集をスケジュールする前に、このチュートリアルを小さなクエリセットに適用してください。
FAQ
Q: gl と hl は互換的に使えますか?
いいえ。gl は検索国を選択し、hl は検索言語を選択します。これらは別々に保存し、テストしてください。
Q: hl=en にすると、すべての結果が英語に制限されますか?
すべての結果ドキュメントについての保証として扱わないでください。検索言語設定とドキュメント言語の制約は別の概念です。
Q: location と uule を同時に指定できますか?
いいえ。現在のパラメータ契約では、これらは相互排他的です。あなたの構成に適合するサポートされた制御方式を選択してください。
Q: 空でない 7 つの国のレスポンスがあれば、7 か国での精度が証明されますか?
いいえ。それは要求された 7 つの構成についてデータが返されたことを示しているに過ぎません。精度を確認するには、位置情報の証拠を独立して検証する必要があります。
Q: 国コード付きドメインは、ローカル関連性の十分な証拠になりますか?
いいえ。ドメイン名だけでは、そのページの地理的所在地や SERP が表している出所は確定できません。
Q: この例ではブラウザや AI エージェントが必要ですか?
いいえ。Python と HTTP API を使用します。独立した視覚的検証ではブラウザを使用する場合がありますが、それは別の検証ステップです。
Scrapelessでは、適用される法律、規制、およびWebサイトのプライバシーポリシーを厳密に遵守しながら、公開されているデータのみにアクセスします。 このブログのコンテンツは、デモンストレーションのみを目的としており、違法または侵害の活動は含まれません。 このブログまたはサードパーティのリンクからの情報の使用に対するすべての責任を保証せず、放棄します。 スクレイピング活動に従事する前に、法律顧問に相談し、ターゲットウェブサイトの利用規約を確認するか、必要な許可を取得してください。



