linkfox-junglescout-keyword-history

Jungle Scout — キーワードの過去の検索ボリューム

このスキルは、Jungle Scout のデータソースを通じて、Amazon キーワードの過去の完全一致検索ボリュームを取得します。指定した日付範囲について、10 の Amazon マーケットプレイスの週次検索ボリュームデータを返します。

基本概念

Jungle Scout のキーワード過去検索ボリュームツールでは、Amazon の各マーケットプレイスにおけるキーワードの週単位の完全一致検索ボリュームの過去データを取得できます。販売者は、指定した期間の検索ボリュームの変化を調べることで、以下を判断できます。

• 季節性のパターン：キーワードの繁忙期・閑散期が何月か
• トレンドの方向性：検索ボリュームが継続的に増加、減少しているか、または横ばいか
• 変動幅：市場需要の安定性
• 祝日やセールの影響：大型セールや祝日の前後に検索ボリュームが急増するか

データ粒度：各レコードは 7 日間の期間を表し、その週の完全一致検索ボリュームの推定値を含みます。

データフィールド

出力フィールド

フィールド	API 名	説明	例
期間識別子	id	データ期間の識別子（マーケットプレイス／キーワード／日付範囲）	us_sushi_20250105_20250111
期間開始日	estimateStartDate	7 日間の集計期間の開始日	2025-01-05
期間終了日	estimateEndDate	7 日間の集計期間の終了日	2025-01-11
完全一致検索ボリューム	estimatedExactSearchVolume	期間内の完全一致検索ボリューム（回／週）	12500
リソースタイプ	type	固定値	historical_keyword_search_volume
消費トークン	costToken	今回の呼び出しで消費したトークン数	1

対応マーケットプレイス

マーケットプレイス	marketplace の値	説明
米国	us	Amazon.com
英国	uk	Amazon.co.uk
ドイツ	de	Amazon.de
インド	in	Amazon.in
カナダ	ca	Amazon.ca
フランス	fr	Amazon.fr
イタリア	it	Amazon.it
スペイン	es	Amazon.es
メキシコ	mx	Amazon.com.mx
日本	jp	Amazon.co.jp

デフォルトのマーケットプレイスは us です。ユーザーが指定しない場合は、us を使用します。

呼び出し方法

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

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

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

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

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

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

異常な状況

• API Key が未設定：環境変数 LINKFOX_AGENT_API_KEY と LINKFOXAGENT_API_KEY のどちらも設定されていません。
• レスポンスのステータスコードが 401 または 402
• 計算リソースまたは残高が不足している旨のレスポンス：メッセージに「算力余额不足／计费不足／余额不足／quota exceeded／insufficient balance／套餐到期／需充值／请充值」、または類似の意味の内容が含まれている場合。

クエリの作成方法

4 つのパラメーターはすべて必須です：marketplace、keyword、startDate、endDate。

API 呼び出しの作成原則

1. マーケットプレイスの対応付け：ユーザーが「米国マーケットプレイス」と指定した場合は us、「日本マーケットプレイス」の場合は jp、「ドイツマーケットプレイス」の場合は de を使用します。指定がない場合はデフォルトの us を使用します
2. 日付形式：YYYY-MM-DD 形式を使用します（例：2025-01-05）
3. 期間：startDate から endDate までの期間は最長 366 日です。超過する場合は、複数回のリクエストに分割する必要があります
4. キーワード：ユーザーが指定したキーワードをそのまま渡します（英小文字が望ましい）
5. よく使う期間の算出方法：
   • 「過去 3 か月」→ endDate は今日、startDate は約 90 日前
   • 「昨年の通年」→ 2025-01-01 から 2025-12-31
   • 「繁忙期」→ 商品カテゴリーに基づいて判断します。例：第 4 四半期は 10-01 から 12-31

よくあるクエリの例

1. キーワードの直近 6 か月の検索トレンドを確認する

{
  "marketplace": "us",
  "keyword": "yoga mat",
  "startDate": "2025-10-01",
  "endDate": "2026-03-31"
}

2. キーワードの季節性を判断する（通年データを取得）

{
  "marketplace": "us",
  "keyword": "christmas decorations",
  "startDate": "2025-01-01",
  "endDate": "2025-12-31"
}

3. 繁忙期と閑散期の検索ボリュームを比較する

2 回に分けて呼び出します：

• 閑散期：startDate=2025-02-01, endDate=2025-04-30
• 繁忙期：startDate=2025-10-01, endDate=2025-12-31

4. 複数のマーケットプレイスを比較する

同じキーワードを異なるマーケットプレイス（例：us、de、jp）でそれぞれ検索し、各マーケットプレイスの検索ボリュームの規模を比較します。

5. 市場需要が増加しているかを検証する

{
  "marketplace": "de",
  "keyword": "luftreiniger",
  "startDate": "2025-04-01",
  "endDate": "2026-03-31"
}

表示ルール

1. トレンドの可視化を優先：検索ボリュームの変化は、時間軸または折れ線グラフで表示することを推奨します。横軸は日付の期間、縦軸は検索ボリュームとします
2. 補助として表を使用：正確に確認できるよう、データ表も併せて提供します。列には期間開始日、期間終了日、検索ボリュームを含めます
3. トレンドの要約：データの後に、トレンドの方向（上昇／下降／横ばい／周期的な変動）を簡潔にまとめ、ピークと谷の期間を明記します
4. ピークの表示：検索ボリュームが最高および最低の期間を強調表示し、ユーザーが繁忙期と閑散期をすばやく判断できるようにします
5. エラー処理：クエリが失敗した場合は、エラーレスポンスに基づいて理由を説明し、パラメーターの調整（例：日付範囲が 366 日を超えている場合）を提案します

重要な制限事項

• 期間の上限：1 回のクエリで指定できる startDate から endDate までの期間は最長 366 日です。超過する場合は、クエリを分割する必要があります
• データ粒度：週単位（7 日ごとに 1 データポイント）であり、日単位ではありません
• 検索ボリュームの種類：完全一致検索ボリューム（Exact Match）であり、部分一致ではありません
• すべてのパラメーターが必須：marketplace、keyword、startDate、endDate のいずれも省略できません

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

適用対象 - キーワード検索量の過去の傾向分析：

ユーザーの発言	シナリオ
"このキーワードの検索量はどう変化していますか"	検索量の傾向を確認
"このカテゴリに季節性はありますか"	年間データから季節的な傾向を判断
"検索量は最近増えていますか、それとも減っていますか"	最近の傾向を判断
"いつが繁忙期ですか"	ピーク期間を特定
"昨年のQ4の検索量はいくつでしたか"	指定期間の検索量を確認
"このキーワードはドイツのサイトで人気がありますか"	米国以外のサイトの検索量を確認
"2つの期間の検索量を比較してください"	繁忙期・閑散期または前年比を比較

適用対象外 - キーワードの過去の検索量の範囲外：

• キーワードの提案・キーワードの拡張（キーワード調査ツールが必要です）
• リアルタイムまたは現在の検索量ランキング（ABA または SIF ツールが必要です）
• キーワードの競争度、CPC 入札額
• 商品の販売数、出品情報の分析
• Amazon 以外のプラットフォームの検索量

適用範囲の判断：「検索量」「キーワードの人気度」「市場需要の傾向」といった言葉が使われていて、期間を通じたキーワードの検索量の変化（過去の傾向）を確認したい場合、このスキルが適用されます。現在のランキングや、人気上昇中のキーワード一覧を知りたい場合は適用されません。

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

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

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

フィードバック：

次のいずれかに該当する場合は、Feedback API を通じてフィードバックを自動検出し、報告してください。

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

references/api.md に記載されている方法でフィードバック API を呼び出してください。ユーザーの操作を中断しないでください。

---

高品質で専門的な越境ECスキルをお探しの場合は、LinkFox Skillsをご覧ください。