Google Search Console API
Search Console API は、Google Search Console のほとんどの機能(パフォーマンスレポート(検索アナリティクス)、URL検査、サイトマップ、プロパティ一覧(サイト))へのプログラムによるアクセスを提供します。REST/JSON API であり、すべての呼び出しに OAuth 2.0 と、Search Console でプロパティに対する権限を持つユーザー(またはサービスアカウント)が必要です。
難しいのは呼び出しそのものではありません。クォータを超えずに完全で正確なデータを取得すること です。このスキルの大部分はこれに関するものです。
このスキルを使用するタイミング
- 分析、ダッシュボード、データウェアハウジング、SEO調査のためにパフォーマンスデータ(クリック数、インプレッション数、CTR、掲載順位)を抽出する場合。
- インデックスステータス、正規URLの選択、robots/noindex 状態、リッチリザルトの有効性を URL 単位で大規模に確認する場合。
- プロパティと権限の一覧表示、サイトマップの一覧表示または送信を行う場合。
- スケジュールされた同期ジョブを設計する場合、または
quotaExceededに達したり、行が欠落したり、UI と一致しない数値が返されるジョブを修正する場合。
このAPIでカバーされないもの: ページインデックス(カバレッジ)レポート、リンク、Core Web Vitals、クロール統計、手動対策、削除、および「インデックス登録をリクエスト」ボタン。Core Web Vitals フィールドデータには CrUX API を、大規模サイトの生のパフォーマンスデータの一括エクスポートには Search Console の BigQueryへの一括データエクスポート を使用してください。独立した Indexing API は JobPosting / BroadcastEvent ページのみをサポートします。
4つのサービス
| サービス | メソッド | HTTP | スコープ(最小) |
|---|---|---|---|
| Search Analytics | searchanalytics.query | POST /webmasters/v3/sites/{siteUrl}/searchAnalytics/query | webmasters.readonly |
| URL Inspection | urlInspection.index.inspect | POST /v1/urlInspection/index:inspect | webmasters.readonly |
| Sitemaps | list / get | GET /webmasters/v3/sites/{siteUrl}/sitemaps[/{feedpath}] | webmasters.readonly |
| Sitemaps | submit / delete | PUT / DELETE …/sitemaps/{feedpath} | webmasters |
| Sites | list / get | GET /webmasters/v3/sites[/{siteUrl}] | webmasters.readonly |
| Sites | add / delete | PUT / DELETE /webmasters/v3/sites/{siteUrl} | webmasters |
ルート URL: https://searchconsole.googleapis.com/ (現在のディスカバリドキュメント、サービス searchconsole v1)。古い https://www.googleapis.com/webmasters/v3/... パスも Google のドキュメント全体にまだ出現しており、webmasters/v3 リソースに対しては引き続き機能します。
スコープ: https://www.googleapis.com/auth/webmasters.readonly(読み取り専用)および https://www.googleapis.com/auth/webmasters(読み取り/書き込み)。タスクが本当にサイトマップの送信/削除やサイトの追加/削除を行わない限り、読み取り専用 をリクエストしてください。
プロパティ識別子(siteUrl) — 403/404 エラーの最大の原因
- ドメインプロパティ:
sc-domain:example.com - URLプレフィックスプロパティ:
https://www.example.com/— スキーム、ホスト、および 末尾のスラッシュ が Search Console のものと正確に一致する必要があります。 - パス内では、
siteUrlとfeedpathは 完全にURLエンコード する必要があります(https%3A%2F%2Fwww.example.com%2F、sc-domain%3Aexample.com)。クライアントライブラリはこれを自動で行いますが、生の HTTP では行いません。 - 常に
sites.listを呼び出し、返されたものとまったく同じsiteUrlを使用してください。siteUnverifiedUserはデータを読み取れません。
クォータ — ループを書く前に必ず読んでください
詳細と予算計算シート: references/LIMITS.md
Search Analytics
- QPM 制限: サイトあたり 1,200 QPM、ユーザーあたり 1,200 QPM、プロジェクトあたり 40,000 QPM および 30,000,000 QPD。例: 1人のユーザーが3つのサイトにアクセスする場合、合計で 1,200 QPM。1つのサイトに2人のユーザーがいる場合、1,200 QPM を共有します。
- 負荷クォータ(実際に影響するもの): クエリの内部コスト。10分(短期) と 1日(長期) のウィンドウで追跡されます。コストは以下によって増加します:
pageまたはqueryによるグループ化/フィルタリング(両方を同時に行うと最も高コスト)、- 日付範囲の長さ(6か月 ≫ 1日)、
- 既に取得したデータの再クエリ。
- これらのいずれかを超えると、同じ
quotaExceededエラーが返されます。短期: 15分 待ってから再試行してください。10分間のウィンドウ内で単一のクエリが依然として失敗する場合、長期(日次)負荷クォータを超えています — コストを削減してください。再試行は翌日まで効果がありません。
URL Inspection: サイトあたり 2,000 QPD および 600 QPM。プロジェクトあたり 10,000,000 QPD および 15,000 QPM。プロパティあたり1日2,000件が実際の上限です — サンプリングを計画し、「すべてのURLを検査する」ことは計画しないでください。
その他すべて(サイト、サイトマップ): ユーザーあたり 20 QPS および 200 QPM。プロジェクトあたり 100,000,000 QPD。
バッチ処理でクォータは節約できません: n 回の呼び出しのバッチは n リクエストとしてカウントされます。バッチ処理は HTTP オーバーヘッドのみを節約します。現在の使用状況: Google Cloud コンソール → APIs & Services → Search Console API → Quotas。
Search Analytics: 完全で正確なデータを取得する
完全なリクエスト/レスポンススキーマとレシピ: references/SEARCH-ANALYTICS.md
推奨パターン(Googleの「すべてのデータ」ガイドより)
- まず最新性を確認する。 過去約10日間を
dateのみでグループ化してクエリします — フィルターや他のディメンションはなし。データがない日は単に結果に含まれません。最終データは通常 2~3日 遅れます。 - 1日ずつクエリする(
startDate == endDate)、必要な各typeに対して1日1回。1日単位のクエリは日次クォータを超えるべきではありません。16か月の範囲を page+query でグループ化すると超えます。 - 結果をページネーションする:
rowLimitは最大 25,000(デフォルト 1,000)、startRowを 25,000 ずつ増やし、ページが リクエストした行数より少ない行 または 0行 を返すまで続けます。 - 確定した履歴を再取得しない。 保存してください。新しい日のみを取得します(
dataState: "all"を使用する場合は、最近の未確定日を再取得することもあります)。
POST https://searchconsole.googleapis.com/webmasters/v3/sites/sc-domain%3Aexample.com/searchAnalytics/query
{
"startDate": "2026-11-14",
"endDate": "2026-11-14",
"dimensions": ["page", "query", "country", "device"],
"type": "web",
"rowLimit": 25000,
"startRow": 0
}
関係者に説明しなければならない厳格なデータ制限
- API は すべての行ではなく、上位の行 を返します: 検索タイプごとに1日あたり最大 50,000行(クリック数でソート)。ページネーションに関係なく。
pageやqueryによるグループ化/フィルタリングは 一部のデータを削除 し(計算範囲を限定するため)、匿名化された稀なクエリは決して返されません。したがって、行の合計 < プロパティの合計 となります。正確な合計を取得するには、page/queryディメンションなしでクエリしてください。- 合計は 集計方法 によって異なります:
byProperty(プロパティごとに重複排除)とbyPage(正規URLごと)。pageでグループ化またはフィルタリングする場合、byPropertyは使用できません —autoを使用してください。 - 日付は 太平洋時間(
America/Los_Angeles)であり、UTC ではありません。 - Search Console のパフォーマンスデータの保持期間は約16か月です。それ以上の履歴が必要な場合は永続化してください。
正しいメトリクスの計算
- グループの CTR =
sum(クリック数) / sum(インプレッション数)。CTR を平均しないでください。 - グループの 掲載順位 = インプレッション加重:
sum(掲載順位 × インプレッション数) / sum(インプレッション数)。掲載順位を平均しないでください。 positionは1ベースの平均最上位位置。低いほど良い。
主要なリクエストフィールド(クイックリファレンス)
dimensions:date,hour,query,page,country(ISO 3166-1 alpha-3、結果では小文字、例:usa)、device(DESKTOP/MOBILE/TABLET)、searchAppearance、brandedClassification。type:web(デフォルト)、image、video、news(ニュースタブ)、googleNews(news.google.com + アプリ)、discover、webMultimodal(Lens / Circle to Search / 画像アップロード)。searchTypeは非推奨のエイリアスです。dimensionFilterGroups[].filters[]:{dimension, operator, expression}。演算子:equals(デフォルト、page/query では大文字小文字を区別)、notEquals、contains、notContains、includingRegex、excludingRegex(RE2)。グループは AND 結合されます。groupType: "and"のみがサポートされています。dimensionFilterGroups[].filterLists[]:country/deviceの複数値完全一致({"dimension":"country","expressions":["usa","can"]})。同じディメンションをfiltersとfilterListsの両方でフィルタリングすることはできません。aggregationType:auto(デフォルト)、byPage、byProperty(discover/googleNewsでは不可)、byNewsShowcasePanel。dataState:final(デフォルト)、all(最新の未確定データを含む)、hourly_all(hourディメンションに必須、約10日間利用可能)。レスポンスのmetadata.firstIncompleteDate/firstIncompleteHourは、数値がまだ変更される可能性がある場所を示します。
注意点
- 検索表示は2段階:
searchAppearanceを唯一のディメンションとしてクエリし、タイプを一覧表示してから、searchAppearance equals <TYPE>でフィルタリングし、他のディメンションを追加します — タイプごとに1クエリ。 brandedClassification(BRANDED/NON_BRANDED):equalsのみ。同じリクエスト内でqueryフィルターと組み合わせることはできません。2026-02-21 以降のデータで、十分なボリュームがあるトップレベルのプロパティのみ。- 結果は クリック数の降順 でソートされます。ただし、
dateでグループ化する場合(日付昇順)は例外です。同点は任意です — 重複排除のために順序に依存しないでください。 - 範囲外の
startRowは、エラーではなく 200 と 0行 を返します。データがちょうど 25,000 の境界にある場合、空の次のページが返されます。 rowsは、データがない場合は 存在しません([]ではありません)。
URL Inspection
完全なスキーマ、列挙型、トリアージテーブル: references/URL-INSPECTION.md
POST https://searchconsole.googleapis.com/v1/urlInspection/index:inspect
{ "inspectionUrl": "https://www.example.com/page", "siteUrl": "sc-domain:example.com", "languageCode": "en-US" }
- インデックス登録された バージョンのみを報告します。ライブ URL をテストしたり、インデックス登録をリクエストしたりすることはできません。
inspectionUrlはsiteUrlの配下にある必要があります。indexStatusResultを読み取ります:verdict(PASS = 有効、NEUTRAL = 除外、FAIL = エラー)、coverageState(人間が読める文字列、例: 「送信済み、インデックス登録済み」)、robotsTxtState、indexingState、pageFetchState、lastCrawlTime、googleCanonicalvsuserCanonical、crawledAs。- 最も有用な一括シグナルは
googleCanonical != userCanonical(Googleが異なる正規URLを選択した)です。 mobileUsabilityResultは 非推奨 です。ampResult/richResultsResultは該当しない場合には存在しません。- 予算: 2,000/日/プロパティ。サンプルを優先: クリック数が多いトップページ、最近変更されたテンプレート、テンプレート/パターンごとに1つのURL、新しいサイトマップのURL。
Sites と Sitemaps
references/SITES-AND-SITEMAPS.md を参照してください。sites.list → siteEntry[] {siteUrl, permissionLevel}。siteOwner / siteFullUser / siteRestrictedUser / siteUnverifiedUser があります。sitemaps.list → sitemap[]。path、lastSubmitted、lastDownloaded、isPending、isSitemapsIndex、type、errors、warnings、contents[].submitted を含みます(contents[].indexed は非推奨 — 報告しないでください)。submit / delete は本文を必要とせず、読み取り/書き込みスコープが必要です。これらは書き込み操作です。呼び出す前にユーザーに確認してください。
認証とセットアップ
各言語のライブラリインストール行を含むステップバイステップ: references/AUTH-AND-SETUP.md
- Google Cloud プロジェクトを作成/選択 → Google Search Console API を有効化。
- 認証情報を選択:
- インストール済み/デスクトップ OAuth クライアント: ローカルでスクリプトを実行する人間用。ユーザーがブラウザで同意し、リフレッシュトークンを保存します。
- サービスアカウント: 無人ジョブ用。次に、Search Console でサービスアカウントのメールアドレスをプロパティのユーザーとして追加します(設定 → ユーザーと権限)。読み取りには制限付きで十分です。書き込みにはオーナー/フルが必要です。この手順がないと、すべての呼び出しで 403 が返されます。
- API キーはこれらのリソースでは受け入れられません。OAuth 2.0 が唯一のサポートされるプロトコルです。
- クライアントライブラリを使用することを推奨 — 例: Python
google-api-python-clientのbuild("searchconsole", "v1", credentials=creds)、Nodegoogleapisのgoogle.searchconsole("v1")。
from google.oauth2 import service_account
from googleapiclient.discovery import build
creds = service_account.Credentials.from_service_account_file(
"sa.json", scopes=["https://www.googleapis.com/auth/webmasters.readonly"])
gsc = build("searchconsole", "v1", credentials=creds, cache_discovery=False)
resp = gsc.searchanalytics().query(siteUrl="sc-domain:example.com", body={
"startDate": "2026-11-14", "endDate": "2026-11-14",
"dimensions": ["page"], "rowLimit": 25000, "startRow": 0,
}).execute()
rows = resp.get("rows", []) # 空の場合は存在しません
トークン、クライアントシークレット、サービスアカウントキーを出力、ログ記録、コミットしないでください。
エラーとリトライ
完全なマップ: references/ERRORS.md
| 症状 | 原因 | アクション |
|---|---|---|
401 authError / expired | トークンが無効/期限切れ | トークンをリフレッシュ。スコープを確認。 |
403 insufficientPermissions / "User does not have sufficient permission for site" | siteUrl の形式が間違っている、またはプリンシパルがプロパティのユーザーではない | sites.list を実行し、正確な siteUrl を使用。Search Console でサービスアカウントを追加。 |
403 accessNotConfigured | プロジェクトで API が有効になっていない | Search Console API を有効化。 |
403/429 rateLimitExceeded、userRateLimitExceeded | QPS/QPM | ジッターを含む指数バックオフ。 |
403/429 quotaExceeded(Search Analytics) | 負荷クォータ | 1回だけ15分待機。単独のクエリがまだ失敗する場合 → 長期負荷: 日付範囲を短縮するか、page/query を削除し、翌日再開。 |
400 invalidParameter / badRequest | 無効な列挙型、日付の順序、同じディメンションでの filters/filterLists の混在、page での byProperty | リクエストを修正。再試行しない。 |
500 / 503 backendError | 一時的な問題 | バックオフして再試行(上限あり)。 |
パフォーマンス
references/BATCH-AND-PERFORMANCE.md: gzip(Accept-Encoding: gzip および gzip を含む User-Agent)、fields= による部分応答(例: fields=rows(keys,clicks,impressions))、HTTP バッチ(multipart/mixed、最大1,000呼び出し、任意の順序で実行、各呼び出しは依然としてクォータにカウントされます)。
ヘルパースクリプト
scripts/gsc.py は、Python 3.9+ 標準ライブラリのみを使用する単一ファイルの CLI です。進行状況を stderr に書き込み、データを stdout に書き出します(デフォルトは JSONL、または CSV/JSON)。ページネーション、スリープ、リトライ、日付の反復処理を自動で行います。scripts/gsc.py --help を参照してください。また、scripts/README.md も参照してください。