google-search-console

Google Search Console

アーキテクチャ

gsc は、2 つの Google API をラップする Python CLI です。

• Search Console API（webmasters v3 + searchconsole v1） -- 検索アナリティクス、サイト管理、サイトマップ、URL 検査
• PageSpeed Insights API（v5） -- パフォーマンス、アクセシビリティ、SEO、ベストプラクティスに関する Lighthouse のラボテスト

すべてのコマンドは JSON を標準出力に出力します。エラーは標準エラー出力に出力されます。Claude がプログラムで呼び出して解析できるように設計されています。

初回使用前

1. uv：which uv を実行します。見つからない場合は、インストール方法をユーザーに確認してください（brew install uv または https://docs.astral.sh/uv/getting-started/installation/ を参照）。
2. プロジェクトの同期：uv sync --project <skill-dir>
3. 認証：以下を参照してください。
4. PageSpeed API キー：以下を参照してください。

Search Console の認証（OAuth）

GCP からダウンロードした OAuth client_secret.json を既知のパスに保存し、認証します。

gsc auth login --client-secret /path/to/client_secret.json

OAuth の同意画面を開くブラウザーが起動します。ヘッドレスマシンでは、先に SSH トンネルを開きます：ssh -L 8085:localhost:8085 <this-host>。その後、ブラウザーを使用できるマシンで表示された URL を開きます。認証情報は ~/.config/skills/gsc/credentials.json に保存され、自動的に更新されます。

新しい OAuth クライアントを作成する必要がある場合は、GCP の操作手順全体を記載した references/setup.md を参照してください。

PageSpeed Insights API キー

キーを一度設定すると、gsc が記憶します。

gsc config set pagespeed-api-key <your-key>

キーをお持ちでない場合は、GCP プロジェクトの Credentials ページで作成し、「PageSpeed Insights API」に限定して、上記の gsc config set に渡してください。

呼び出し

uv run --project /path/to/skills/google-search-console gsc <command> [args]

簡潔にするため、以下の例では gsc を直接使用します。

コマンド

auth -- 認証を管理

# Authenticate with OAuth
gsc auth login --client-secret ./client_secret.json --port 8085

# Check auth status
gsc auth status

# Remove stored credentials
gsc auth logout

config -- 設定を管理

# Set PageSpeed API key
gsc config set pagespeed-api-key AIza...

# Get a config value
gsc config get pagespeed-api-key

# Show all config (secrets masked)
gsc config show

query -- 検索アナリティクス

# Basic query: clicks, impressions, CTR, position for last 7 days
gsc query sc-domain:example.com -s 2026-03-01 -e 2026-03-07

# Group by query keyword
gsc query sc-domain:example.com -s 2026-03-01 -e 2026-03-07 -d query

# Group by page and query
gsc query sc-domain:example.com -s 2026-03-01 -e 2026-03-07 -d page -d query

# Daily breakdown
gsc query sc-domain:example.com -s 2026-03-01 -e 2026-03-07 -d date

# Filter by query containing "pricing"
gsc query sc-domain:example.com -s 2026-03-01 -e 2026-03-07 -d query --query-filter pricing

# Exact match filter
gsc query sc-domain:example.com -s 2026-03-01 -e 2026-03-07 --query-filter "=best coffee shop"

# Mobile only
gsc query sc-domain:example.com -s 2026-03-01 -e 2026-03-07 --device-filter "=MOBILE"

# Image search
gsc query sc-domain:example.com -s 2026-03-01 -e 2026-03-07 --search-type image

# Paginate results
gsc query sc-domain:example.com -s 2026-03-01 -e 2026-03-07 --row-limit 5000 --start-row 0

フィルターの接頭辞演算子：= は完全一致、! は含まない、接頭辞なしまたは ~ は部分一致です。

inspect -- URL 検査

gsc inspect sc-domain:example.com https://example.com/page
gsc inspect https://example.com/ https://example.com/page --language en-US

返される情報：インデックス登録の判定、クロール情報、正規 URL、モバイルユーザビリティ、リッチリザルトのステータス。

sites -- プロパティを管理

gsc sites list
gsc sites get sc-domain:example.com
gsc sites add https://example.com/

sitemaps -- サイトマップを管理

gsc sitemaps list sc-domain:example.com
gsc sitemaps get sc-domain:example.com https://example.com/sitemap.xml
gsc sitemaps submit sc-domain:example.com https://example.com/sitemap.xml
gsc sitemaps delete sc-domain:example.com https://example.com/sitemap.xml

pagespeed -- PageSpeed Insights

# Mobile performance (default)
gsc pagespeed https://example.com

# Desktop, all categories
gsc pagespeed https://example.com --strategy desktop \
  --category performance --category accessibility --category seo --category best-practices

# Specific locale
gsc pagespeed https://example.com --locale fr

API キーが必要です：gsc config set pagespeed-api-key <key>。ラボテストには 30～60 秒かかります。

サイト URL の形式

Google Search Console では、2 種類のプロパティがサポートされています。

種類	形式	例	対象範囲
ドメイン プロパティ	sc-domain:example.com	sc-domain:example.com	すべてのサブドメイン、プロトコル、パス
URL プレフィックス プロパティ	https://example.com/	https://example.com/	プレフィックスの完全一致のみ

可能であればドメイン プロパティを使用してください。すべてのバリエーションが対象になります。

よくあるワークフロー

週次パフォーマンスチェック

# This week vs last week, grouped by date
gsc query sc-domain:example.com -s 2026-03-05 -e 2026-03-11 -d date
gsc query sc-domain:example.com -s 2026-02-26 -e 2026-03-04 -d date

# Top queries by clicks
gsc query sc-domain:example.com -s 2026-03-05 -e 2026-03-11 -d query --row-limit 25

インデックス登録状況のチェック

# Check if key pages are indexed
gsc inspect sc-domain:example.com https://example.com/important-page
gsc inspect sc-domain:example.com https://example.com/new-blog-post

# Verify sitemap coverage
gsc sitemaps list sc-domain:example.com
gsc sitemaps get sc-domain:example.com https://example.com/sitemap.xml

CTR の最適化

# Find high-impression, low-CTR queries (position 3-10)
gsc query sc-domain:example.com -s 2026-02-10 -e 2026-03-11 -d query -d page --row-limit 5000

# Filter results to find optimization opportunities:
# Look for rows where impressions > 100 and position between 3-10 but CTR < 3%

デバイスの比較

gsc query sc-domain:example.com -s 2026-03-01 -e 2026-03-07 -d device

Core Web Vitals のチェック

gsc pagespeed https://example.com --strategy mobile
gsc pagespeed https://example.com --strategy desktop

出力の解釈

詳しい解釈ガイドについては references/seo-playbook.md を参照してください。以下の内容が含まれています。

• SERP の順位別 CTR のベンチマーク
• Core Web Vitals のしきい値
• URL 検査の判定
• タイトル／説明の最適化
• 月次モニタリングの方法

設定ファイル

• OAuth 認証情報：~/.config/skills/gsc/credentials.json
• 設定（API キー）：~/.config/skills/gsc/config.json
• GSC_CONFIG_DIR=/path/to/dir で設定ディレクトリを変更できます

以前のバージョンからの移行

設定が ~/.config/gsc/ に保存されるビルドからアップグレードする場合は、gsc config migrate --apply を実行して、認証情報と設定を新しい場所に移動してください。移行が実行されるまで、gsc auth status は deprecation_warning を出力します。

トラブルシューティング

「認証されていません」 -- gsc auth login --client-secret /path/to/client_secret.json を実行してください。新しいマシンでは、認証情報の有効期限が切れているか、認証情報が存在しない可能性があります。

「アクセスが拒否されました」 -- 認証済みアカウントは、Search Console プロパティの確認済み所有者またはユーザーである必要があります。https://search.google.com/search-console でプロパティへのアクセス権を確認してください。

「レート制限を超えました」 -- Search Console API には、分単位および日単位の使用上限があります。60 秒待ってから再試行してください。使用上限の詳細については、references/setup.md を参照してください。

URL 検査でデータが返されない -- URL が Google のインデックスに登録されていない可能性があります。verdict フィールドを確認してください。検査できるのは、確認済みプロパティ内の URL のみです。

PageSpeed のタイムアウト -- Lighthouse のラボテストには 30～60 秒かかることがあります。このコマンドのタイムアウトは 120 秒です。失敗した場合は再試行してください。

config set で「不明なキー」が表示される -- 有効な設定キーは pagespeed-api-key のみです。