pp-google-trends

Google Trends — Printing Press CLI

前提条件：CLI をインストールする

このスキルは google-trends-pp-cli バイナリを使用します。このスキルのコマンドを実行する前に、CLI がインストールされていることを必ず確認してください。 インストールされていない場合は、先にインストールしてください。

1. Printing Press インストーラーを使ってインストールします。バイナリの既定のインストール先は、macOS/Linux では $HOME/.local/bin、Windows では %LOCALAPPDATA%\Programs\PrintingPress\bin です。

   npx -y @mvanhorn/printing-press-library install google-trends --cli-only
   

2. 確認します：google-trends-pp-cli --version
3. 報告されたインストール先ディレクトリが、このスキルを実行するエージェント／ランタイムの $PATH に含まれていることを確認します。

npx によるインストールに失敗した場合（Node がない、オフラインなど）は、Go を直接インストールする方法に切り替えてください（Go 1.26.6 以降が必要です）。これは $GOPATH/bin（既定値は $HOME/go/bin）にインストールされるため、代わりにそのディレクトリを $PATH に追加してください。

go install github.com/mvanhorn/printing-press-library/library/marketing/google-trends/cmd/google-trends-pp-cli@latest

インストール後に --version が「command not found」と報告する場合、ランタイムから $PATH 上のバイナリディレクトリが見えていません。確認に成功するまで、スキルのコマンドを実行しないでください。

定番の Python ラッパーである pytrends は 2025 年 4 月にアーカイブされました。また、Google Trends は匿名アクセスを積極的かつ予測不能な形で制限します。この CLI は、リトライとバックオフを組み込んで explore-to-widget の一連の処理に対応し、すべてのクエリをローカルにキャッシュすることで履歴を積み重ねて保持します。さらに、ライブサイトでは答えられない「3 週間前に何がトレンドだったか」「前回の確認から何が変わったか」「関連語のうち、実際にコンテンツ概要に値するものはどれか」といった質問にも答えられます。

この CLI を使用する場面

関心度の時系列データの取得、複数のキーワードや地域間での比較、コンテンツ計画に役立つ関連クエリや急上昇クエリの発見、ローカルキャッシュを使ったトレンドトピックの経時的な追跡など、プログラムによる Google Trends 調査にこの CLI を使用してください。Google Trends の UI では破棄される履歴が必要な場合や、以前は手動の pytrends スクリプトで行っていた作業を自動化する場合に最適なツールです。

使用しない場面

次の場合、この CLI は使用しないでください。

• 絶対的な検索ボリュームの取得には使用しないでください。Google Trends が公開するのは相対的な 0～100 の関心度だけで、実際の検索クエリ数は公開しません。
• 大規模なリアルタイム（1 時間未満の間隔）トレンド監視には使用しないでください。API の厳しいレート制限により、短い間隔でのポーリングループは信頼性に欠けます。
• Google Ads キーワードプランナーのような、認証が必要なボリュームデータの取得には使用しないでください。その場合は、Trends ではなく、別途 Google Ads アカウントと API が必要です。

独自の機能

これらの機能は、この API を扱う他のツールでは利用できません。

積み重なるローカル状態

• trends trending at — 過去の特定の日付と地域で何がトレンドだったかを確認できます。Google Trends のライブ UI では答えられない質問です。

  ライブサイトをスクレイピングする代わりに、過去の特定の日に何がトレンドだったかを再構成するときに使用してください。ライブサイトでは、過去のトレンドスナップショットをまったく表示できません。

  google-trends-pp-cli trends trending at --date 2026-06-15 --geo US --agent
  

• trends history search — これまでに同期した関連語やトレンドトピックの結果を、オフラインで全文検索できます。

  数週間前に追跡した語が関連語やトレンドとして表示されたことがあるか、レート制限のあるライブ API に再クエリすることなく確認できます。

  google-trends-pp-cli trends history search "electric vehicle" --table related --agent
  

• trends changes — 前回の同期以降、キーワードの関連語と関心度スコアに何が変わったかを正確に確認できます。

  先週から何が新しく加わったかを正確に知りたいときに、チャートをもう一度目視確認する代わりに使用してください。

  google-trends-pp-cli trends changes coffee --since 7d --agent
  

• trends opportunities — キーワードの関連語／急上昇語を、上昇の勢いと親トピックの成長率の積でランク付けし、優れたコンテンツ案を上位に表示します。

  関連クエリの一覧ではなく、勢いに基づいてランク付けされたコンテンツ案の候補が必要なときに使用してください。

  google-trends-pp-cli trends opportunities "meal prep" --agent
  

算出されたインサイト

• trends seasonality — キャッシュされた履歴からキーワードの月別平均、ピーク月、季節性の強さを示すスコアを算出します。

  グラフを手作業で目視する代わりに、キャッシュされた履歴からキーワードの季節パターンを検出する場合に使います。

  google-trends-pp-cli trends seasonality "pumpkin spice" --geo US --agent
  

• trends geo-gap — 2 つのキーワードの関心度に最も大きな差がある地域を順位付けします。手作業で比較する必要がある地域ごとの生の値を返すのではありません。

  2 つのキーワード間で地域差が最も大きい順に並んだ一覧が必要な場合に使います。地域ごとの生の値を比較する場合には使いません。

  google-trends-pp-cli trends geo-gap nike adidas --resolution REGION --agent
  

到達可能性の緩和策

• trends stale — ローカルデータが最近更新されていない追跡対象のキーワードを一覧表示します。レート制限に達する前に、どのデータを再同期すべきか確認できます。

  この API はレート制限の影響を受けやすいことが確認されているため、一括再同期の前にこれを確認し、実際に古くなっているデータだけを更新してください。

  google-trends-pp-cli trends stale --older-than 14d --agent
  

HTTP トランスポート

この CLI は、ブラウザー向けエンドポイントに Chrome 互換の HTTP トランスポートを使用します。通常の API 呼び出しに、常駐するブラウザープロセスは必要ありません。

検出シグナル

この CLI は、ブラウザーで観測されたトラフィックのコンテキストを使って生成されました。

• キャプチャ範囲：ネットワークエントリ合計 226 件のうち、API エントリ 29 件
• プロトコル：google_batchexecute（信頼度 95%）、rpc_envelope（信頼度 90%）、rest_json（信頼度 75%）
• 認証シグナル：api_key — ヘッダー：X-Goog-Api-Key；api_key — クエリ：key、token
• 生成時のヒント：browser_http_transport、has_rpc_envelope、requires_protected_client、weak_schema_confidence
• コマンド候補：create_GetAsyncData — 観測された POST /$rpc/google.internal.onegoogle.asyncdata.v1.AsyncDataService/GetAsyncData トラフィックから導出。create_batchexecute — 観測された POST //TrendsUi/data/batchexecute トラフィックから導出。create_browserinfo — 観測された POST //TrendsUi/browserinfo トラフィックから導出。create_explore — 観測された POST /trends/api/explore トラフィックから導出。create_reload — 観測された POST /recaptcha/enterprise/reload トラフィックから導出。create_startup_config — 観測された POST /v1/survey/startup_config トラフィックから導出。create_trigger_anonymous — 観測された POST /v1/survey/trigger/trigger_anonymous トラフィックから導出。create_ubd — 観測された POST /recaptcha/api2/ubd トラフィックから導出。
• 注意事項：empty_payload：API リクエストのように見えるリクエストが、空または null のペイロードを返しました。スキーマの信頼度は低いです。empty_payload：API リクエストのように見えるリクエストが、空または null のペイロードを返しました。スキーマの信頼度は低いです。empty_payload：API リクエストのように見えるリクエストが、空または null のペイロードを返しました。スキーマの信頼度は低いです。empty_payload：API リクエストのように見えるリクエストが、空または null のペイロードを返しました。スキーマの信頼度は低いです。empty_payload：API リクエストのように見えるリクエストが、空または null のペイロードを返しました。スキーマの信頼度は低いです。empty_payload：API リクエストのように見えるリクエストが、空または null のペイロードを返しました。スキーマの信頼度は低いです。empty_payload：API リクエストのように見えるリクエストが、空または null のペイロードを返しました。スキーマの信頼度は低いです。empty_payload：API リクエストのように見えるリクエストが、空または null のペイロードを返しました。スキーマの信頼度は低いです。empty_payload：API リクエストのように見えるリクエストが、空または null のペイロードを返しました。スキーマの信頼度は低いです。empty_payload：API リクエストのように見えるリクエストが、空または null のペイロードを返しました。スキーマの信頼度は低いです。

コマンドリファレンス

trends — Google Trends のコアとなる explore／ウィジェットのフローです。explore と pickers_* は直接呼び出せます。widget_* エンドポイントには、先行する explore 呼び出しで発行されたトークンが必要です（Priority 0/1 の手書きラッパーコマンドで連鎖させます。absorb manifest を参照）。すべてのレスポンスには、Google の XSSI 防御文字列 )]}’ が先頭に付いているため、JSON をデコードする前に削除する必要があります。

• google-trends-pp-cli trends explore — 最大 5 個のキーワードを比較するための、ウィジェットごとのトークンをリクエストします。
• google-trends-pp-cli trends pickers-category — カテゴリ ID から名前への完全な対応ツリーです。誰でもアクセスでき、クリアランスクッキーは不要です。
• google-trends-pp-cli trends pickers-geo — 地域コードから名前への完全な対応ツリー（国／地域／DMA／都市）です。誰でもアクセスでき、クリアランスクッキーは不要です。
• google-trends-pp-cli trends widget-comparedgeo — GEO_MAP ウィジェットの地域別関心度データです。
• google-trends-pp-cli trends widget-multiline — TIMESERIES ウィジェットの期間別関心度データです。
• google-trends-pp-cli trends widget-relatedsearches — RELATED_QUERIES／RELATED_TOPICS ウィジェットの関連クエリと関連トピック（上位と上昇中の両方）です。

適切なコマンドを見つける

実行したいことは分かっていても、どのコマンドを使えばよいか分からない場合は、CLI に直接尋ねてください。

google-trends-pp-cli which "<capability in your own words>"

which は、自然言語で記述された機能に関するクエリを、この CLI の厳選された機能インデックスから最適なコマンドに解決します。終了コード 0 は少なくとも 1 つ一致したことを示します。終了コード 2 は確度の高い一致がないことを示します。その場合は --help にフォールバックするか、より具体的なクエリを使用してください。

レシピ

ブランドと 2 つの競合ブランドを比較する

google-trends-pp-cli trends interest nike --compare adidas,puma --geo US --timeframe "today 3-m" --json

1 回の呼び出しで、3 つのキーワードすべてを同じ 0-100 スケールで返します。これは、共有スケールでの比較を pytrends で行う際に、手動でペイロードを構築する必要があった処理です。

トピックから今週の最適なコンテンツ案を見つける

google-trends-pp-cli trends opportunities "home workout" --agent

関連クエリの一覧をそのまま出力するのではなく、上昇中の関連語を勢いに基づいてランキングします。

再スクレイピングせずに先週からの変化を確認する

google-trends-pp-cli trends changes coffee --since 7d --agent

ローカルに保存された最新 2 件のスナップショットを比較します。履歴を保持していないライブサイトでは答えられない質問にも対応します。

大規模な地域別内訳を取得し、必要なフィールドに絞り込む

google-trends-pp-cli trends region coffee --resolution CITY --geo US --agent --select region_name,value

都市レベルの内訳は、追加メタデータを含む数十行を返します。--select を使うと、エージェントが通常必要とする 2 つのフィールドだけにレスポンスを絞り込めます。

過去の特定の日に何がトレンドだったか確認する

google-trends-pp-cli trends trending at --date 2026-06-01 --geo US --json

ライブの Trending Now ページでは答えられない質問に対応します。ライブページに表示されるのは現在の期間だけです。

認証の設定

Google Trends にはログインも API キーもありません。匿名の NID クッキーで認証しますが、通常の HTTP クライアントと Chrome のフィンガープリントを使用したクライアントは、どちらも最初の接続時にブロックされます（HTTP 429）。これは生成時にライブ環境で確認済みです。ログイン済みの Chrome セッションからクリアランスクッキーを一度インポートするには、google-trends-pp-cli auth login --chrome を実行してください。CLI は必要に応じてクッキーを自動更新します。

google-trends-pp-cli doctor を実行して、設定を確認してください。

エージェントモード

任意のコマンドに --agent を追加してください。次のオプションに展開されます：--json --compact --no-input --no-color --yes。

• パイプ可能 — 標準出力には JSON、標準エラー出力にはエラーを出力します

• フィルタ可能 — --select でフィールドを絞り込めます。ドット区切りのパスはネストされた構造にアクセスし、配列では各要素をたどります。冗長な API でコンテキストを小さく保つために重要です。

  google-trends-pp-cli trends explore --hl en-US --tz 42 --req '{}' --agent --select id,name,status
  

• プレビュー可能 — --dry-run で、リクエストを送信せずに内容を表示します

• オフラインに対応 — sync／search コマンドは、利用可能な場合にローカルの SQLite ストアを使用できます

• 非対話型 — プロンプトは表示されず、すべての入力はフラグで指定します

• 明示的な再試行 — 既存の作成が成功として扱われるべき場合に限り、--idempotent を使用してください

レスポンスエンベロープ

ローカルストアまたは API から読み取るコマンドは、出力をプロベナンスエンベロープでラップします。

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

データには .results を、ライブデータかローカルデータかの確認には .meta.source を解析してください。人が読みやすい N results (live) の概要は、標準出力がターミナルであり、かつ機械向け形式のフラグ（--json、--csv、--compact、--quiet、--plain、--select）が設定されていない場合に限り、標準エラーに出力されます。パイプ経由またはエージェントからの利用時と、形式を明示した実行時には、標準出力には純粋な JSON のみが出力されます。

パスと状態

エージェントは、CLI のパス解決をランタイム契約の一部として扱ってください。

• 1 回の呼び出しでは --home <dir> を使い、4 種類すべてのパスを 1 つのルートの下に移動する場合は GOOGLE_TRENDS_HOME=<dir> を設定してください。

• 特定の種類のパスだけを別の場所にする必要がある場合に限り、種類ごとの環境変数 GOOGLE_TRENDS_CONFIG_DIR、GOOGLE_TRENDS_DATA_DIR、GOOGLE_TRENDS_STATE_DIR、GOOGLE_TRENDS_CACHE_DIR を使ってください。

• 解決順序は、種類ごとの環境変数、--home、GOOGLE_TRENDS_HOME、XDG（XDG_CONFIG_HOME、XDG_DATA_HOME、XDG_STATE_HOME、XDG_CACHE_HOME）、プラットフォームのデフォルトの順です。

• config には config.toml やプロファイルなどの設定が含まれます。data には credentials.toml、data.db、Cookie、認証サイドカーが含まれます。state には永続化されたクエリ、ジョブ、teach.log が含まれます。cache には再生成可能な HTTP／キャッシュファイルが含まれます。

• 保存されたシークレットは、データディレクトリ内の credentials.toml に格納されます。既存のレガシーな config.toml 内のシークレットは互換性のために読み込まれ、最初の認証書き込み時に config.toml から取り除かれます。

• google-trends-pp-cli doctor --fail-on warn を実行すると、パスと認証情報の場所に関する警告が表示されます。agent-context は、解決済みディレクトリを必要とするエージェント向けに、スキーマ v4 の paths ブロックを公開します。

• MCP の場合は、MCP ホストの設定を通じて移動先を指定してください。MCP バイナリは CLI フラグを継承しません。

  {
    "mcpServers": {
      "google-trends": {
        "command": "google-trends-pp-mcp",
        "env": {
          "GOOGLE_TRENDS_HOME": "/srv/google-trends"
        }
      }
    }
  }
  

フリートでの優先順位：継承された種類ごとの環境変数は、その種類に対する明示的な --home より優先されます。フリート全体で継続的に使う設定には GOOGLE_TRENDS_HOME または種類ごとの環境変数を使い、--home は 1 回の呼び出しに限って使ってください。環境変数の設定を解除しても、移動は元に戻りません。GOOGLE_TRENDS_HOME をクリアする前にファイルを手動で移動してください。そうしないと、doctor は以前のルートに残された認証情報を見つけられません。

エージェントへのフィードバック

あなた（またはエージェント）がこの CLI に違和感を覚えたら、記録してください。

google-trends-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
google-trends-pp-cli feedback --stdin < notes.txt
google-trends-pp-cli feedback list --json --limit 10

エントリーは、解決済みデータディレクトリ内の feedback.jsonl にローカル保存されます。GOOGLE_TRENDS_FEEDBACK_ENDPOINT が設定され、かつ --send が指定されている場合、または GOOGLE_TRENDS_FEEDBACK_AUTO_SEND=true の場合を除き、POST されることはありません。デフォルトの動作はローカルのみです。

バグ報告ではなく、意外だったことを書いてください。短く、具体的に、1 行で。それが積み重なる部分です。

出力の配信

すべてのコマンドで --deliver <sink> を指定できます。出力は、標準出力に加えて、または標準出力の代わりに、指定したシンクに送られます。そのため、エージェントはコマンド結果を手動でパイプ処理せずに振り分けられます。次の 3 つのシンクに対応しています。

シンク	効果
stdout	デフォルト。標準出力のみに書き込みます
file:<path>	出力を <path> にアトミックに書き込みます（一時ファイル + rename）
webhook:<url>	出力本文を URL に POST します（--compact の場合は application/json または application/x-ndjson）

不明なスキームは、対応しているスキームを示す構造化エラーとともに拒否されます。Webhook の失敗時はゼロ以外の終了コードが返され、URL と HTTP ステータスが標準エラーに記録されます。

名前付きプロファイル

プロファイルは、保存されたフラグ値のセットで、呼び出し間で再利用されます。スケジュール実行または定期実行するエージェントが、実行ごとに異なる入力を受け取りながら同じ保存済みフラグを再利用する場合に使います。

google-trends-pp-cli profile save briefing --json
google-trends-pp-cli --profile briefing trends explore --hl en-US --tz 42 --req '{}'
google-trends-pp-cli profile list --json
google-trends-pp-cli profile show briefing
google-trends-pp-cli profile delete briefing --yes

明示的なフラグは常にプロファイル値より優先され、プロファイル値はデフォルト値より優先されます。agent-context は、実行時にエージェントが利用可能なプロファイルを確認できるよう、すべてのプロファイルを available_profiles に一覧表示します。

終了コード

コード	意味
0	成功
2	使用方法のエラー（引数が誤っています）
3	リソースが見つかりません
4	認証が必要です
5	API エラー（上流の問題）
7	レート制限中（待ってから再試行してください）
10	設定エラー

引数の解析

$ARGUMENTS を解析します：

1. 空、help、または --help → google-trends-pp-cli --help の出力を表示します
2. install で始まる → mcp で終わる場合は MCP のインストール、それ以外の場合は上記の前提条件を参照します
3. それ以外 → 直接使用（--agent を付けて CLI コマンドとして実行します）

MCP サーバーのインストール

1. MCP サーバーをインストールします：

   go install github.com/mvanhorn/printing-press-library/library/marketing/google-trends/cmd/google-trends-pp-mcp@latest
   

2. Claude Code に登録します：

   claude mcp add google-trends-pp-mcp -- google-trends-pp-mcp
   

3. 確認します：claude mcp list

直接使用

1. インストール済みか確認します：which google-trends-pp-cli 見つからない場合は、インストールを提案します（このスキルの冒頭にある「前提条件」を参照）。
2. ユーザーのクエリに最適なコマンドを、上記の「独自の機能」と「コマンドリファレンス」から選びます。
3. --agent フラグを付けて実行します：

   google-trends-pp-cli <command> [subcommand] [args] --agent
   

4. 曖昧な場合は、サブコマンドのヘルプを確認します：google-trends-pp-cli <command> --help。