Google Search Console API の使い方

Q: Google Search Console API の使い方

Cloud プロジェクトの作成、API の有効化、OAuth での認可を行い、検索パフォーマンスデータ、URL 検査、サイトマップを取得します。手順とクォータをまとめました。

Google Cloud コンソールでプロジェクトを作成し、Google Search Console API を有効にして OAuth 2.0 認証情報を作成します。そのうえで、プロパティへのアクセス権を持つ Google アカウントでログインします。これで 4 つのリソースにリクエストを送れるようになります。クリック数、表示回数、CTR、掲載順位を取得する Search Analytics、インデックス状況を調べる URL Inspection、Sitemaps、Sites です。API キーだけでは利用できません。すべての呼び出しに OAuth トークンが必要で、取得できる量にはクォータの上限があります。

API でできること、できないこと

リソース	メソッド	用途
Search Analytics	`query`	クエリ、ページ、国、デバイス、検索での見え方、日付、時間帯ごとのパフォーマンス行
URL Inspection	`index.inspect`	1 つの URL のインデックス済みバージョン(カバレッジ、前回のクロール、canonical)
Sitemaps	`list`、`get`、`submit`、`delete`	プロパティに送信済みのサイトマップの管理
Sites	`list`、`get`、`add`、`delete`	ログイン中のアカウントに紐づくプロパティ

API の範囲はこれがすべてです。リンク、クロールの統計情報、ページのインデックス登録レポート、ウェブに関する主な指標レポートにはエンドポイントがないため、Search Console の画面でしか確認できません。また、URL Inspection が返すのは Google のインデックスに登録されている内容であり、ページのライブテストではありません。

アクセスの設定

Google Cloud コンソールで、プロジェクトを作成するか既存のものを選びます。
そのプロジェクトで Google Search Console API を有効にします。
OAuth 同意画面を設定し、OAuth クライアント ID を作成します。
スコープを指定します。読み取りだけなら https://www.googleapis.com/auth/webmasters.readonly、サイトマップの送信や削除も行うなら https://www.googleapis.com/auth/webmasters です。
プロパティに対する権限を持つアカウントでログインします。パフォーマンスデータの読み取りには、少なくとも閲覧権限が必要です。API で見えるのは、そのアカウントで見えるものとまったく同じ範囲です。

最初の Search Analytics クエリ

POST https://www.googleapis.com/webmasters/v3/sites/sc-domain%3Aexample.com/searchAnalytics/query
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "startDate": "2026-09-01",
  "endDate": "2026-09-30",
  "dimensions": ["query", "page"],
  "type": "web",
  "rowLimit": 25000,
  "startRow": 0
}

サイトはパスに URL エンコードして指定します。ドメインプロパティなら sc-domain:example.com、URL プレフィックスプロパティなら末尾のスラッシュを含む https://www.example.com/ のような正確なプレフィックスです。特に重要なフィールドは次のとおりです。

日付は開始日・終了日ともに含まれ、太平洋時間で扱われます。
type の既定値は web です。ほかに image、video、news、googleNews、discover があり、それぞれ個別のリクエストが必要です。
フィルタは dimensionFilterGroups に指定します。演算子は equals や contains から includingRegex、excludingRegex(RE2 構文)まで使えます。
rowLimit は 1 から 25,000 まで(既定値は 1,000)で、残りの行は startRow でページ送りして取得します。
dataState の既定値は final です。all を指定すると集計が確定していない最新の日も含まれ、hourly_all は hour ディメンションと組み合わせて使います。

各行は keys、clicks、impressions、ctr(0 から 1)、position を返します。日付でグループ化しない限り、クリック数の降順で並びます。

コードの設計に影響する上限

検索タイプごとに 1 日あたり 50,000 行。 startRow を 25,000 ずつ進めてページ送りし、空のレスポンスが返ったら終了します。最大限のデータを得るには、1 日ずつクエリを実行します。
負荷クォータ。 ページとクエリの両方でグループ化またはフィルタするリクエストは最も負荷が高く、期間が長いほどコストも増えます。短期クォータを超えると、Google から 15 分間待つよう求められます。
リクエストレート。 サイトごと・ユーザーごとに 1 分あたり 1,200 クエリ、プロジェクトごとに 1 分あたり 40,000 クエリ、1 日あたり 30,000,000 クエリです。
URL Inspection のクォータ。 プロパティごとに 1 日 2,000 件、1 分あたり 600 件の検査が可能です。
履歴は 16 か月分。 データは通常、その日が終わってから 2〜3 日後に利用可能になります。
行の合計は全体の値と一致しません。 まれなクエリはクエリ単位の行から除外されます。また、ページでグループ化した場合は、プロパティでグループ化した場合と表示回数の数え方が異なります。合計値は、query ディメンションを含まないリクエストから読み取ってください。

よくある間違い

プロパティが https:// なのに http:// を使った場合や、末尾のスラッシュを付け忘れた場合は、アカウントにアクセス権があっても権限エラーになります。
URL Inspection でプロパティ外の URL を指定すると拒否されます。URL は、渡した siteUrl の配下にある必要があります。
1 か月分をクエリとページでグループ化して 1 回で取得すると、上位の行しか返りません。日単位でリクエストすると、より多くの行を取得できます。

AutoPSEO でできること

OAuth やページ送りの実装・保守を避けたい場合は、AutoPSEO が便利です。AutoPSEO は Google ログインで接続し、同じデータを独自の REST API(/v1、OpenAPI 3.1 ドキュメント付き)と MCP サーバーから提供します。認可には Account → API keys で発行する API キーを使います。読み取り専用キーも用意されており、検索アナリティクスのエンドポイントは 1 回の呼び出しで最大 5,000 行を返します。また、アプリ内の URL Inspection ツールは、Google の 1 日 2,000 件というクォータの消費数を代わりに管理します。詳しくは MCP と API キーをご覧ください。パイプラインを自作せずに 16 か月より長くデータを保管する方法については、Search Console のデータ保持期間をご覧ください。

参考資料: Google の API リファレンス、Search Analytics の query メソッド、使用上の制限、すべてのデータを取得する、認可ガイド。