Google SERP API 生の HTML: rawUrl の取得と検証
Senior Web Scraping Engineer
要約 (TL;DR):
- metadata.rawUrl は保存された Google SERP の HTML を指します。 完了した JSON レスポンスを受け取った後、その URL から取得します。
- HTML の取得は 2 回目の HTTP リクエストです。 検索レスポンスは、ダウンロード済みドキュメントをそのフィールド内に埋め込みません。
- ドキュメント検査は限界付きの証拠を提供します。 ステータス、メディアタイプ、バイト数、構造は問題検出に役立ちますが、すべての機能が完全であることまでは証明しません。
- 元のバイト列とチェックサムを保持します。 ローカルコピーは、リモートストレージリンクの可用性とは独立して検査可能なままです。
はじめに: パース結果の裏にページ本体を保持する
構造化された検索データは分析に便利ですが、JSON のフィールドだけでは、その抽出元ページのすべてを示すことはできません。保存された HTML ドキュメントがあれば、結果に説明が必要なときに追加の検査対象になります。
Scrapeless Google Search API は、構造化結果と並んで metadata.rawUrl を返すことができます。この Google SERP API 生 HTML チュートリアルでは、そのドキュメントを取得し、何がダウンロードされたかを確認します。目的は監査可能なローカル成果物を持つことであり、保存されたマークアップがライブブラウザページのあらゆるインタラクションを再現するという主張ではありません。
Google Search クイックスタートレスポンス は、そのフィールドが metadata の下にあることを示しています。より広い アクターリクエストモデル では、まず検索データが提供され、その後に HTML ダウンロードが行われます。
rawUrl が表すもの
rawUrl の値は、レスポンスに関連付けられた保存済みページドキュメントの URL です。オーガニック検索結果の最終到達 URL ではありません。
概念的に 3 つのアドレスを分けて考えてください。検索を受け付けた API エンドポイント、保存された SERP HTML のアドレス、そしてパブリッシャーのページへ続く可能性のある結果リンクです。SERP ドキュメントをダウンロードしても、リンクされている記事や商品、ビジネスページをすべて取得することにはなりません。
クエリやタスク ID からストレージパスを組み立てないでください。完了したレスポンスから、正確な URL を読み取ります。ストレージの場所は出力値であり、ドキュメント例からコピーしたアドレスは、自分のリクエストの証拠にはなりません。
rawUrl が存在しない場合は、ワークフロー上の明示的な「HTML 利用不可」状態にすべきです。新たに構成した Google 検索 URL で置き換えるべきではありません。そうすると別の観測を開始することになるためです。
HTML をダウンロードする前に JSON を取得する
検索タスクが完了してからでなければ、HTML 取得プログラムはメタデータを読み取れません。検索が HTTP 201 を返す場合は、まず タスク結果ワークフロー を使って完了オブジェクトを取得します。
以下のスクリプトは、そのオブジェクトが serp.json として保存されていることを前提とします。他の前提条件は Python と Requests で、python -m pip install requests でインストールします。fetch_serp_html.py として保存し、保存済みレスポンスの横で python fetch_serp_html.py を実行します。
観測されたストレージ URL は、/storage/ 配下の api.scrapeless.com 上で HTTPS を使用します。プログラムは、その観測されたホストとパス形状にダウンロードを限定し、リダイレクトには従わず、ストレージには API キーヘッダーを送信しません。将来ストレージホストが変更された場合は、無制限のフェッチではなく、このルールの見直しを促すべきです。
URL チェックでは、部分文字列ではなく構成要素を検査する必要があります。URI 構文仕様は、そのチェックで使用されるスキーム、オーソリティ、パスなどの構成要素を定義しています。
python
import hashlib
import json
from html.parser import HTMLParser
from pathlib import Path
from urllib.parse import urlsplit
import requests
class DocumentShape(HTMLParser):
def __init__(self):
super().__init__()
self.opened = set()
self.closed = set()
def handle_starttag(self, tag, attrs):
self.opened.add(tag)
def handle_endtag(self, tag):
self.closed.add(tag)
data = json.loads(Path("serp.json").read_text(encoding="utf-8"))
metadata = data.get("metadata")
raw_url = metadata.get("rawUrl") if isinstance(metadata, dict) else None
if not isinstance(raw_url, str) or not raw_url:
raise ValueError("metadata.rawUrl is absent")
parts = urlsplit(raw_url)
if (parts.scheme != "https" or parts.hostname != "api.scrapeless.com"
or parts.port not in (None, 443) or parts.username or parts.password
or not parts.path.startswith("/storage/")):
raise ValueError("Storage URL needs review before downloading")
# The storage fetch uses no API-key header and follows no redirects.
with requests.get(raw_url, timeout=(10, 60), stream=True, allow_redirects=False) as response:
response.raise_for_status()
if response.status_code != 200:
raise ValueError(f"Unexpected storage status: {response.status_code}")
media_type = response.headers.get("Content-Type", "").split(";")[0].lower()
if media_type not in ("text/html", "application/xhtml+xml"):
raise ValueError(f"Unexpected media type: {media_type}")
chunks = []
size = 0
for chunk in response.iter_content(65536):
size += len(chunk)
if size > 10 * 1024 * 1024:
raise ValueError("HTML exceeds this example's local size limit")
chunks.append(chunk)
html_bytes = b"".join(chunks)
if not html_bytes:
raise ValueError("Empty HTML body")
Path("serp.html").write_bytes(html_bytes)
shape = DocumentShape()
shape.feed(html_bytes.decode("utf-8", errors="replace"))
report = {
"bytes": len(html_bytes),
"sha256": hashlib.sha256(html_bytes).hexdigest(),
"has_html": "html" in shape.opened,
"has_body": "body" in shape.opened,
"has_closing_html": "html" in shape.closed,
"source_url": raw_url,
}
Path("serp-html-check.json").write_text(json.dumps(report, indent=2), encoding="utf-8")
print(json.dumps({key: value for key, value in report.items() if key != "source_url"}))
ローカルの 10 メビバイト制限は、クライアント側の安全策の一例であり、API の HTML 最大サイズではありません。より大きなドキュメントは、想定している作業負荷を見直し、ローカルポリシーを意図的に調整すべき理由になります。プログラムは、制限内のダウンロードが成功した場合にのみバイト列を書き込みます。
Scrapeless でスクレイピングを始めよう
Scrapeless でウェブスクレイピングと自動化ワークフローを強化しましょう。
今日サインアップすると $5 分の無料クレジット を獲得できます — クレジットカード不要 です。今すぐ Scrapeless ダッシュボード で無料クレジットを取得してください。
複数レベルでダウンロードを確認する
有用な HTML チェックでは、転送成功、ドキュメントタイプ、ペイロードサイズ、構造、および元の検索との対応関係を記録します。いずれか 1 つのチェックだけですべてを証明することはできません。
このチュートリアルで使用したベースラインの coffee レスポンスでは、HTTP 200 と Content-Type: text/html を伴う 2 回目のリクエストが行われました。ダウンロードされた内容は 1,938,204 バイトで、html と body 要素の開始タグに加え、html 要素の終了タグが含まれていました。これらは 1 つの保存済みドキュメントからの観測結果であり、後続レスポンスの最小サイズ要件ではありません。
| Check | 何を確認できるか | 何を確認できないか |
|---|---|---|
| HTTP status | ストレージ要求が期待どおりに完了したこと | ドキュメントに意図した結果が含まれていること |
| Media type | サーバーがその表現を HTML として認識したこと | すべての検索機能が存在すること |
| Nonempty bytes | ボディがダウンロードされたこと | ボディが正しいページであること |
| Document elements | 基本的なマークアップ構造が存在すること | セマンティックな完全性やレンダリングの忠実度 |
| Checksum | 後からバイト列を保存済みコピーと比較できること | ページ上のすべての記述の真正性 |
| Query and result inspection | ドキュメントが選択されたレスポンス詳細と対応していること | あり得るすべての検索モジュールの完全性 |
レスポンスヘッダーとコンテンツ表現の意味は、HTTP 表現セマンティクスによって定義されています。content-type チェックは 1 つのシグナルとして扱い、ドキュメントを読むことの代わりにしてはいけません。
Python の HTMLParser インターフェイスはマークアップイベントを認識します。これはブラウザレンダラーでも完全な適合性バリデーターでもありません。したがってレポート内のブール構造フィールドは、控えめなチェックにとどまります。
HTML が検索内容と一致しているか検査する
対応関係のチェックでは、保存されたドキュメントをリクエストおよび選択された返却レコードと比較する必要があります。ページ上に表示されているクエリと、JSON に含まれる少数のタイトルやリンクのサンプルから始めてください。
テキストはエンティティエンコードされていたり、要素間で分割されていたり、埋め込みデータ内で異なる形で表現されている場合があります。生の部分文字列検索でヒットしなかったとしても、それはドキュメントを精査する理由であり、その結果が存在しないという即時の証拠ではありません。ファイルをローカルでレンダリングする場合、外部アセットやスクリプトが利用できない、あるいは現在のリソースを要求することがあり、レンダリング結果が元の取得時と異なる可能性があります。
保存したドキュメントを使って、特定の質問に答えてください。たとえば、あるタイトルがマークアップ内に現れるか、想定外のリンク形式が存在するか、そのドキュメントが実際に検索ページであるか、などを判断します。これらの観測結果を拡大解釈して、「すべての動的展開や隠れたモジュールが取得済みである」と主張しないでください。
HTML が欠落している/使用不能な場合のトラブルシュート
HTML の問題は、それが発生したステップで分類する必要があります。ストレージ取得が失敗した場合でも、完了した検索 JSON は保持してください。
| Symptom | Check |
|---|---|
metadata が存在しない |
完了した検索オブジェクトを保存したか確認する |
rawUrl が欠落または空 |
そのレスポンスについては HTML を利用不能として記録する |
| スクリプトに URL が拒否される | 実際のストレージオリジンを承認済みオリジンと比較する |
| 200 以外のストレージレスポンス | ステータスとリクエストコンテキストを保持し、それをドキュメントと呼ばない |
| 想定外のメディアタイプ | HTML とみなす前にレスポンスを精査する |
| サイズ制限に到達した | ローカルの制限値と想定されるドキュメントサイズを確認する |
| 構造チェックが失敗する | バイト列を精査する;有効なパースだけでは不十分 |
| クエリまたは結果の不一致 | 同一リクエストから保存された JSON と HTML を比較する |
リモートストレージアドレスに恒久的な保持期間があると想定してはいけません。プロセスでアーカイブが必要な場合は、ドキュメントが利用可能なうちにダウンロードしてください。JSON、HTML、チェックサム、および収集コンテキストを一緒に保存し、別のエンジニアがその関係性を理解できるようにします。
結論: 実際にダウンロードされたものを保存する
生の HTML ワークフローには 2 つの明確な操作があります。完了した検索 JSON を取得し、その後でそこに含まれる HTML の保存先 URL をダウンロードする、という流れです。ドキュメントを保存し、実際に観測した内容を正確に示すチェック結果を記録してください。
元のクエリを制御するには Google Search API のパラメータ を使用し、検索ワークロードを計画する際には 現在の料金 を参照してください。自分のレポートでは、HTML の利用可能性とオーガニック結果の利用可能性を分けて扱ってください。
検索データワークフローを構築する
検索データを扱う開発者コミュニティに参加してください: Discord · Telegram。
Scrapeless アカウント を作成し、このチュートリアルを大規模な収集をスケジューリングする前に小さなクエリセットへ適用してみてください。
FAQ
Q: rawUrl には HTML テキストが含まれますか?
いいえ。URL が含まれています。2 回目の HTTP リクエストでドキュメントをダウンロードします。
Q: rawUrl はオーガニック検索結果の最終到達先ですか?
いいえ。これはレスポンスに関連付けられた保存済み SERP ドキュメントを指しており、その SERP 上に掲載されているすべてのウェブサイトを指しているわけではありません。
Q: 閉じる html タグがあれば SERP 全体が完全だと証明できますか?
いいえ。これは構造上のシグナルにすぎません。コンテンツの対応関係や動的機能の完全性には追加の検査が必要です。
Q: ストレージへのリクエストに API キーを含めるべきですか?
観測されたストレージのダウンロードは認証ヘッダーなしで成功しました。この例ではキーは API リクエスト内にとどめられ、ストレージや結果サイトには転送されません。
Q: 保存された HTML リンクは恒久的なアーカイブですか?
確立されていない保持保証を前提にしてはいけません。後でドキュメントが必要な場合はローカルコピーとチェックサムを保持してください。
Q: 保存された HTML はリンク先ページの検証の代わりになりますか?
いいえ。SERP HTML は検索ページを記録したものです。リンク先ページの内容の検証は別個の作業です。
Scrapelessでは、適用される法律、規制、およびWebサイトのプライバシーポリシーを厳密に遵守しながら、公開されているデータのみにアクセスします。 このブログのコンテンツは、デモンストレーションのみを目的としており、違法または侵害の活動は含まれません。 このブログまたはサードパーティのリンクからの情報の使用に対するすべての責任を保証せず、放棄します。 スクレイピング活動に従事する前に、法律顧問に相談し、ターゲットウェブサイトの利用規約を確認するか、必要な許可を取得してください。



