seo-google

Google SEO APIs

共有データキャッシュ

ステップ 0 -- 共有データキャッシュを確認します：

情報を収集する前に、関連する SEO スキルの再利用可能なコンテキストが .seo-cache/ にあるか確認してください。 スキーマと依存関係マップについては、../seo/references/shared-data-cache.md を参照してください。

次のキャッシュファイルが存在する場合は確認してください：

• .seo-cache/site-meta.json：ドメイン、ビジネスタイプ、業界、クロールのコンテキスト

• .seo-cache/audit-scores.json：以前のフル監査での優先事項

• .seo-cache/pages/{url-slug}/page-analysis.json：URL が指定されている場合のページ単位のコンテキスト

• 見つかった場合：明らかに有効なフィールドを解析して使用します（「[日付] の [X] をキャッシュから使用」と記録します）

• 見つからない、破損している、または関連性がない場合：新しいエビデンスを使って続行します

• ユーザーが「refresh」または「re-run」と指示した場合：キャッシュの読み込みを無視し、書き込み時に上書きします

Google 独自の SEO データに直接アクセスします。クロールベースの分析（既存の codex-seo スキル）と、Google のリアルタイムなフィールドデータ（実際の Chrome ユーザーメトリクス、実際のインデックス登録状況、検索パフォーマンス、オーガニックトラフィック）の間をつなぎます。

すべての API は無料です。セットアップには API キーまたはサービスアカウントを備えた Google Cloud プロジェクトが必要です。手順については /seo google setup を実行してください。

前提条件

コマンドを実行する前に、認証情報を確認してください：

python scripts/google_auth.py --check --json

設定ファイル：~/.config/codex-seo/google-api.json

{
  "service_account_path": "/path/to/service_account.json",
  "api_key": "AIzaSy...",
  "default_property": "sc-domain:example.com",
  "ga4_property_id": "properties/123456789"
}

見つからない場合は、references/auth-setup.md を読み、ユーザーのセットアップを案内してください。

認証情報のティア

ティア	検出条件	利用可能なコマンド
0（API キー）	api_key がある	pagespeed、crux、crux-history、youtube、nlp
1（OAuth/SA）	+ OAuth トークンまたはサービスアカウント	ティア 0 + gsc、inspect、sitemaps、index
2（フル）	+ ga4_property_id が設定済み	ティア 1 + ga4、ga4-pages
3（広告）	+ ads_developer_token + ads_customer_id	ティア 2 + keywords、volume

コマンドを実行する前に、検出されたティアを必ず伝えてください。

クイックリファレンス

コマンド	内容	ティア
/seo google setup	API 認証情報の確認／設定	--
/seo google pagespeed <url>	PSI Lighthouse + CrUX フィールドデータ	0
/seo google crux <url>	CrUX フィールドデータのみ（p75 メトリクス）	0
/seo google crux-history <url>	25 週間の CWV トレンド分析	0
/seo google gsc <property>	Search Console：クリック数、表示回数、CTR、掲載順位	1
/seo google inspect <url>	URL 検査：インデックス登録状況、canonical、クロール情報	1
/seo google inspect-batch <file>	ファイルから URL を一括で検査	1
/seo google sitemaps <property>	GSC サイトマップのステータス	1
/seo google index <url>	Indexing API に URL を送信	1
/seo google index-batch <file>	最大 200 件の URL を一括送信	1
/seo google ga4 [property-id]	GA4 オーガニックトラフィックレポート	2
/seo google ga4-pages [property-id]	オーガニック流入のランディングページ上位	2
/seo google youtube <query>	YouTube 動画検索（再生回数、いいね数、長さ）	0
/seo google youtube-video <id>	YouTube 動画の詳細 + 上位コメント	0
/seo google nlp <url-or-text>	NLP エンティティ抽出 + 感情分析 + 分類	0
/seo google entities <url-or-text>	エンティティ分析のみ（E-E-A-T 用）	0
/seo google keywords <seed>	Google Ads キーワードプランナーによるキーワード候補	3
/seo google volume <keywords>	キーワードプランナーによる検索ボリュームの確認	3
/seo google entity <query>	Knowledge Graph エンティティの確認	0
/seo google safety <url>	Web Risk による URL の安全性チェック	0
/seo google quotas	すべての API のレート制限を表示	--

---

PageSpeed + CrUX

/seo google pagespeed <url>

Lighthouse のラボデータと CrUX のフィールドデータを統合します。

スクリプト： python scripts/pagespeed_check.py <url> --json リファレンス： references/pagespeed-crux-api.md デフォルト： モバイルとデスクトップの両方のストラテジーを使用し、Lighthouse のすべてのカテゴリを対象にします。

出力では、ラボスコア（実行時点の Lighthouse）とフィールドデータ（Chrome ユーザーの28日間の指標）を統合します。CrUX はまず URL レベルのデータを取得し、取得できない場合はオリジンレベルにフォールバックします。

/seo google crux <url>

CrUX のフィールドデータのみを取得します（Lighthouse は実行しません）。より高速です。

スクリプト： python scripts/pagespeed_check.py <url> --crux-only --json

/seo google crux-history <url>

25週間分の CrUX 履歴トレンドです。CWV 指標が改善、安定、悪化のいずれの傾向にあるかを示します。

スクリプト： python scripts/crux_history.py <url> --json リファレンス： references/pagespeed-crux-api.md

出力には、指標ごとのトレンドの方向、変化率、週ごとの p75 値が含まれます。

---

Search Console

/seo google gsc <property>

検索アナリティクス：過去28日間のクリック数、表示回数、CTR、掲載順位を取得します。

スクリプト： python scripts/gsc_query.py --property <property> --json リファレンス： references/search-console-api.md デフォルト： 28日間、ディメンション=query,page、タイプ=web、上限=1000。

クイックウィンの検出も含まれます。表示回数が多く、掲載順位が4～10位のクエリを特定します。

/seo google inspect <url>

URL 検査：Google における実際のインデックス登録状況を取得します。

スクリプト： python scripts/gsc_inspect.py <url> --json

返される情報：判定（PASS/FAIL）、カバレッジの状態、robots.txt の状態、インデックス登録の状態、ページの取得状態、正規 URL の選択、モバイルでの使いやすさ、リッチリザルト。

/seo google inspect-batch <file>

ファイルから一括検査します（1行につき URL を1つ指定）。サイトごとに1日あたり2,000件までに制限されています。

スクリプト： python scripts/gsc_inspect.py --batch <file> --json

/seo google sitemaps <property>

送信済みのサイトマップを、ステータス、エラー、警告とともに一覧表示します。

スクリプト： python scripts/gsc_query.py sitemaps --property <property> --json

---

Indexing API

/seo google index <url>

URL の更新を Google に通知します。

スクリプト： python scripts/indexing_notify.py <url> --json リファレンス： references/indexing-api.md

Indexing API の公式な対象は、JobPosting および BroadcastEvent/VideoObject のページです。この制限は必ずユーザーに伝えてください。1日の割り当て上限：公開リクエスト200件。

/seo google index-batch <file>

ファイルから URL を一括送信します。割り当ての使用状況を追跡します。

スクリプト： python scripts/indexing_notify.py --batch <file> --json

---

GA4 Traffic

/seo google ga4 [property-id]

オーガニックトラフィックレポート：日ごとのセッション数、ユーザー数、ページビュー数、直帰率、エンゲージメントを取得します。

スクリプト： python scripts/ga4_report.py --property <id> --json リファレンス： references/ga4-data-api.md デフォルト： 28日間、Organic Search チャネルグループでフィルタリング。

/seo google ga4-pages [property-id]

セッション数の多い順に、オーガニック検索からのランディングページを表示します。

スクリプト： python scripts/ga4_report.py --property <id> --report top-pages --json

---

YouTube (Video SEO)

YouTube への言及は、AI の可視性との相関が最も強く（0.737）、無料で API キーのみが必要です。

/seo google youtube <query>

YouTube で動画を検索します。タイトル、チャンネル、再生回数、高評価数、再生時間を返します。

スクリプト： python scripts/youtube_search.py search "<query>" --json リファレンス： references/youtube-api.md 割り当て： 1回の検索につき100ユニット（無料枠は1日10,000ユニット）。

/seo google youtube-video <video_id>

動画の詳細情報、タグ、上位10件のコメントを取得します。

スクリプト： python scripts/youtube_search.py video <video_id> --json 割り当て： 2ユニット（動画の詳細情報とコメント）。

---

NLP Content Analysis

Google 独自のエンティティ／感情分析です。E-E-A-T のスコアリングを強化します。

/seo google nlp <url-or-text>

NLP による包括的な分析：エンティティ、感情、コンテンツ分類。

スクリプト： python scripts/nlp_analyze.py --url <url> --json または --text "..." リファレンス： references/nlp-api.md 無料枠： 月5,000ユニット。GCP プロジェクトで課金を有効にする必要があります。

/seo google entities <url-or-text>

エンティティの抽出のみ（高速で、割り当て量を抑えられます）。

スクリプト： python scripts/nlp_analyze.py --url <url> --features entities --json

---

キーワード調査（Google Ads）

ゴールドスタンダードのキーワード検索ボリュームデータです。Google Ads アカウントが必要です。

/seo google keywords <seed>

シードキーワードからキーワード候補を生成します。

スクリプト： python scripts/keyword_planner.py ideas "<seed>" --json リファレンス： references/keyword-planner-api.md 必要なもの： 設定ファイル内の Ads デベロッパートークンと顧客 ID（Tier 3）。

/seo google volume <keywords>

指定したキーワード（カンマ区切り）の検索ボリュームを取得します。

スクリプト： python scripts/keyword_planner.py volume "<kw1>,<kw2>" --json

---

補足

/seo google entity <query>

ナレッジグラフのエンティティを確認します。ブランドの存在を検証します。

リファレンス： references/supplementary-apis.md API キーを使用して Knowledge Graph Search API を利用します。

/seo google safety <url>

Web Risk API でマルウェアやソーシャルエンジニアリングのリスクを確認します。

リファレンス： references/supplementary-apis.md

/seo google quotas

レート制限の表を表示します。references/rate-limits-quotas.md を読み込みます。

---

レポート

分析コマンドの実行後、PDF／HTML レポートを生成するか確認します。

/seo google report <type>

グラフと分析を含む、プロフェッショナルな PDF レポートを生成します。

スクリプト： python scripts/google_report.py --type <type> --data <json> --domain <domain> --format pdf

種類	入力	出力
cwv-audit	PSI + CrUX + CrUX History データ	ゲージ、タイムライン、分布図を含む Core Web Vitals 監査
gsc-performance	GSC クエリデータ	クエリ表とすぐに実施できる改善策を含む Search Console レポート
indexation	一括検査データ	カバレッジのドーナツグラフを含むインデックス登録状況
full	すべてのデータを統合	包括的な Google SEO レポート（全セクション）

ワークフロー：

1. データ収集コマンド（pagespeed、gsc、inspect-batch など）を実行します
2. JSON 出力をファイルに保存します：python scripts/pagespeed_check.py <url> --json > data.json
3. レポートを生成します：python scripts/google_report.py --type cwv-audit --data data.json --domain <domain>

慣例： 分析完了後、「レポートを生成しますか？/seo google report <type> を使用してください」と提案します。

---

レート制限

API	分あたり	日あたり	認証
PSI v5	240 QPM	25,000 QPD	API キー
CrUX + History	150 QPM（共有）	無制限	API キー
GSC Search Analytics	1,200 QPM/site	30M QPD	サービスアカウント
GSC URL Inspection	600 QPM	2,000 QPD/site	サービスアカウント
Indexing API	380 RPM	200 件公開／日	サービスアカウント
GA4 Data API	同時実行 10 件	約 25K トークン／日	サービスアカウント

スキル間の連携

• seo-audit：ライブ CWV とインデックス登録データを取得するため、seo-google エージェントを起動します（条件付き）。
• seo-technical：実際の CWV フィールドデータの取得に pagespeed_check.py を使用します。
• seo-performance：CrUX のフィールドデータで Lighthouse のラボデータを補完します。
• seo-sitemap：GSC のサイトマップ状況から、実際のクロール／インデックス登録範囲を確認できます。
• seo-content：GSC のクエリデータをキーワードターゲティングに活用します。
• seo-geo：GSC の検索での表示データには、AI Overview の参照情報が含まれます。

出力形式

• CWV 指標：信号機形式の評価（良好／要改善／不良）
• パフォーマンスレポート：列を並べ替えられる表
• データの鮮度に関する注記を必ず含めます
• レポートは GOOGLE-API-REPORT-{domain}.md として保存します
• 構造化された出力には assets/templates/ のテンプレートを使用します

技術上の注意

• INP は 2024 年 3 月 12 日に FID に取って代わりました。FID には言及しないでください。
• CrUX の CLS 値は文字列としてエンコードされています（例：「0.05」）。スクリプトが解析を処理します。
• CrUX の 404 はトラフィック不足を示し、認証エラーではありません。
• Search Analytics のデータには 2～3 日の遅延があります。
• CrUX では round_trip_time が effectiveConnectionType に取って代わりました（2025 年 2 月）。
• Custom Search JSON API は新規顧客の受付を終了しています（2025 年）。

エラー処理

シナリオ	対応
認証情報が設定されていない	/seo google setup を実行します。API キーのみで動作する Tier 0 コマンドを一覧表示します。
サービスアカウントに GSC へのアクセス権がない	エラーを報告します。client_email を GSC > Settings > Users > Add に追加するよう案内します。
CrUX データを利用できない（404）	Chrome のトラフィックが不十分であることを報告します。代替として PSI のラボデータを提案します。
GA4 プロパティが見つからない	エラーを報告します。GA4 Admin > Property Details でプロパティ ID を確認する方法を案内します。
Indexing API のクォータ超過	1 日あたり 200 件の上限を報告します。重要度の高い URL を優先するよう提案します。
レート制限（429）	指数バックオフで待機して再試行します。上限に達した API を報告します。

共有データキャッシュへの書き込み

すべての作業が完了した後、ワークフローで永続的に保持すべき調査結果が得られた場合は、簡潔な JSON サマリーを .seo-cache/ に書き込みます。 ../seo/references/shared-data-cache.md に記載されたスキーマと命名規則を使用します。少なくとも cache_type、analyzed_at、ソース URL／ドメイン、主な調査結果、問題、推奨事項、ツールの制限事項を含めます。.gitignore に .seo-cache/ がない場合は追加します。