google-search-console-cli

Google Search Console CLI スキル

Google Search Console API 用の CLI、google-search-console-cli を利用できます。検索アナリティクスのクエリ、URL のインデックス登録状況の確認、サイトとサイトマップの管理に使用します。

クイックスタート

# Check if the CLI is available
google-search-console-cli --help

# List accessible sites
google-search-console-cli sites

CLI がインストールされていない場合は、インストールしてください。

npm install -g google-search-console-cli

認証

CLI は Google サービスアカウントを使用します。認証情報は次の順序で解決されます。

1. --credentials <path> フラグ（コマンドごと）
2. GOOGLE_APPLICATION_CREDENTIALS 環境変数
3. ~/.config/google-search-console-cli/credentials.json（自動検出）
4. gcloud Application Default Credentials

コマンドを実行する前に、google-search-console-cli sites を実行して認証情報が設定されていることを確認してください。認証情報エラーが発生した場合は、認証を設定するようユーザーに依頼してください。

サイト URL の形式

Search Console には 2 種類のプロパティがあります。

• URL プレフィックス プロパティ：https://www.example.com/（末尾のスラッシュとプロトコルが必要です）
• ドメイン プロパティ：sc-domain:example.com（すべてのプロトコルとサブドメインが対象です）

Search Console に登録されている正確な形式を常に使用してください。サイト URL は、ほとんどのコマンドで位置引数として指定します。

出力形式

すべてのコマンドは、デフォルトで整形済み JSON を出力します。1 行の JSON を出力するには --format compact を使用します（パイプ処理に便利です）。

コマンド

検索アナリティクスのクエリ

検索パフォーマンスデータを取得する主なツールは query コマンドです。

google-search-console-cli query <siteUrl> --start-date <date> --end-date <date> [options]

必須：

• --start-date <date> -- 開始日（YYYY-MM-DD）
• --end-date <date> -- 終了日（YYYY-MM-DD）

任意：

• --dimensions <names> -- カンマ区切りの指定：date、query、page、country、device、searchAppearance、hour
• --type <type> -- 検索タイプ：web（デフォルト）、image、video、news、discover、googleNews
• --dimension-filter <json> -- ディメンション フィルター グループの JSON 配列（以下を参照）
• --aggregation-type <type> -- auto、byPage、byProperty、byNewsShowcasePanel
• --row-limit <n> -- 最大行数。1～25000（デフォルトは 1000）
• --start-row <n> -- 開始行のオフセット（デフォルトは 0）
• --data-state <state> -- データの鮮度：all、final、hourly_all
• --all -- 自動ページネーションですべての行を取得します（--start-row とは併用できません）

行ごとのレスポンスフィールド：

• keys -- ディメンション値の配列（--dimensions で指定した順）
• clicks -- クリック数
• impressions -- 表示回数
• ctr -- クリック率（0.0～1.0）
• position -- 検索結果での平均掲載順位

--all による自動ページネーション

--all を指定すると、CLI はすべての結果を自動的にページネーションし（1 ページあたり 25000 行を使用）、完全なデータセットを返します。手動でページネーションせずにすべてのデータをエクスポートする場合に便利です。

# Get ALL queries (auto-paginates through all pages)
google-search-console-cli query https://www.example.com/ \
  --start-date 2026-02-16 \
  --end-date 2026-03-17 \
  --dimensions query \
  --all

注：--all と --start-row は併用できません。--all を使用すると、--row-limit は無視されます。

サイトの管理

# List all sites
google-search-console-cli sites

# Get info about a specific site
google-search-console-cli site <siteUrl>

# Add a site (requires Full permission)
google-search-console-cli site-add <siteUrl>

# Remove a site (requires Full permission)
google-search-console-cli site-remove <siteUrl>

サイトマップの管理

# List sitemaps for a site
google-search-console-cli sitemaps <siteUrl>

# List sitemaps under a specific sitemap index
google-search-console-cli sitemaps <siteUrl> --sitemap-index <url>

# Get info about a specific sitemap
google-search-console-cli sitemap <siteUrl> <feedpath>

# Submit a sitemap (requires Full permission)
google-search-console-cli sitemap-submit <siteUrl> <feedpath>

# Delete a sitemap (requires Full permission)
google-search-console-cli sitemap-delete <siteUrl> <feedpath>

URL の検査

# Inspect a single URL's index status
google-search-console-cli inspect <siteUrl> <inspectionUrl>

# With a specific language for messages
google-search-console-cli inspect <siteUrl> <inspectionUrl> --language zh-CN

--language オプションは、レスポンス内のメッセージの言語を指定します（デフォルト：en-US）。

レスポンスには、インデックスのステータス（インデックス登録の状態、クロール時刻、robots.txt のステータス、正規 URL）、AMP 分析（該当する場合）、モバイル ユーザビリティ、リッチリザルトの検出結果が含まれます。

複数 URL の一括検査

1 つのコマンドで複数の URL を検査します：

# From a file (one URL per line)
google-search-console-cli inspect-batch https://www.example.com/ --file urls.txt

# From stdin
cat urls.txt | google-search-console-cli inspect-batch https://www.example.com/

# With compact format (NDJSON, streams results as they complete)
cat urls.txt | google-search-console-cli inspect-batch https://www.example.com/ --format compact

オプション：

• --file <path> -- URL が 1 行に 1 つずつ記載されたファイル。省略した場合は標準入力を読み取ります
• --language <code> -- メッセージの言語コード（デフォルト：en-US）

進捗は標準エラー出力に書き込まれます：Inspecting 1/50: https://...

--format compact を指定すると、各結果は完了次第 NDJSON（1 行に 1 つの JSON オブジェクト）としてストリーミング出力されます。--format json（デフォルト）を指定すると、すべての結果が収集され、最後に JSON 配列として出力されます。

URL ごとのエラーは、バッチを停止せずに出力に記録されます（error フィールド、および取得できる場合は 403 や 429 などの code フィールド）。URL が 1 つでも失敗した場合、コマンドはすべての結果を出力した後、{"error": "N of M URLs failed inspection."} を標準エラー出力に書き込み、コード 1 で終了します。どの URL が失敗したかは、URL ごとの error フィールドを確認してください。

ディメンションフィルターグループ

--dimension-filter オプションには、フィルターグループの JSON 配列を指定します。各フィルターグループには、次の内容が含まれます：

• groupType -- "and"（すべてのフィルターに一致する必要があります）
• filters -- フィルターオブジェクトの配列

各フィルターオブジェクト：

• dimension -- 次のいずれか：query、page、country、device、searchAppearance
• operator -- 次のいずれか：equals、notEquals、contains、notContains、includingRegex、excludingRegex
• expression -- 照合する値

国コードには、3 文字の ISO 3166-1 alpha-3 形式（例：USA、GBR、DEU、JPN）を使用します。

デバイスの値：DESKTOP、MOBILE、TABLET。

フィルターの例

単一のフィルター：

[{"groupType":"and","filters":[{"dimension":"country","operator":"equals","expression":"USA"}]}]

複数のフィルター（AND）：

[{"groupType":"and","filters":[{"dimension":"country","operator":"equals","expression":"USA"},{"dimension":"device","operator":"equals","expression":"MOBILE"}]}]

正規表現フィルター：

[{"groupType":"and","filters":[{"dimension":"query","operator":"includingRegex","expression":"buy|purchase|order"}]}]

ページフィルター：

[{"groupType":"and","filters":[{"dimension":"page","operator":"contains","expression":"/blog/"}]}]

実践的な例

検索クエリの上位項目

google-search-console-cli query https://www.example.com/ \
  --start-date 2026-02-16 \
  --end-date 2026-03-17 \
  --dimensions query \
  --row-limit 50

日ごとのパフォーマンス推移

google-search-console-cli query https://www.example.com/ \
  --start-date 2026-02-16 \
  --end-date 2026-03-17 \
  --dimensions date

クリック数別の上位ページ

google-search-console-cli query https://www.example.com/ \
  --start-date 2026-02-16 \
  --end-date 2026-03-17 \
  --dimensions page \
  --row-limit 50

国別のパフォーマンス

google-search-console-cli query sc-domain:example.com \
  --start-date 2026-02-16 \
  --end-date 2026-03-17 \
  --dimensions country

デバイス別のパフォーマンス

google-search-console-cli query https://www.example.com/ \
  --start-date 2026-02-16 \
  --end-date 2026-03-17 \
  --dimensions device

特定のページのクエリパフォーマンス

google-search-console-cli query https://www.example.com/ \
  --start-date 2026-02-16 \
  --end-date 2026-03-17 \
  --dimensions query \
  --dimension-filter '[{"groupType":"and","filters":[{"dimension":"page","operator":"equals","expression":"https://www.example.com/product"}]}]'

特定の国におけるモバイルのパフォーマンス

google-search-console-cli query https://www.example.com/ \
  --start-date 2026-02-16 \
  --end-date 2026-03-17 \
  --dimensions query \
  --dimension-filter '[{"groupType":"and","filters":[{"dimension":"country","operator":"equals","expression":"USA"},{"dimension":"device","operator":"equals","expression":"MOBILE"}]}]'

ブランド関連クエリと非ブランド関連クエリ

# Brand queries
google-search-console-cli query https://www.example.com/ \
  --start-date 2026-02-16 \
  --end-date 2026-03-17 \
  --dimensions query \
  --dimension-filter '[{"groupType":"and","filters":[{"dimension":"query","operator":"includingRegex","expression":"example|exmpl"}]}]'

# Non-brand queries
google-search-console-cli query https://www.example.com/ \
  --start-date 2026-02-16 \
  --end-date 2026-03-17 \
  --dimensions query \
  --dimension-filter '[{"groupType":"and","filters":[{"dimension":"query","operator":"excludingRegex","expression":"example|exmpl"}]}]'

ブログセクションのパフォーマンス

google-search-console-cli query https://www.example.com/ \
  --start-date 2026-02-16 \
  --end-date 2026-03-17 \
  --dimensions page \
  --dimension-filter '[{"groupType":"and","filters":[{"dimension":"page","operator":"contains","expression":"/blog/"}]}]'

画像検索のパフォーマンス

google-search-console-cli query https://www.example.com/ \
  --start-date 2026-02-16 \
  --end-date 2026-03-17 \
  --dimensions query \
  --type image \
  --row-limit 50

特定のクエリでランクインしているページ（カニバリゼーションの確認）

google-search-console-cli query https://www.example.com/ \
  --start-date 2026-02-16 \
  --end-date 2026-03-17 \
  --dimensions page \
  --dimension-filter '[{"groupType":"and","filters":[{"dimension":"query","operator":"equals","expression":"best running shoes"}]}]'

ディメンションをまたいだ分析（query × page）

google-search-console-cli query https://www.example.com/ \
  --start-date 2026-02-16 \
  --end-date 2026-03-17 \
  --dimensions query,page \
  --row-limit 100

時間経過に伴うデバイス別の推移

google-search-console-cli query https://www.example.com/ \
  --start-date 2026-02-16 \
  --end-date 2026-03-17 \
  --dimensions date,device

Google News のパフォーマンス

google-search-console-cli query https://www.example.com/ \
  --start-date 2026-02-16 \
  --end-date 2026-03-17 \
  --dimensions page \
  --type googleNews

Discover フィードのパフォーマンス

google-search-console-cli query https://www.example.com/ \
  --start-date 2026-02-16 \
  --end-date 2026-03-17 \
  --dimensions page \
  --type discover

時間ごとのパフォーマンス推移（最新データを使用）

google-search-console-cli query https://www.example.com/ \
  --start-date 2026-03-17 \
  --end-date 2026-03-17 \
  --dimensions hour \
  --data-state hourly_all

ページ単位の集計（ページごとに重複を除去）

google-search-console-cli query https://www.example.com/ \
  --start-date 2026-02-16 \
  --end-date 2026-03-17 \
  --dimensions page \
  --aggregation-type byPage

すべての行を取得（自動ページネーション）

google-search-console-cli query https://www.example.com/ \
  --start-date 2026-02-16 \
  --end-date 2026-03-17 \
  --dimensions query \
  --all

大規模な結果セットをページ単位で取得（手動）

# First 1000 rows
google-search-console-cli query https://www.example.com/ \
  --start-date 2026-02-16 \
  --end-date 2026-03-17 \
  --dimensions query \
  --row-limit 1000

# Next 1000 rows
google-search-console-cli query https://www.example.com/ \
  --start-date 2026-02-16 \
  --end-date 2026-03-17 \
  --dimensions query \
  --row-limit 1000 \
  --start-row 1000

検索での表示形式別の内訳

google-search-console-cli query https://www.example.com/ \
  --start-date 2026-02-16 \
  --end-date 2026-03-17 \
  --dimensions searchAppearance

URL のインデックス登録状況を検査

google-search-console-cli inspect https://www.example.com/ https://www.example.com/important-page

複数 URL を一括検査

# Create a file with URLs to inspect
echo "https://www.example.com/page1
https://www.example.com/page2
https://www.example.com/page3" > urls.txt

# Batch inspect
google-search-console-cli inspect-batch https://www.example.com/ --file urls.txt

# Or pipe from another command
google-search-console-cli query https://www.example.com/ \
  --start-date 2026-02-16 --end-date 2026-03-17 \
  --dimensions page --format compact \
  | jq -r '.rows[].keys[0]' \
  | google-search-console-cli inspect-batch https://www.example.com/ --format compact

サイトマップを監査

# List all sitemaps
google-search-console-cli sitemaps https://www.example.com/

# Check a specific sitemap
google-search-console-cli sitemap https://www.example.com/ https://www.example.com/sitemap.xml

ワークフローのガイダンス

ユーザーが検索パフォーマンスの概要を求めた場合

1. google-search-console-cli sites を実行して、アクセス可能なサイトを確認します
2. --dimensions date を指定して query を実行し、日ごとの推移を確認します
3. --dimensions query を指定して query を実行し、上位のクエリを確認します
4. 主要な指標（合計クリック数、表示回数、平均 CTR、平均掲載順位）を提示します

ユーザーが特定のページの SEO について尋ねた場合

1. --dimensions query と、そのページ URL を指定する --dimension-filter を使って query を実行します
2. inspect を使ってページのインデックス登録状況を確認します
3. クエリのランキング（掲載順位）とインデックス登録の健全性を照合します

ユーザーがモバイルとデスクトップのパフォーマンスについて尋ねた場合

1. --dimensions device を指定して query を実行し、概要を確認します
2. 必要に応じて --dimensions query,device で詳細を確認し、デバイスによってパフォーマンスが異なるクエリを特定します

ユーザーが国際的なパフォーマンスについて尋ねた場合

1. --dimensions country を指定して query を実行し、国別の内訳を確認します
2. --dimension-filter を使って、特定の国に絞り込みます

ユーザーがインデックス登録の問題について尋ねた場合

1. 特定の URL には inspect、一括確認には inspect-batch を使用します
2. sitemaps コマンドと sitemap コマンドでサイトマップを確認します
3. 検査結果で、クロールエラー、インデックス登録のブロック、モバイルユーザビリティの問題を確認します

ユーザーがすべての検索データをエクスポートしたい場合

1. --all を指定した query を使用して、すべての結果を自動的にページネーションします
2. jq などのツールにパイプで渡すのに適した NDJSON 出力には、--format compact を使用します

権限レベル

• 読み取り専用（制限付き）：sites、site、query、sitemaps、sitemap、inspect、inspect-batch
• 書き込み（フル）：site-add、site-remove、sitemap-submit、sitemap-delete

ほとんどの分析ワークフローでは、読み取り専用の権限で十分です。

エラー処理

• 認証エラー — サービスアカウントの認証情報を確認するようユーザーに依頼します
• 403 Permission denied — サービスアカウントにサイトへのアクセス権がありません。Search Console の設定で、サイトごとに追加する必要があります
• 結果が空 — 期間を確認します（通常、データが利用可能になるのは対象日から 2～3 日後です）。サイト URL の形式が登録済みのプロパティと一致しているかも確認します
• 400 Bad request — ディメンションフィルターの JSON 構文とフィールドの互換性を確認します

API ドキュメントの参照先

参照先	使用する場面
google-search-console-cli documentation	README 全文、セットアップガイド、インストール
Search Analytics API	クエリメソッド、ディメンション、フィルター、レスポンス形式
URL Inspection API	検査メソッド、リクエスト／レスポンスのフィールド
Sites API	サイト管理メソッドと権限レベル
Sitemaps API	サイトマップ管理メソッドとリソースフィールド