linkfox-google-trend-get-trend-by-keys

Google Trends キーワードトレンド分析

このスキルでは、Google Trends のキーワード検索関心データを取得して分析する方法を説明します。ユーザーが、地域ごとにキーワードの人気度が時間とともにどのように変化するかを把握できるよう支援します。

基本概念

Google Trends は、選択した地域と期間における検索語のピーク人気度を基準に、検索関心度を正規化したデータ（0～100 の尺度）を提供します。値が 100 の場合は人気度のピークを表し、50 はピーク時の半分の人気度を意味します。0 はデータが不十分であることを示します。

重要な言語ルール：キーワードは対象国の言語で指定する必要があります。たとえば、米国では英語、ドイツではドイツ語、日本では日本語のキーワードを使用します。ユーザーが異なる言語のキーワードを指定した場合は、取得前に翻訳してください。

パラメーター

パラメーター	種類	必須	説明
keyword	文字列	はい	分析する検索キーワード（最大 100 文字）。対象国の言語で指定する必要があります。
region	文字列	いいえ	国／地域コード。デフォルトは US です。
dayRangeStart	文字列	いいえ	期間の開始日（形式：YYYY-MM-DD、2004 年以降）。
dayRangeEnd	文字列	いいえ	期間の終了日（形式：YYYY-MM-DD、2004 年以降）。

dayRangeStart と dayRangeEnd の両方が指定されている場合は、カスタム期間が優先されます。

対応地域

US（米国）、GB（英国）、JP（日本）、CA（カナダ）、MX（メキシコ）、DE（ドイツ）、FR（フランス）、IT（イタリア）、ES（スペイン）、NL（オランダ）、AU（オーストラリア）、SG（シンガポール）、AE（アラブ首長国連邦）、BR（ブラジル）、IN（インド）、TR（トルコ）、PL（ポーランド）、SE（スウェーデン）

デフォルトの地域は US です。ユーザーが地域を指定しない場合は、US を使用してください。

呼び出し方法

• API エンドポイント：POST /googleTrend/getTrendByKeys（パラメーター／レスポンス／エラーコードの詳細は references/api.md を参照）
• Python スクリプト：python scripts/google_trends_keyword.py '<JSON 参数>' [--inline]
• コスト制約：このツールは計算リソースを消費します。同一セッション内では、同じパラメーターの組み合わせに対する呼び出しはデフォルトで 1 回のみです。スクリプトには 24 時間のローカルキャッシュがあります。失敗や空の結果が返された場合に、キーワードの自動変更、ページ送り、郵便番号の変更を繰り返して試してはいけません。検索を続ける必要がある場合は、追加の消費が発生することを事前にユーザーに伝えてください。

出力方針（スクリプトのデフォルト動作）：

• 常に完全なレスポンスを <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-google-trend-get-trend-by-keys-<timestamp>.json に保存します（<cwd> はスクリプト実行時の作業ディレクトリです。Claude Code では現在のプロジェクトディレクトリに該当します。<session> は環境変数 SESSION_ID から取得され、ユーザーのタスクごとに自動的に集約されます。/tmp への書き込みは禁止です。現在のディレクトリに書き込めない場合はエラーになります）
• レスポンス本文が 8 KB 以下の場合：ファイルへの保存後、完全な JSON を stdout に出力します
• レスポンス本文が 8 KB を超える場合：ファイルへの保存後、stdout には要約のみを出力します（トップレベルのフィールド、total／costToken などの一般的な件数、最大のリストフィールドの長さと先頭 3 件のサンプル）
• --inline を追加すると、stdout に全量を強制的に出力します（同様にファイルにも保存されます）

データの確認に関する推奨事項：まず要約を確認し、十分な情報が得られているか判断してください。具体的なフィールドが必要な場合は、JSON 全体をコンテキストに読み込ませず、保存された JSON ファイルから jq または ConvertFrom-Json を使って必要なデータを抽出してください。

認証と計算リソースの問題を解決する

次のような異常が発生した場合は、references/onboarding.md の案内に従って問題を解決してください。

異常な状況

• API Key が未設定：環境変数 LINKFOX_AGENT_API_KEY も LINKFOXAGENT_API_KEY も設定されていません。
• レスポンスのステータスコードが 401 または 402
• 計算リソースまたは残高が不足している旨のレスポンス：メッセージに「計算リソースの残高不足／課金不足／残高不足／quota exceeded／insufficient balance／プランの期限切れ／チャージが必要／チャージしてください」または類似の内容が含まれています。

クエリの作成方法

効果的なクエリの原則

1. 適切な言語を使用する：キーワードが対象地域の言語に合っていることを必ず確認してください。必要に応じて、まず翻訳してください。
2. 地域を指定する：デフォルトは US ですが、ユーザーが対象とする市場を必ず確認してください。
3. 分析対象を絞るには期間を指定する：季節的なトレンドや特定のイベントを分析する場合は、dayRangeStart と dayRangeEnd を指定してください。
4. キーワードは簡潔にする：Google Trends では、短く焦点を絞った検索語が最も効果的です。

使用例

1. 基本的なキーワードトレンド（デフォルトの地域と期間）

{"keyword": "wireless charger"}

米国における「wireless charger」の検索関心度の全体的な推移を確認します。

2. 特定の地域におけるキーワードトレンド

{"keyword": "Ladekabel", "region": "DE"}

ドイツにおける「Ladekabel」（充電ケーブル）の検索関心度を確認します。

3. カスタム期間の分析

{"keyword": "christmas gifts", "region": "US", "dayRangeStart": "2024-09-01", "dayRangeEnd": "2025-01-31"}

米国における「christmas gifts」の季節的な推移を、2024年9月から2025年1月まで分析します。

4. 前年比の比較

{"keyword": "sunscreen", "region": "AU", "dayRangeStart": "2023-01-01", "dayRangeEnd": "2025-12-31"}

オーストラリアにおける「sunscreen」の複数年にわたる季節性を比較します。

5. 地域市場の調査

{"keyword": "yoga mat", "region": "GB"}

英国における「yoga mat」の人気の推移を確認します。

6. 新たなトレンドの検出

{"keyword": "AI glasses", "region": "US", "dayRangeStart": "2024-01-01", "dayRangeEnd": "2025-12-31"}

米国における「AI glasses」の検索関心度が過去2年間でどのように高まったかを追跡します。

表示ルール

1. データをわかりやすく提示する：トレンドデータを整った表で示すか、トレンド曲線について説明します。ピーク値、最低値、注目すべき変化など、主要なデータポイントを含めます。
2. 尺度を説明する：Google Trends の値は0～100の正規化された尺度であり、選択した範囲内で100が最も人気の高い状態を表すことをユーザーに伝えます。
3. パターンを強調する：データに表れている場合は、季節的なパターン、急激な上昇、継続的な増加や減少を指摘します。
4. チャートデータの利用可能性：応答にchartOptionが含まれている場合は、可視化データを利用できることに触れ、トレンドの形状を説明します。
5. エラー処理：クエリに失敗した場合は、理由を説明し、修正案を提示します（例：キーワードのスペルを確認する、別の期間を試す、キーワードが適切な言語であることを確認する）。

重要な制限事項

• データ分析：応答はJSONです。保存された応答からtrendInfoForKeys[].trendValues[]を読み取り、timeRangeと"<1"などの値はゼロに変換せず、そのまま保持します。_dataQuery_executeDynamicQueryはSLSに保存されたLinkfoxセッションデータをクエリするものであり、任意のJSONファイルを対象とするものではありません。必要な保存データのマッピングが存在する場合にのみ使用してください。
• 正規化された値：トレンド値は相対値（0～100）であり、検索ボリュームの絶対値ではありません。
• データの利用可能性：データは2004年以降を対象としていますが、非常にニッチな用語はデータがまばらな場合があります。
• 1回の呼び出しにつきキーワードは1つ：各API呼び出しで扱えるキーワードは1つです。複数のキーワードを比較する場合は、個別に呼び出して結果を比較します。
• 言語要件：正確な結果を得るには、キーワードを対象地域の言語に合わせる必要があります。

ユーザーの表現とシナリオのクイックリファレンス

適用対象 — キーワードの検索人気度の推移に関するクエリ：

ユーザーの発言	シナリオ
「GoogleでXXキーワードはどのくらい人気ですか」	基本的なトレンドの確認
「XXは上昇傾向ですか、下降傾向ですか」	トレンドの方向性の分析
「XXの検索数がピークになるのはいつですか」	季節的なピークの検出
「XXの人気を月ごとに比較してください」	季節的なパターンの分析
「ドイツでXXの注目度は高まっていますか」	地域別のトレンド確認
「過去1年間のXXの検索トレンドを教えてください」	過去のトレンド分析
「XXに関する休暇シーズンの検索トレンド」	季節的／イベントに応じた分析

適用対象外 — Google Trendsの検索関心度データ以外の情報が必要な場合：

• Google Adsのキーワードプランナー、または入札単価／CPCデータ
• 検索ボリュームの絶対値（Google Trendsが提供するのは相対値であり、絶対値ではありません）
• ソーシャルメディアのトレンドトピック（Twitter/X、TikTokなど）
• Amazon固有の検索語データ（代わりにABA Data Explorerを使用してください）
• ウェブサイトのトラフィック分析（Google Analytics、SimilarWebなど）
• 検索エンジンの検索結果ページにおけるキーワードの順位（SEO順位の追跡）

適用範囲の判断：「キーワード調査」や「市場トレンド分析」とユーザーが述べた場合、Googleの観点から見た検索関心度の経時的な人気に関するものであれば、このスキルが適用されます。絶対的なトラフィック数、広告指標、または特定のEコマースプラットフォームのデータを求めている場合は適用されません。

計算リソースの消費ルール

計算リソースを6消費します。

ユーザーは計算リソースの消費に応じて料金を支払います。十分に評価してください。このスキルを頻繁に呼び出す必要がある場合、またはユーザーが計算リソースの消費量を十分に把握していない場合は、必ずユーザーに注意を促し、続行するかどうかはユーザーに判断してもらってください。

フィードバック：

以下のいずれかに該当する場合、フィードバック API を使用してフィードバックを自動検出し、報告してください。

1. このスキルで説明されている機能または目的が、実際の動作と一致しない
2. スキルの結果がユーザーの意図と一致しない
3. ユーザーがこのスキルへの不満または称賛を表明する
4. 改善できると思われる点がある

references/api.md の指示に従ってフィードバック API を呼び出してください。ユーザーの作業を中断しないでください。

---

高品質でプロフェッショナルな越境ECスキルをさらに利用するには、LinkFox Skills を設定してください。