Google 検索 API JSON レスポンス:organic_results の解説
Senior Web Scraping Engineer
要約
- organic_results はオーガニック検索レコードの集合です。 他の検索モジュールと混在させずに、各レコードの返却ポジション、タイトル、スニペット、リンクを読み取ります。
- 返却ポジションと配列順序は別の値です。 データセットを準備する際は両方を保持します。
- 返却されたリンクは自動的に検証済みの最終 URL ではありません。 中継状態と最終候補状態を区別して保持します。
- 欠損フィールドは見える形で残します。 スニペットがないこと、空文字列、不正なレコードは、それぞれ異なる扱いが必要です。
序論: フラット化する前にレスポンスを読む
Google 検索 API の JSON レスポンスには、オーガニック結果に加えて、ナレッジパネル、ローカルセクション、関連する質問、その他クエリ依存のモジュールが含まれることがあります。title フィールドを含むあらゆるオブジェクトをフラット化すると、意味が混ざったデータセットが生成されます。
このチュートリアルは Scrapeless Google Search API における organic_results に焦点を当てます。目的は、タイトル、スニペット、ポジション、リンクのための、小さく検査しやすいレコード形式を作ることです。順位トラッカーを構築するものではなく、返却されたすべてのリンクがすでに最終ターゲット URL と照合済みだと主張するものでもありません。
Google 検索レスポンス例 と アクターリクエストのワークフロー が周辺のリクエストコンテキストを提供します。ここでの有用な作業は、完了したレスポンスが保存された後に始まります。
organic_results が含むもの
organic_results フィールドはオーガニック結果オブジェクトの配列であり、各アイテムごとにフィールドの有無を確認する必要があります。レコードは行き先ページの完全なコピーではありません。
| Field | データセットにおける意味 | 取り扱いルール |
|---|---|---|
position |
API によって返却されたポジション | 再計算せず、そのまま保持する |
title |
結果タイトル | null や欠損値をテキストと区別して保持する |
snippet |
検索結果の抜粋 | ページ全文ではなく「検索観測値」として扱う |
link |
返却された結果 URL | 後続の行き先マッチング前に分類する |
redirect_link |
追加のリダイレクト形式リンク(存在する場合) | link を自動で置き換えず、別に保存する |
source |
利用可能な場合に表示されるソースラベル | 登録可能ドメインであると決めつけない |
この表は調査対象となるフィールドを説明するものであり、すべてのアイテムがあらゆるキーを持つことを保証するものではありません。パラメータリファレンス はリクエストの制御方法を定義するものであり、クエリ間で結果モジュールが同一であるという約束として読むべきではありません。
JSON は、JSON 仕様 に記載されているように、null、文字列、配列などの値を許容します。柔軟なレスポンス形式であっても、利用側には意図的な契約が必要です。アプリケーションが保持できる欠損値と、処理を停止すべき欠損値を決めておきましょう。
ランクをでっち上げずにポジションを保持する
ページを結合する際は、返却された position、配列インデックス、およびリクエストオフセットを別々のフィールドとして保持します。それぞれが観測の異なる部分を表します。
配列インデックスは、そのアイテムが返却配列のどこに現れたかを記録します。返却ポジションは API が提供した値です。リクエストオフセットは、どのページを要求したかを記録します。ポジションの意味を確立する前に、単にオフセットをポジションに加えると、オフセットを二重計上したり、レスポンスが明示していないランキングを暗示したりする可能性があります。
広告、ナレッジグラフ、オーガニックレコードを、定義・検証済みの独自測定がない限り、一連のシーケンスとして数え上げないでください。オーガニック順位が必要な開発者は、そのレコードを生成した検索ページを検査できるだけのコンテキストを保持するべきです。
たとえデータベースに必要なのが数列のカラムだけであっても、変更前の JSON を保存しておきましょう。後になって、最初の正規化スクリプトで捨ててしまったフィールドが必要になったり、自分の変換によって導入された値と、もともと欠損していたフィールドを区別する必要が生じたりするかもしれません。
解決前にリンクを分類する
URL の分類は、その後の検証処理におけるルーティングの決定であり、最終到達点の証拠ではありません。coffee のベースラインレスポンスには、同一のオーガニックレコード内に、直接的な link 値と、別個の Google redirect_link 値の両方が含まれていました。
Google という単語が含まれているかどうかだけで判断するのではなく、スキーム、ホスト名、パスを検査してください。URI コンポーネントモデルは、これらの部分を明示的に示します。パスの中におなじみのブランド名が含まれている URL であっても、そのブランドがホストしているとは限りません。
有用な分類には、値が欠落しているもの、相対リンク、観測された Google の中継、絶対 URL の候補などがあります。/goto?url=... のリンク内の不透明な値は保持してください。不透明なパラメータは、復号スキームを推測することで復元できる宛先ではありません。
Scrapeless でスクレイピングを始めよう
Scrapeless で Web スクレイピングと自動化ワークフローを強化しましょう!
今日サインアップすると $5 分の無料クレジット を獲得できます — クレジットカードは不要です。今すぐ Scrapeless ダッシュボード で無料クレジットを受け取りましょう。
保存済み JSON レスポンスを正規化する
次のプログラムは、結果 URL にアクセスすることなく正規化されたレコードを作成します。両方のリンクフィールドを保持し、後で確認できるようにローカル分類を付与します。
前提条件は、Python と、serp.json として保存された完了済みの Google 検索レスポンスです。ログ用メタデータを含むカスタムラッパーではなく、API のレスポンスオブジェクト自体を保存してください。クイックスタートリクエストがそのレスポンスを提供します。スクリプトを normalize_organic.py として保存し、JSON ファイルの横で python normalize_organic.py を実行します。
例で設定しているホスト名は、このレスポンスファミリーで観測された Google ホストをカバーしています。これは意図的に、すべての Google ドメインのグローバルな登録簿ではありません。実際のレスポンスが追加を正当化するときにのみ拡張してください。他の絶対 URL は検証されていない候補のままです。
python
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 から開始し、現在の料金 を見ながらコレクション頻度を選び、データベーススキーマを確定する前に、保存したレスポンスをいくつか検証してください。
検索データワークフローを構築する
検索データを扱う開発者コミュニティに参加しましょう: Discord · Telegram。
Scrapeless アカウント を作成し、大規模な収集をスケジューリングする前に、このチュートリアルを小さなクエリセットに適用してください。
FAQ
Q: organic_results には SERP 上に見えるすべてのセクションが含まれますか?
いいえ。他の検索機能は別のレスポンスセクションとして現れる場合があります。organic 配列用のパーサーで、それらのモジュールを暗黙的に取り込まないようにしてください。
Q: position は要素の配列インデックスと同じですか?
同一であると仮定しないでください。返却された position と配列インデックスは別々に保持し、とくにページネーションされたリクエストをまたぐ場合は分けて扱ってください。
Q: redirect_link は link を置き換えるべきですか?
いいえ。両方が存在する場合はどちらも保持してください。実際の URL の状態と、その後段のタスクに基づいて、どのリンクを宛先として処理するかのポリシーを決めてください。
Q: エンコードされた Google リンクは、デコードされた最終宛先として扱えますか?
いいえ。不透明な値はそのまま保持し、最終的な宛先の同定が必要な場合は、検証済みの解決プロセスを使用してください。
Q: snippet が空でないなら、その要約は正確だといえますか?
いいえ。空でないテキストは、そのフィールドが利用可能であることを示すだけです。正確性や主張の裏付けには、元コンテンツの精査が必要です。
Q: 正規化には AI エージェントや別のプロキシが必要ですか?
いいえ。この正規化スクリプトは保存された JSON に対して動作し、ネットワークリクエストは一切行いません。
Scrapelessでは、適用される法律、規制、およびWebサイトのプライバシーポリシーを厳密に遵守しながら、公開されているデータのみにアクセスします。 このブログのコンテンツは、デモンストレーションのみを目的としており、違法または侵害の活動は含まれません。 このブログまたはサードパーティのリンクからの情報の使用に対するすべての責任を保証せず、放棄します。 スクレイピング活動に従事する前に、法律顧問に相談し、ターゲットウェブサイトの利用規約を確認するか、必要な許可を取得してください。



