SERP API

認証付き POST 1 回でキーワードのリアルタイム構造化 Google SERP 結果を取得——順位、タイトル、URL、タイプ——デバイス、地域、言語パラメータ付き。

単一 REST エンドポイント
正確な市場ターゲティング
デバイスとブラウザの忠実度
構造化された結果項目
冪等な課金書き込み
予測可能なエラーコード

リクエスト例

curl -X POST "https://api.agentbody.io/v1/seo/google-serp" \
  -H "Authorization: Bearer <YOUR_AGENTBODY_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"browser_screen_density":"1","browser_screen_height":"1","browser_screen_resolution":"YOUR_BROWSER_SCREEN_RESOLUTION","browser_screen_width":"1","calculate_rectangles":"true","depth":"1","device":"desktop","keyword":"YOUR_KEYWORD","language_code":"YOUR_LANGUAGE_CODE","language_name":"YOUR_LANGUAGE_NAME","load_async_ai_overview":"true","location_code":"1","location_coordinate":"YOUR_LOCATION_COORDINATE","location_name":"YOUR_LOCATION_NAME","os":"windows","se_domain":"YOUR_SE_DOMAIN","search_param":"YOUR_SEARCH_PARAM"}'

レスポンス例

OpenAPI 仕様に記載されたレスポンス。

Organic search results.

{
  "items": [],
  "items_count": 0,
  "keyword": "example_value"
}

機能特徴

SERP API を使ってキーワードのリアルタイム構造化 Google 結果を取得します。デバイス、地域、言語、ドメインのパラメータを備え、順位トラッカー、SEO ツール、データパイプラインに対応します。

単一 REST エンドポイント

bearer API キーとキーワードを付けて POST /v1/seo/google-serp を呼び出します。SERP API は検索をリアルタイムで実行し、結果ページを構造化 JSON として返します。ブラウザのホストもプロキシのローテーションもパーサーの維持もなしに、アプリケーションは順位を取得できます。

正確な市場ターゲティング

location_name、location_code、または location_coordinate に言語と Google の se_domain を組み合わせ、各リクエストを市場に固定します。順位は地理と言語で変動します。これらのパラメータは、製品がトラッキングする市場に対して毎回のリクエストを再現可能にします。

デバイスとブラウザの忠実度

device をデスクトップまたはモバイルに設定し、任意で検索の実行時のブラウザ画面サイズを指定できます。SERP のレイアウトと特集範囲はデバイスクラスで異なります。API はこれらのノブを公開し、データをユーザーの実際の検索方法に合わせます。

構造化された結果項目

順位、タイトル、URL、結果タイプ付きの順序づけられた項目と、depth や calculate_rectangles などのより深いパース制御を受け取ります。スキーマは保存のために設計されています。項目をそのまま順位トラッキングテーブルや分析パイプラインに落とし込めます。

冪等な課金書き込み

リアルタイムの SERP リクエストは従量課金の操作です。再試行時に Idempotency-Key ヘッダーを送ると、中断されたレスポンスが二重に課金される検索になりません。ゲートウェイは同じキーを持つ同一の繰り返しリクエストを 1 回として扱います。

予測可能なエラーコード

ドキュメント化されたステータスコードで失敗を処理します。400 は無効なリクエスト、401 は API キーの不足または誤り、402 は残高不足、502、503、504 は一時的な上流の問題です。各クラスは明確な修正または再試行アクションに対応します。

使い方

次の 6 ステップで SERP API を呼び出します。キーを作成し、キーワードと市場パラメータで POST リクエストを構築し、構造化された結果を処理します。

API キーを作成

AgentBody アカウントを作成し、コンソールで API キーを生成します。キーはサーバー環境または承認されたシークレットストアに保管し、bearer トークンとして送信します。本番キーをブラウザコードやクライアントバンドルに置かないでください。

リクエストボディを構築

必須の keyword と選択したオプション——device、location、language、se_domain、depth——を付けて /v1/seo/google-serp に POST を送信します。このページの生成例は、curl、JavaScript、Python、Java、Go での正確なリクエストを示します。

冪等キーを追加

再試行する可能性のあるすべての検索に Idempotency-Key ヘッダーを付けます——タイムアウト、接続切断、ワーカーの再起動。繰り返されたキーに対してゲートウェイは元のレスポンスを返し、同一の検索を再実行して課金することはありません。

キーはサーバー側に

バックエンド、サーバーレス関数、または定期ジョブからエンドポイントを呼び出します。API キーがブラウザに出ない場所ならどこでも構いません。エンドユーザーがチェックをトリガーする場合は、独自のエンドポイントでプロキシし、キーと課金を自分の管理下に置いてください。

JSON レスポンスをパース

順位、タイトル、URL、タイプのフィールドを持つ順序づけられた項目を読み取ります。トラッカーに必要なものを保存し、各行にリクエストの市場パラメータのタグを付けます。初日から再現可能な順位系列が手に入ります。

エラーを正しく処理

400 はリクエストボディを修正し、401 は有効なキーを設定し、402 は残高を補充します。502、503、504 はバックオフ付きで同じ冪等キーの下で再試行してください。これらは永続的な失敗ではなく、一時的な上流の状態です。

よくある質問

この SERP API とは何ですか？

SERP API は認証付きの POST エンドポイント /v1/seo/google-serp です。キーワードに対してリアルタイムの Google 検索を実行し、結果ページを構造化 JSON——順位、タイトル、URL、結果タイプ付きの順序づけられた項目——として返します。市場に正確なデータのためのデバイス、地域、言語のコントロールも備えます。

SERP API の料金はどうなっていますか？

毎回のリアル検索はアカウントのクレジットで実行される従量課金の操作です。従量課金の価格はこのページの固定数値ではなくゲートウェイが管理します。コンソールで現在の 1 回あたりのコストを確認し、再試行が二重課金にならないよう冪等キーを使ってください。

Google SERP API スクレイパーの自作と比べてどうですか？

SERP API スクレイパー——ヘッドレスブラウザ、プロキシのローテーション、CAPTCHA 対応、レイアウト変更で壊れるパーサー——を維持する代わりに、ドキュメント化された 1 つの REST エンドポイントを呼び出して安定した JSON フィールドを受け取ります。API がインフラを吸収し、契約を安定に保ちます。

特定の国や都市の結果を取得できますか？

はい。リクエストボディに location_name、location_code、または location_coordinate を渡します。検索はその市場に対して実行され、返される順位はそこで検索する人が見るものを反映します。ローカル順位トラッキングの中核です。

Google.com 以外のドメインと他の言語に対応していますか？

se_domain を市場が使う Google ドメインに設定し、language_name または language_code で検索言語を指定します。地域オプションと組み合わせることで、毎回のリクエストは再現可能な市場設定に固定されます。

API エラーの処理方法は？

400 はリクエストボディを修正し、401 は bearer キーを修正し、402 は残高を解決します。502、503、504 は一時的な上流の障害として、同じ冪等キーの下でバックオフ付きで再試行してください。ステータスコードをログに残し、パイプラインが不良リクエストと一時的な問題を区別できるようにします。