Google SERP APIのページネーション: start を使って結果を収集する
Senior Web Scraping Engineer
要約:
- Google のウェブ検索ページネーションは start オフセットを使う。 クエリと言語・地域設定を固定したまま、
0、10、20以降のオフセットを指定してリクエストする。 - 10 ページあっても有機検索結果が 100 件とは限らない。 実際の
coffee収集例では、10 ページで 95 件のレコードだった。 - 重複排除には明示的な定義が必要。 その 95 レコードには、返却されたリンク文字列として 85 個の異なる値が含まれていたが、「85 個のユニークな到達ページ」が検証されたわけではない。
- 上限付きループには停止理由の記録が必要。 空配列、同一ページの繰り返し、エラー、ページ上限到達はそれぞれ異なる結果を表す。
はじめに: 1 ページ目だけで終わらせない
Google SERP API のページネーションは、一連の関連した観測値である。各リクエストは同一検索の別オフセットを要求し、各レスポンスはそれぞれ固有のコンテキストをもつ。
このチュートリアルでは、Scrapeless Google Search API を使って最大 10 ページ分のウェブ検索結果を取得する。各レスポンスを保持し、保持した各レコードごとにオフセットを付けて保存し、生データ行と重複排除後のリンク文字列とを区別する。この例は、トピックの深掘りや検索カバレッジの把握に役立つが、完全な「トップ 100 ランキング」データセットを構築するものではない。
Google Search エンドポイントのコントロール がウェブ検索のオフセットを定義しており、アクターリクエストパターン がそれを囲む API コールの構造を説明している。収集の間は検索モードを固定しておくこと。
start がリクエストをどう変えるか
start パラメータは、ウェブ検索リクエストの結果オフセットを選択する。通常のページシーケンスは 0、10、20 … のように続く。
オフセットはリクエストの制御値であり、それ以前のレスポンスに含まれていた有機検索レコード数を表すものではない。あるページが有機検索結果を 9 件しか返さなくても、この例では次のリクエストはあくまで次に設定されたオフセットを使う。len(organic_results) ずつ進めてしまうと、レスポンスの件数とページネーション仕様を混同することになる。
q、gl、hl、および明示的なフィルターは変更せずに固定しておくこと。収集中に国設定を変更すると、結合した配列はもはや単一の検索設定を表さなくなる。こうしたミスを検出できるよう、各ページごとに入力オブジェクト全体を保存しておく。
この例では num と tbm を省略している。これはウェブ検索のページネーション例であり、他のモードは別途確認する必要がある。モード間でオフセット設定をそのまま流用するのではなく、最新のパラメータ定義 を参照すること。
ページサイズがそろっていない 10 ページの例
q=coffee、gl=us、hl=en の組み合わせで収集したところ、要求した 10 個すべてのオフセットで有機検索レコードが返ってきた。このサンプルでは、各リクエストは HTTP 200 で完了している。
| start | Returned Organic Records |
|---|---|
| 0 | 9 |
| 10 | 9 |
| 20 | 9 |
| 30 | 9 |
| 40 | 10 |
| 50 | 10 |
| 60 | 10 |
| 70 | 9 |
| 80 | 10 |
| 90 | 10 |
| Total | 95 |
返却された link 文字列を完全一致で比較したところ、85 個の異なる値になった。この計算ではリダイレクトの追跡、canonical タグの比較、コンテンツ同一性の確認は行っていない。異なる 2 つのリンクが 1 つのページに到達することもあれば、異なる 2 ページが同一ドメインを共有していることもある。ホスト名でグルーピングしたり、生の文字列を比較したりしても、「ユニークな到達先ページ」が網羅されていることの証明にはならない。
この例が示すのは、設定したオフセットが 1 回の収集中にデータを返したという事実だけである。すべてのクエリが常に 10 個の空ではないページを返すことを保証するものではない。複数リクエストで収集している間にも、検索結果は変化しうる。
上限付きページネーション収集器を作る
この収集器は最大 10 回まで検索リクエストを送り、完了した各レスポンスを保存し、有機検索配列が空になったとき、または同一結果ページが繰り返し現れたときに早期停止する。エラーはエラーとして記録し、すでに収集済みのデータは保持する。
前提条件は Python・Requests・環境変数に設定された SCRAPELESS_API_KEY である。Requests を python -m pip install requests でインストールし、プログラムを paginate_google.py として保存して python paginate_google.py を実行する。出力は pagination-runs 配下の新しいディレクトリに保存される。
リクエストヘルパーは、完了済みタスクと保留中タスクの両方を処理します。各検索を一度だけ送信し、必要に応じて既存タスクの結果エンドポイントを使用します。その区別はpending-task ワークフローによって定義されており、コード上の制限はローカルなポリシー選択にすぎません。
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("pagination-runs") / datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%fZ")
run_dir.mkdir(parents=True)
seen_links = set()
seen_pages = set()
collected = []
summary = []
stop_reason = "page_limit"
try:
for start in range(0, 100, 10):
query = {"q": "coffee", "gl": "us", "hl": "en", "start": start}
data = google_search(query)
(run_dir / f"page-{start}.json").write_text(
json.dumps({"input": query, "response": data}, ensure_ascii=False, indent=2),
encoding="utf-8",
)
rows = organic_rows(data)
signature = json.dumps(rows, sort_keys=True, ensure_ascii=False)
repeat = bool(rows) and signature in seen_pages
seen_pages.add(signature)
new_count = 0
for index, row in enumerate(rows, start=1):
link = row.get("link")
usable_link = isinstance(link, str) and bool(link.strip())
if usable_link and link in seen_links:
continue
if usable_link:
seen_links.add(link)
collected.append({"start": start, "array_index": index, "result": row})
new_count += 1
summary.append({"start": start, "returned": len(rows), "kept": new_count})
if not rows:
stop_reason = "empty_organic_array"
break
if repeat:
stop_reason = "identical_result_page"
break
except (requests.RequestException, ValueError, RuntimeError, TimeoutError) as exc:
stop_reason = "error:" + type(exc).__name__
raise
finally:
(run_dir / "collected.json").write_text(json.dumps(collected, ensure_ascii=False, indent=2), encoding="utf-8")
report = {"pages": summary, "stop_reason": stop_reason, "kept_rows": len(collected)}
(run_dir / "summary.json").write_text(json.dumps(report, indent=2), encoding="utf-8")
print(json.dumps(report))
finally ブロックは、後続のページが失敗した場合でも要約を書き出します。失敗したページは空ページとして追加されません。以前に保存されたページファイルは検査用として利用可能なままであり、発生した例外によってプログラムは引き続き目に見える形で失敗します。
Scrapeless でスクレイピングを始めよう
Scrapeless で Web スクレイピングと自動化ワークフローを強化しましょう。
本日サインアップすると 5 ドル分の無料クレジット を獲得できます — クレジットカードは不要です。今すぐ Scrapeless ダッシュボード で無料クレジットを取得しましょう。
慎重な重複排除ルールを選ぶ
コレクターは、空でない返却リンク文字列を厳密一致で重複排除し、リンクが欠落している行は保持します。このポリシーは URL コンポーネントを書き換えないため、監査が容易です。
URI 正規化モデルは、URL 比較に明示的なルールが必要な理由を説明しています。クエリ文字列の無批判な削除、パスの大文字小文字変更、スラッシュのバリエーションの折り畳みは、意味のある差異を消してしまう可能性があります。対象となる Web サイトを検証したうえで、より強力な正規化を追加してください。
生のページレコードは、繰り返しリンクの最初の出現だけを結合結果が保持する場合でも、すべてページファイルに残ります。出現回数分析を行うには、重複排除されたコレクションではなく、これらのページファイルを参照してください。そうしなければ、同じリンクが複数のオフセットに現れたという証拠を失ってしまいます。
繰り返しページのセーフガードは、シリアル化された結果レコードを比較します。これは、まったく同一の繰り返しデータを検出するものであり、あらゆる類似 SERP を特定できると主張するものではありません。小さなフィールドの変化によって、見た目がよく似た 2 つのレスポンスでも比較結果が異なる場合があるため、上限付きのページ数制限は依然として必要です。
空ページと部分実行を解釈する
空の organic 配列は、このコレクターにおける停止条件であり、そのトピックについて Google にこれ以上インデックスされたページがないという証拠ではありません。配列の欠落や不正なレコードは、依然としてバリデーションエラーです。
| Stop Reason | コレクターが観測した内容 | 安全な解釈 |
|---|---|---|
page_limit |
設定されたページ予算に到達した | コレクションは設定された予算まで完了している |
empty_organic_array |
完了したレスポンスに organic レコードが 0 件だった | この実行はそのオフセットで停止した |
identical_result_page |
organic レコードが完全に同一だった | セーフガードによってこれ以上の収集が停止された |
error:... |
リクエストまたはパース処理が失敗した | データセットは部分的である |
一般的な HTTP ステータスの意味論は、通信結果を区別するうえで役立ちますが、収集の完全性を記録する責任は依然としてアプリケーション側にあります。最初のページが成功していても、後続ページの失敗を成功扱いにすることはできません。
定期実行の作業では、実行 ID を割り当て、タイムスタンプ、入力、オフセット、および停止理由を保持してください。これは データ来歴の実務的な目的に従うものであり、後の利用者が、派生データセットを生成した観測と変換をさかのぼって追跡できるようにするためのものです。
結論: 深さとカバレッジを分けて報告する
ページネーションレポートには、要求したオフセット、完了したページ、生の行数、および重複排除ルールを示すべきです。これらの指標は異なる問いに答えるものであり、コードと文章の両方で分けて扱う必要があります。
より深いコレクションの予算を立てる際には、サービスの詳細と現在の料金については Google Search API の製品ページを参照してください。10 ページ分の予算はコレクション設定であり、最終的に 100 件の URL を保証するものではありません。
検索データワークフローを構築する
検索データを扱う開発者コミュニティに参加しましょう: Discord · Telegram。
Scrapeless アカウントを作成し、大規模なコレクションをスケジューリングする前に、このチュートリアルを小規模なクエリセットに適用してみてください。
FAQ
Q: start は返却された行数だけ増やすべきですか?
いいえ。ウェブ検索のオフセットシーケンスに従ってください。9 件のオーガニックレコードしかないページでも、次に設定されたオフセットは変わりません。
Q: 10 ページ分の収集は常に 100 件の結果を返しますか?
いいえ。実際の収集では 95 件のオーガニックレコードが返されました。ページサイズと利用可能件数は、それぞれのレスポンスから測定する必要があります。
Q: 85 個の異なるリンク文字列は、85 個のユニークなウェブページと同じですか?
いいえ。完全一致による文字列の重複排除では、リダイレクト、正規 URL としての同一性、またはページ内容は検証できません。
Q: HTTP エラーは空ページとして保存すべきですか?
いいえ。失敗は別に保存し、実行を部分完了としてマークしてください。空の completed 配列には別の意味があります。
Q: pagination.next は Google から直接取得する必要がありますか?
いいえ。このクライアントはリクエストを Scrapeless エンドポイント上に留め、設定された start 値を提供します。Google のナビゲーション URL を直接取得することはありません。
Q: コレクターは AI エージェントなしで実行できますか?
はい。これは独立した Python プログラムであり、制限された逐次ページループを持っています。
Scrapelessでは、適用される法律、規制、およびWebサイトのプライバシーポリシーを厳密に遵守しながら、公開されているデータのみにアクセスします。 このブログのコンテンツは、デモンストレーションのみを目的としており、違法または侵害の活動は含まれません。 このブログまたはサードパーティのリンクからの情報の使用に対するすべての責任を保証せず、放棄します。 スクレイピング活動に従事する前に、法律顧問に相談し、ターゲットウェブサイトの利用規約を確認するか、必要な許可を取得してください。



