Google Search API: 検索クエリから構造化されたJSONへ

Emily Chen

Advanced Data Extraction Specialist

09-Sep-2026

TL;DR:

Scrapeless Google Search APIは、検索結果を構造化されたJSONとして返します。 リサーチツール、SEOレポート、ソース発見ワークフローでオーガニック結果フィールドを使用してください。
検索コンテキストは結果に属します。 後での比較に明確な意味が持てるように、クエリ、国、言語、観察時間を一緒に保ってください。
保留中のタスクは空の結果セットとは異なります。 organic_resultsを読む前に、HTTP 201を別途処理してください。

Google検索データは、チームが各結果をそれを生み出した質問および市場と結びつけることができるときに有用になります。スプレッドシートにコピーされたタイトルとURLは、そのコンテキストの多くを失います。構造化された応答は、アプリケーションが最初からそれを保持できるようにします。

更新された Scrapeless Google Search API は、検索クエリからJSONへの管理されたルートを提供します。あなたのアプリケーションはリクエストを送り、返されたデータの使用方法を決定します。プロキシとCAPTCHA処理はサービス側で実行され、チームが維持する必要のある収集インフラストラクチャを削減します。

このガイドはその引き渡しに従います：検索コンテキストを選択し、リクエストを送信し、応答を読み、他の人が理解できるデータセットを保存します。

Google Search APIが返すもの

Google Search APIは構造化された検索データを返し、存在する場合はオーガニック結果が最上位の organic_results 配列に利用可能です。自然な結果には、position、title、link、および snippet が含まれる場合があります。応答には、クエリと返された結果に応じて、ページング情報や他の検索モジュールが含まれることもあります。

サブセットを抽出する前に、元の応答を保持してください。フラットテーブルは分析に便利ですが、意図的なマッピングなしにすべてのネストされたオブジェクトを表すことはできません。 JSONデータモデル は配列、オブジェクト、文字列、数値、ブーリアン、およびnullを区別します。これらの区別を保持することで、後の処理が容易になります。

スニペットは検索結果の抜粋です。目的のページの完全なコンテンツを提供するものではありません。リサーチアプリケーションが記事の証拠を必要とする場合、そのアプリケーションはそのページを別途取得してレビューする必要があります。

小さな最初のリクエストを準備する

最初のリクエストにはScrapeless APIキー、クエリ、およびHTTP経由でJSONを送信できるクライアントが必要です。Google Search APIへのアクセスがあるアカウントを使用し、SCRAPELESS_API_KEY環境変数にキーを保持してください。

以下のPythonの例では、requestsパッケージをプロジェクト環境にインストールします。残りのモジュールはPythonの標準ライブラリから来ます。スクリプトをgoogle_search_export.pyとして保存し、ローカルシェルまたはシークレットマネージャー経由で環境変数を設定した後、python3 google_search_export.pyで実行します。

この例では、中立のクエリcoffee、国us、および言語enを使用しています。キーワードのリストやスケジュールされたジョブを導入する前に、この小さな入力から始めてください。最初に応答の形を確認してください。その後のデータモデルは、それに依存します。

認証されたリクエストは、自分自身のアカウントキーが必要な前提条件です。例のリクエストの形は現在のAPIリファレンスに従います；ライブアカウントの実行をキャプチャした形では提示されていません。

国、言語、および入力モードを選ぶ

国、言語、位置は検索リクエストの異なる部分を説明します。glは検索国を選択し、hlは検索言語を選択し、locationは検索がどこから始まるべきかを指定します。google_domainはGoogleドメインを選択します。現在のデバイスオプションはデスクトップをサポートしています。

Google Search APIパラメータモデルには、リクエストの構造に影響を与える2つの入力ルールもあります：

qを使用して、個々のパラメータを通じて表現されたクエリを提供します。あるいは、完全なGoogle Search urlを提供します。urlが供給されると、他の入力パラメータは無視されます。
locationまたは uule のいずれかを選択します。これらは一緒に使用できません。

市場を横断した比較のために、各応答とともに完全な入力オブジェクトを保存してください。同じ国と言語を設定することで、意図されたコンテキストが明示的になり、観察間で同一の結果を保証するものではありません。特定の人のサインインした検索履歴を再現するものでもありません。
クエリには、site:、inurl:、およびintitle:のような演算子を含めることができます。サイト制限付き検索はインデックス付けされたページの完全な在庫ではなく、その結果は正確なインデックスカバレッジのカウントとして扱ってはいけません。

JSONをリクエストしてオーガニック結果をエクスポートする

リクエストはPOST https://api.scrapeless.com/api/v1/scraper/request、scraper.google.searchアクター、およびx-api-tokenヘッダーを使用します。スクリプトは、レスポンスをその入力および受信時間と共に保存し、その後HTTP 200でオーガニック結果をCSVにエクスポートします。

注: ネットワークリクエストは、あなたのScrapeless APIキーを必要とし、このアーティクルのためにライブアカウントで実行されていません。スクリプトは、検査のためのHTTP 201タスクレスポンスを保持します; タスク結果の取得を実装していません。

python Copy

import csv
import json
import os
from datetime import datetime, timezone
from pathlib import Path

import requests


def spreadsheet_text(value):
    text = "" if value is None else str(value)
    if text.lstrip().startswith(("=", "+", "-", "@")) or text.startswith(("\t", "\r")):
        return "'" + text
    return text


def export_results(payload, context, received_at, output_path):
    results = payload.get("organic_results")
    if not isinstance(results, list):
        print("No usable organic_results array; inspect the saved JSON.")
        return
    fields = ["q", "gl", "hl", "received_at", "position", "title", "link", "snippet"]
    with output_path.open("w", encoding="utf-8", newline="") as stream:
        writer = csv.DictWriter(stream, fieldnames=fields)
        writer.writeheader()
        for item in results:
            if not isinstance(item, dict):
                raise ValueError("Unexpected organic result item; inspect the saved JSON.")
            row = {name: item.get(name) for name in ("position", "title", "link", "snippet")}
            row.update(context, received_at=received_at)
            writer.writerow({name: spreadsheet_text(row.get(name)) for name in fields})
    print(f"Exported {len(results)} organic results to {output_path}")


def main():
    context = {"q": "coffee", "gl": "us", "hl": "en"}
    response = requests.post(
        "https://api.scrapeless.com/api/v1/scraper/request",
        headers={"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
        json={"actor": "scraper.google.search", "input": context},
        timeout=120,
    )
    response.raise_for_status()
    received_at = datetime.now(timezone.utc).isoformat()
    run_id = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%fZ")
    payload = response.json()
    record = {"input": context, "received_at": received_at,
              "http_status": response.status_code, "response": payload}
    output = Path(f"google-search-{run_id}.json")
    output.write_text(json.dumps(record, ensure_ascii=False, indent=2), encoding="utf-8")
    if response.status_code == 201:
        print(f"Task pending. Inspect taskId in {output}; no CSV was created.")
        return
    if response.status_code != 200 or not isinstance(payload, dict):
        raise ValueError(f"Unexpected response; inspect {output}")
    export_results(payload, context, received_at, output.with_suffix(".csv"))


if __name__ == "__main__":
    main()

120タイムアウトは、この例におけるクライアント設定であり、サービスの応答時間の約束ではありません。受信時間は、レスポンスが到着した後にクライアントによって記録されます; Googleが提供するタイムスタンプではありません。

PythonのCSVライターは、区切り文字と引用符付きフィールドを処理します。ヘルパーは、エクスポートされたテキスト内の一般的なスプレッドシート数式マーカーにも接頭辞を付けます。JSONは元のレコードとして保持してください; CSVは検査用の変換されたビューです。外部ソースからの値をスプレッドシートで開く前に、テキストインポート設定を確認してください。

この例では、q、gl、およびhlのみが入力からエクスポートされます。場所、ドメイン、またはページネーションオフセットを追加した場合、CSV列を拡張してこれらの次元を保持してください。保存されたJSONには、すでに完全な入力オブジェクトが含まれています。

レポートを作成する前にレスポンスを解釈する

HTTP 200レスポンスにはタスクデータが含まれており、HTTP 201は処理を示し、taskIdを提供します。保留中のタスクは空の結果の観察を生じてはいけません。この場合、スクリプトはJSONレコードを保持し、CSVエクスポートをスキップします。

成功したデータレスポンスに対しては、空の配列を欠如または使用不可能なorganic_resultsフィールドと区別してください。他のモジュールはまだ存在するかもしれません。スクリプトはレスポンスを保持し、使用可能な配列が存在しない場合は検査を求めます。

positionを、取得した結果に対して提供された位置として読み取ります。ページをグローバルランクに結合する前に、エンドポイントがリクエストの位置をどのように番号付けしているかを確認してください。startは結果のオフセットを制御し、ページネーション情報は後続のリクエストを導くことができます; どちらもすべてのGoogle結果を取得できることを確立しません。

構造化検索データを活用する

構造化検索結果は、APIの周りにアプリケーションが構築するワークフローの入力を提供します。便利な単位は、結果とそのリクエストコンテキストおよび観察時間です。

SEOスナップショット: 固定キーワードリストの観察を保存し、それに対して一致するコンテキストを時間をかけて比較します。スケジューリング、ストレージ、および変更検出はあなたのパイプラインに属します。
ブランドおよび競合調査: 選択したクエリに対してどのドメインおよびページタイトルが表示されるかを確認します。このサンプルはその検索を説明しており、すべてのWeb言及やサイトのトラフィックをカバーするものではありません。
AIソース発見: 候補のタイトル、リンク、およびスニペットをソース選択ステップに渡します。証拠が必要な場合は、フルページを別に取得し、生成された主張がそのソースと一致していることを確認します。

コンテンツチームにとって、最初の出力はクエリと市場が添付された短いリーディングリストになる可能性があります。開発者にとっては、既存のレポートで使用される再利用可能なエクスポートになる可能性があります。どちらも、その範囲を可視化するデータレコードから始まります。

これらの例を、収集および使用が許可されている公共情報に使用してください。タスクに必要なフィールドを保持し、資格情報を保護し、ダウンストリーム再利用に適用される条件を確認してください。

結論

Google Search APIは、アプリケーションが扱うための構造化検索データを提供します。便利な統合は、入力を保持し、タスクの状態をチェックし、ソース発見を後の分析から分離します。単一のクエリから始め、ワークフローを拡大する前に保存されたJSONを検査してください。

更新されたGoogle Search APIリクエストワークフローは、この例をあなた自身のプロジェクトに適応するための接続詳細を提供します。

FAQ

Q: これはGoogleが提供するAPIですか？

この記事は、Google Searchデータを取得するためのScrapelessサービスであるScrapeless Google Search APIについて説明しています。公式なGoogleパートナーシップを主張するものではありません。

Q: ブラウザやプロキシを管理する必要がありますか？

管理されたAPIは、サービス側の収集インフラストラクチャを処理します。クライアントはHTTPリクエストを送信し、返されたデータを処理します。

Q: APIには履歴的なランクデータが含まれていますか？
ここで説明されているワークフローは、自身の観察を保存することによって歴史を作ります。既存のランキング履歴を取得するものではありません。

Q: 同じAPIで画像検索はできますか？

この製品は、パラメーターリファレンスにtbm=ischとして特定されているGoogle画像検索をサポートしています。画像レスポンスを別途確認してください；この記事のCSVマッピングはオーガニックウェブ結果用です。

Q: 検索スニペットにはページ全体が含まれていますか？

スニペットは、検索結果に関連した抜粋です。ページの完全な証拠が必要なワークフローは、宛先コンテンツを別途取得して確認する必要があります。

Q: リクエストがHTTP 201を返した場合、何が起こるべきですか？

taskIdを保持し、タスクを保留として扱います。ドキュメント化されたタスク結果ワークフローを完了した後、それを完了した検索データとして処理してください。

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