linkfox-aba-intelligent-query

ABA データエクスプローラー

このスキルでは、ABA 検索語データのクエリと分析の方法を説明します。Amazon セラーが ABA 検索語レポートから価値のあるインサイトを抽出できるよう支援します。

主な概念

ABA（Amazon Brand Analytics）検索語レポートは、Amazon における実際の消費者の検索行動を反映した、Amazon 公式の検索行動データです。このツールには、15 の Amazon マーケットプレイスにわたる、ほぼ 3 年分の週単位のデータが含まれています。

ランキングの仕組み：searchFrequencyRank の値が小さいほど、検索人気度が高いことを意味します。ランク 1 が最も人気のある検索語です。ここは混乱しやすい点です。「ランキングが上がった」とは数値が小さくなったことを意味し、「ランキングが下がった」とは数値が大きくなったことを意味します。

データフィールド

フィールド	API 名	説明	例
検索語	searchTerm	消費者が検索したキーワード	rimel loreal
レポート開始日	reportStartDate	データ収集週の開始日	2025-10-26
地域	region	Amazon マーケットプレイスのコード	US
検索頻度ランク	searchFrequencyRank	検索人気度のランク（数値が小さいほど上位）	82135
クリックされた ASIN	clickedAsin	クリックされた商品の ASIN	B0XXXXXXXX
クリックされた商品名	clickedItemName	クリックされた商品の名前	xxx
クリックシェアランク	clickShareRank	この検索語における、この ASIN のクリックシェアランク	1
クリックシェア	clickShare	この ASIN が獲得したクリックシェア（0～1）	0.28
コンバージョンシェア	conversionShare	この ASIN が獲得したコンバージョンシェア（0～1）	0.3333

対応マーケットプレイス

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

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

呼び出し方法

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

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

• 常にレスポンス全体を <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-aba-intelligent-query-<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／套餐到期／需充值／请充值」、または同様の意味の内容が含まれる場合。

クエリの作成方法

このツールを呼び出す際の重要なパラメーターは analysisDescription です。これは、クエリしたいデータを自然言語で説明するものです。この説明はバックエンドで構造化されたクエリに変換されるため、正確かつ具体的である必要があります。

analysisDescription を作成する際の原則

1. マーケットプレイスを指定する：必ず冒頭でマーケットプレイスを明記します。例：「米国のマーケットプレイスを絞り込む」
2. フィルター条件を具体的にする：曖昧な表現ではなく、具体的な数値範囲を指定します。「ランキングが5万位以内」は、「ランキングが良い」よりもはるかに効果的です。
3. 期間を指定する：例：「過去12週間」「2024年1～9月」「直近3か月」のように、具体的な期間を指定します。
4. 比較基準を指定する：トレンド分析では、比較する時点を明確にします。例：「4週間前のランキングは8週間前と比べて30％上昇」
5. 重複排除のルールを指定する：同じ検索語とASINの組み合わせに複数のレコードがある場合、どのレコードを残すかを指定します。例：「同じ検索語とASINの値が重複する場合は、最新のレコードのみを残す」
6. ユーザーの意図に忠実である：ユーザーのクエリを誤解したり、範囲を広げすぎたりせず、求めている内容をそのまま反映します。

よくあるシナリオの analysisDescription 例

1. 検索語の人気度の推移

筛选美国站，关键词"gift"在过去12周的搜索热度排名。

2. 急上昇中のダークホースキーワード

筛选美国站，关键词包含"gift"，2025年Q1和全年的平均搜索排名都大于50万，但最新排名冲进5万-10万的搜索词。

3. 継続的な成長トレンドの発見

筛选美国站，最新排名在20万以内，且4周前的排名比8周前提升30%，本周的排名比4周前提升30%的搜索词。

4. 市場機会の発見（検索ボリュームが多く、独占度が低い）

筛选美国站，筛选当前搜索排名在20000以内，近三个月点击占比Top 1的Asin的转化率占比低于5%的搜索词。相同搜索词相同Asin值保留最新的一个。

5. 季節・祝日関連キーワードのターゲティング

筛选美国站，包含"cup"的关键词中，去年（2024年）1-9月份排名未进入50万，10-11月份连续进入20万的词。

6. クリック数が多く、コンバージョン率が低いASINの発掘

筛选美国站关键词包含"hat"的，最新搜索排名在5万-20万之间，且近3个月来点击占比大于20%，转化占比小于10%的ASIN。相同搜索词和ASIN仅保留点击占比和转化占比的比例最小数据。

7. ROASの高いロングテールのブルーオーシャンキーワード

筛选美国站，关键词包含"charger"的，当前排名在20万开外的，近2个月的平均转化占比大于平均转化占比1.5倍的关键词，以及相应的ASIN。

8. 新しい市場用語と新たな需要の検出

找到美国站"charger"的长尾词中，近一个月才进入排名榜单，且当前排名在50万以内的所有词。

9. ニッチなトレンド・バリエーションの成長獲得

筛选美国站中"table"的长尾词中，排名在10万-30万之间，且近4周的搜索排名增长50%以上的搜索词。

表示ルール

1. データのみを提示する：クエリ結果は、主観的なビジネスアドバイスを含めず、わかりやすい表で示します。
2. ランキングを明確にする：ランキングデータを表示する際は、数値が小さいほどランキングが高いことをユーザーに伝えます。
3. ボリュームに関する注意：結果が大量の場合は、主要なデータを表示し、ダウンロードリンクから全データを取得できることをユーザーに伝えます。
4. ダウンロード方法を案内する：応答に downloadUrl が含まれる場合は、ダウンロード先を明確に伝えます。ユーザーが全データを必要としているもののダウンロードを依頼していない場合は、ダウンロードリンクの生成を積極的に提案します。
5. エラー処理：クエリが失敗した場合は、msg フィールドに基づいて理由を説明し、クエリ条件の調整を提案します。

重要な制限事項

• 結果の上限：ダウンロードリンクに含められるレコードは最大10,000件です。
• データの粒度：データは週単位であり、日単位ではありません。
• データ範囲：過去約3年分の履歴データです。

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

該当するもの — Amazonの検索語に関するデータクエリ：

ユーザーの表現	シナリオ
「XXというキーワードの検索ボリューム・人気度はどうですか」	ランキングの推移
「最近話題のキーワード」「新たに登場した用語」	ダークホース・新語の検出
「ブルーオーシャンキーワード」「競争の少ない用語」	市場機会の発見
「どのキーワードがよくコンバージョンしますか」「コンバージョン率の高いロングテール」	ROASの高いキーワードライブラリ
「季節キーワード」「ピークシーズンに急増する用語」	季節キーワード
「誰がトラフィックを獲得していますか」「独占状態ですか」	クリックシェア・独占度の分析
「クリック数は多いがコンバージョン率が低いASIN」	クリック数が多く、コンバージョン率が低い場合の診断

該当しないもの — ABAの検索語データを超える情報が必要な場合：

• 広告・PPC（入札、キャンペーン戦略）
• 商品レビュー、商品リストのコピーライティング
• ASINの売上推定
• ユーザーが処理対象のABAファイルをすでにローカルに持っている場合

適用範囲の判断：「商品リサーチ」「競合分析」「市場機会があるか」といった依頼でも、検索語単位のデータクエリ（ブルーオーシャンキーワードの発見、キーワード別の競合トラフィック分布の分析など）に帰結する場合は、このスキルが該当します。利益率、価格戦略、包括的な市場レポートについて尋ねている場合は該当しません。

計算リソース消費ルール

動的ルールに基づいて課金されます：消費計算リソース = SQL の初期生成にかかる計算リソース + Σ(各成功タスクの実行・再試行にかかる計算リソース) + round(CSVファイルサイズMB × 0.075)。各項目の token はすべて inputTokens + outputTokens を指します。成功したタスクのみ課金され、成功したタスクがない場合は 0 です。

重要：本スキルのサービス料金は倍率に応じて動的に計算されるため、一度に大量の計算リソースを消費する可能性があります。必ずユーザーに伝え、続行するかどうかはユーザーに判断してもらってください。

フィードバック：

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

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

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

---

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