Community研究&データ分析github.com

google-search-console-api

Google Search Console API(searchconsole v1 / webmasters v3)を使用して、検索アナリティクスクエリ、URL検査、サイトマップ、サイト管理をクォータ範囲内で行います。「Search Consoleデータを取得」「GSCパフォーマンスデータをエクスポート」「ページ/クエリ別のクリック数/インプレッション数/CTR/掲載順位を取得」「GSCパイプラインやダッシュボードを構築」「1,000行/25,000行以上のデータを取得」「APIでURLを検査/インデックス状況を確認」「一括URL検査」「APIでサイトマップを送信」「Search Consoleプロパティ一覧」などのタスクや、Search Console APIの「quota exceeded」エラー、403エラー、「User does not have sufficient permission」エラーのデバッグに利用します。

google-search-console-api とは?

このスキルは、Google Search Console API(searchconsole v1 / webmasters v3)を操作するための包括的なガイドです。主な対象は、検索アナリティクス(パフォーマンスレポート)、URL検査、サイトマップ、サイト(プロパティ)の4つのサービスで、OAuth 2.0認証が必要です。最も重要なのはクォータ管理であり、特に検索アナリティクスの負荷クォータは、日付範囲の長さやpage/queryディメンションの使用によって消費量が変動します。このスキルは、1日1日ずつクエリするパターンや25,000行ずつのページネーションなど、完全かつ正確なデータをクォータ内で取得するための推奨手法を詳述しています。また、URL検査の1日あたり2,000件という実質的な上限など、各サービスのクォータ制限についても説明しています。さらに、プロパティ識別子(siteUrl)の正しい形式、認証設定手順、エラーハンドリング、パフォーマンス最適化(gzip、部分応答、HTTPバッチ)についてもカバーしており、Google Search Consoleのデータパイプラインやダッシュボードを構築する開発者にとって必須のリファレンスです。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/nimajafari/google-search-console-api-skill/tree/main/skills/google-search-console-api

Installed? Explore more 研究&データ分析 skills: affaan-m/uspto-database, affaan-m/scholar-evaluation, affaan-m/literature-review · View all 6 →

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

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 Analyticssearchanalytics.queryPOST /webmasters/v3/sites/{siteUrl}/searchAnalytics/querywebmasters.readonly
URL InspectionurlInspection.index.inspectPOST /v1/urlInspection/index:inspectwebmasters.readonly
Sitemapslist / getGET /webmasters/v3/sites/{siteUrl}/sitemaps[/{feedpath}]webmasters.readonly
Sitemapssubmit / deletePUT / DELETE …/sitemaps/{feedpath}webmasters
Siteslist / getGET /webmasters/v3/sites[/{siteUrl}]webmasters.readonly
Sitesadd / deletePUT / 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の「すべてのデータ」ガイドより)

  1. まず最新性を確認する。 過去約10日間を date のみでグループ化してクエリします — フィルターや他のディメンションはなし。データがない日は単に結果に含まれません。最終データは通常 2~3日 遅れます。
  2. 1日ずつクエリする(startDate == endDate)、必要な各 type に対して1日1回。1日単位のクエリは日次クォータを超えるべきではありません。16か月の範囲を page+query でグループ化すると超えます。
  3. 結果をページネーションする: rowLimit は最大 25,000(デフォルト 1,000)、startRow を 25,000 ずつ増やし、ページが リクエストした行数より少ない行 または 0行 を返すまで続けます。
  4. 確定した履歴を再取得しない。 保存してください。新しい日のみを取得します(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、googleCanonical vs userCanonical、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

  1. Google Cloud プロジェクトを作成/選択 → Google Search Console API を有効化。
  2. 認証情報を選択:
    • インストール済み/デスクトップ OAuth クライアント: ローカルでスクリプトを実行する人間用。ユーザーがブラウザで同意し、リフレッシュトークンを保存します。
    • サービスアカウント: 無人ジョブ用。次に、Search Console でサービスアカウントのメールアドレスをプロパティのユーザーとして追加します(設定 → ユーザーと権限)。読み取りには制限付きで十分です。書き込みにはオーナー/フルが必要です。この手順がないと、すべての呼び出しで 403 が返されます。
    • API キーはこれらのリソースでは受け入れられません。OAuth 2.0 が唯一のサポートされるプロトコルです。
  3. クライアントライブラリを使用することを推奨 — 例: Python google-api-python-client の build("searchconsole", "v1", credentials=creds)、Node googleapis の 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、userRateLimitExceededQPS/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 も参照してください。

関連スキル