Loading Light/Dark Toggle
ブログに戻ります

Python での Google 検索 API チュートリアル:リクエストと結果

Alex Johnson
Alex Johnson

Senior Web Scraping Engineer

12-Nov-2026

要約

  • Scrapeless Google Search API は、構造化された検索データを Python に返します。 認証済みの JSON リクエストで q、gl、hl を送信します。
  • HTTP 200 と HTTP 201 では処理が異なります。 完了した結果はそのまま読み取り、保留中のタスク ID は保持して既存タスクを取得します。
  • HTTP レスポンスが成功でも、データチェックは必須です。 行を使用する前に organic_results を検証します。
  • レスポンスを保存すると、後からの分析が楽になります。 タイトル、スニペット、リンクを選ぶ前に JSON を保存します。

はじめに: 検索結果を Python で扱えるようにする

検索リクエストがアプリケーションにとって有用なのは、そのアプリケーションが完了したデータと、まだ実行中のタスクを区別できるときだけです。response.text を出力する簡単なスクリプトならすぐに始められますが、その状態は混在したままになってしまいます。

この Google Search API Python チュートリアルでは、Scrapeless Google Search API 用の小さなクライアントを作成します。クエリを設定し送信し、保留中のタスクを処理し、別のスクリプトが検査できるレスポンスを保存します。例では通常のウェブ検索を使います。画像、ローカル、動画、ショッピングは結果セクションが異なり、それぞれ別の検証が必要です。

このコードは Scrapeless と通信するものであり、Google の Custom Search JSON API や Search Console API ではありません。あなたのアプリケーションが受け取るのはサイトトラフィックのレポートではなく、検索スナップショットです。すでにより広範な Scrapeless アクターリクエストモデル を扱っている場合、リクエストの入れ物には見覚えがあるはずです。

前提条件

Python、requests パッケージ、そしてサービスにアクセスできる Scrapeless API キーが必要です。プロジェクトには仮想環境を使用し、python -m pip install requests で Requests をインストールしてください。スクリプトを実行する前に、SCRAPELESS_API_KEY をプロセス環境に設定します。キーはソースファイル、共有するノートブック、レスポンスログには残さないでください。

ローカル環境変数は、このスクリプトのために選んだ慣習です。HTTP 認証ヘッダーは x-api-token です。両者の役割は異なります。Python は変数を読み取り、その値をヘッダーに入れて API エンドポイントへ送信します。

以下の完全なプログラムを google_search.py として保存し、python google_search.py で実行します。プログラムは作業ディレクトリに serp.json を作成します。過去のレスポンスを保持したい場合は、実験ごとに別々のディレクトリを使用してください。

q、gl、hl を設定する

q パラメータは検索クエリを指定し、gl は検索対象の国、hl は検索言語を選択します。これらのコントロールは、周囲のリクエストオブジェクト内でアクター名と並んで input の中に配置します。

Field Example What to Check
actor scraper.google.search アクターをトップレベルに維持する
input.q coffee 比較したいクエリ文字列をそのまま保存する
input.gl us 要求した国コードを結果と一緒に記録する
input.hl en 要求した言語を別枠で記録する

まずはこの小さな入力から始めてください。位置情報や検索フィルタをすぐに追加してしまうと、どのパラメータが出力を変えたのかを特定するのがすぐに難しくなります。リクエストを拡張するときは、現在の Google Search パラメータ を手元に置いておきましょう。

ボディは Requests の json= 引数で送信します。これは Python オブジェクトを JSON としてシリアライズし、適切な Content-Type を設定します。JSON オブジェクトと配列は JSON データ形式 において別個の構造です。レスポンスが正しくパースできても、それがアプリケーションの期待するオブジェクト形状であるとは限りません。

リクエストを送信し、保留中タスクを取得する

クライアントは 1 つの検索タスクを送信し、そのタスクがまだ処理中の場合にのみ結果エンドポイントをチェックします。完了したレスポンスは、Python の辞書として呼び出し元に返されます。

Google Search クイックスタート は POST /api/v1/scraper/request を使用します。この API では、HTTP 201 は処理中であることを意味し、taskId を含みます。タスク結果ワークフロー は GET /api/v1/scraper/result/{taskId} でその ID を取得します。
これはステータスコードのアプリケーション固有の解釈です。一般的なHTTP セマンティクス仕様はステータスクラスを定義し、一方でサービスコントラクトは保留中のタスクをクライアントがどのように扱うべきかを示します。

このプログラムは結果チェックを 10 回まで、間隔 2 秒に制限しています。これらはサービスの制限や完了時間の保証ではなく、クライアント側の設定例です。ネットワークタイムアウトは各リクエストごとに個別に適用されます。タスクが保留のままの場合、例外にはタスク ID が含まれるため、オペレータがそれを保持できます。

python Copy
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__":
    query = {"q": "coffee", "gl": "us", "hl": "en"}
    try:
        result = google_search(query)
        Path("serp.json").write_text(
            json.dumps(result, ensure_ascii=False, indent=2), encoding="utf-8"
        )
        rows = organic_rows(result)
        print(f"Saved serp.json; organic rows: {len(rows)}")
        for row in rows:
            print(row.get("position"), row.get("title"), row.get("link"))
    except requests.HTTPError as exc:
        raise SystemExit(f"HTTP request failed: {exc.response.status_code}")
    except requests.RequestException:
        raise SystemExit("Network request did not complete")
    except (ValueError, RuntimeError, TimeoutError, KeyError) as exc:
        raise SystemExit(str(exc))

最初の raise_for_status() は HTTP エラーレスポンスを捕捉します。明示的なステータスチェックは、想定外の非エラーステータスも拒否します。JSON のパースはそれらのチェックの後に行われ、結果バリデータは API がタスク完了を通知した後に実行されます。各段階は異なる疑問に答えます。

Scrapeless でスクレイピングを始めよう

Scrapeless で Web スクレイピングと自動化ワークフローを強化しましょう。
本日サインアップすると $5 分の無料クレジット がもらえます — クレジットカード不要。

今すぐ Scrapeless ダッシュボード で無料クレジットを受け取りましょう。

オリジナルレスポンスを失わずに organic_results を読む

organic_results 配列には、完了したレスポンス内のオーガニック結果レコードが含まれます。各レコードから position、title、snippet、link などのフィールドを読みつつ、検査のために元のオブジェクトを保持します。

このチュートリアルの準備中に使用したベースラインの coffee リクエストは、HTTP 200 と、gl=us と hl=en を持つ 8 件のオーガニックレコードを返しました。その件数は 1 つのレスポンスを表します。同じクエリに対する後続のリクエストでは、行数が異なったり、検索機能の構成が異なったりする可能性があります。

プログラムはオーガニック配列を検証する前に JSON を保存します。これは、完了したレスポンスの形状が予期しないものであった場合に重要です。検証で例外が発生した際にレスポンスを失ってしまうのではなく、何が届いたのかを確認できます。Python の JSON エンコード・デコードインターフェースは、ensure_ascii=False によって非 ASCII テキストを読みやすく保つことをサポートしています。

3 つのケースを分けて扱います。空配列は、オーガニック項目が 1 つもないという観測済みの集合です。キーが存在しない場合、そのような保証はありません。型が誤っている値はスキーマ上の問題です。スクリプトは最初のケースは受け入れ、残り 2 つについては空リストで黙って置き換えるのではなく処理を停止します。

返されるリンクにもコンテキストが必要です。直接的に見える URL は遷移先候補ですが、Google の中継 URL であれば、ターゲットサイトとして扱う前にさらに処理する必要があります。この最初のチュートリアルでは、最終的な遷移先が検証されたと主張することなく、返された値をそのまま出力します。

適切なレイヤーで障害を処理する

例外は、認証ヘッダを露出させたり、失敗したリクエストを有効に見える空結果へと変えてしまうことなく、失敗した段階を特定できるものであるべきです。

観測内容 このクライアントにとっての意味 次に確認するもの
環境変数が存在しない 認証がローカルで構成されていない プロセスの環境を確認する
HTTP 400 API がリクエストを拒否した 入力名・型・組み合わせを確認する
HTTP 429 サービスがリクエスト制限を報告した リクエスト頻度とアカウントのクオータを確認する
その他の HTTP エラー 完了した結果は受理されなかった 調査のためにステータスとリクエストコンテキストを保持する
無効な JSON ボディをパースできなかった 制御された診断ログでレスポンスを検査する
organic 配列が存在しない ペイロードがこのコンシューマと一致しない 保存した JSON と要求した検索モードを検査する
保留タスクの上限に達した このクライアントでは完了が観測されなかった タスク ID を保持し、ジョブを未完了としてマークする

サンプルは意図的に、リクエストヘッダ全体やサーバーのエラーボディを出力しないようにしています。より大きなサービスでは、クエリ設定・ステータス・利用可能であればタスク ID を含む構造化された診断情報を書き出します。失敗した実行は、完了した観測とは別に記録し、ダウンストリームのレポートが失敗を欠如と誤認しないようにします。

結論: 最初のクライアントは小さく保つ

有用な Google Search API Python クライアントには明確な経路があります。クエリを送信し、必要であれば既存タスクを取得し、レスポンスを保存し、アプリケーションが利用するフィールドを検証します。その経路が機能するようになったら、入力次元を 1 つずつ追加していきます。
Google Search API の製品詳細を使ってサービスを選択し、現在の料金を確認して定期的な収集を計画してください。大きなデータセットを構築する前に、保存したそれぞれのレスポンスの隣にリクエスト設定を保持しておきましょう。

検索データワークフローを構築する

検索データを扱う開発者のコミュニティに参加してください: Discord · Telegram。

Scrapeless アカウントを作成し、大規模な収集をスケジュールする前に、このチュートリアルを小さなクエリセットに適用してみてください。

FAQ

Q: Python は SDK なしで Google Search API を呼び出せますか?

はい。例では Requests と、ドキュメント化された HTTP エンドポイントを使用しています。AI エージェントや特定フレームワーク向けの SDK は不要です。

Q: HTTP 201 には最終的な検索結果が含まれていますか?

この API では、HTTP 201 は保留中のタスクを示します。taskId を保持し、結果エンドポイントを通じてそのタスクを取得してください。

Q: gl=us は、すべての結果がアメリカのものであることを証明しますか?

いいえ。国情報は検索入力であり、返されるすべてのページに対する国籍ラベルではありません。ローカル精度には、別の検証手法が必要です。

Q: organic_results キーが存在しない場合、空リストとみなすべきですか?

いいえ。キーが存在しないことと、明示的に空配列が返されることは、異なる観測結果です。オーガニックレコードが返されなかったと報告する前に、レスポンスの構造を確認してください。

Q: 別途プロキシを設定する必要はありますか?

この基本的なリクエストでは、別途プロキシを設定する必要はありません。API 側で取得処理が行われます。トランスポートやロケーション設定を追加する前に、パラメータ仕様を確認してください。

Q: スクリプトは、すべての結果リンク先のコンテンツを検証しますか?

いいえ。これは検索スナップショットを収集するものです。リンク先の検証やページコンテンツのバリデーションは、別のステップになります。

Scrapelessでは、適用される法律、規制、およびWebサイトのプライバシーポリシーを厳密に遵守しながら、公開されているデータのみにアクセスします。 このブログのコンテンツは、デモンストレーションのみを目的としており、違法または侵害の活動は含まれません。 このブログまたはサードパーティのリンクからの情報の使用に対するすべての責任を保証せず、放棄します。 スクレイピング活動に従事する前に、法律顧問に相談し、ターゲットウェブサイトの利用規約を確認するか、必要な許可を取得してください。

最も人気のある記事

カタログ