linkfox-keepa-product-series

Keepa 商品時系列データエクスプローラー

このスキルでは、Amazon 商品の過去の時系列データを照会・分析する方法を説明します。Amazon の販売者が、価格の動き、BSR の傾向、評価の変化など、商品に関する重要な指標を経時的に追跡できるよう支援します。

基本概念

このツールは、Keepa を利用して個々の Amazon 商品（ASIN）の過去の時系列データを提供します。さまざまな指標についてタイムスタンプ付きのデータポイントを返し、設定可能な期間（最大 365 日）で傾向を分析できます。各クエリの対象は、特定の Amazon マーケットプレイスにおける 1 つの ASIN です。

時系列データの形式：すべてのデータ系列は、{time, value} オブジェクトの配列として返されます。time はタイムスタンプ、value はその時点での指標値です。BSR データには、points 配列とともに categoryName フィールドが含まれます。保存された JSON から、これらのフィールドを直接分析してください。_dataQuery_executeDynamicQuery は SLS に保存された Linkfox セッションデータを読み取るもので、任意の JSON ファイルを読み取るものではありません。また、対応するデータマッピングによって、これらの時系列データを分析できるかどうかが決まるわけではありません。

BSR のロジック：BSR の値が小さいほど、販売ランキングは上位です。ランキング 1 位は、そのカテゴリーで最も売れている商品を意味します。ユーザーが「BSR が改善した」と言った場合、数値が下がったことを意味します。「BSR が下がった」と言った場合は、数値が上がったことを意味します。

利用可能なデータ系列

系列	パラメーター	説明
Buy Box 価格	(常に返されます)	経時的な Buy Box 価格
新品の最安価格	showPrice=1	マーケットプレイスにおける新品の最安価格
定価	showPriceList=1	取り消し線付き価格／定価
セール価格	showPriceDeal=1	タイムセール価格
Prime 限定価格	showPricePrime=1	Prime 限定の新品価格
FBA 価格	showPriceFba=1	第三者販売者による FBA 新品価格
FBM 価格	showPriceFbm=1	第三者販売者による FBM 新品価格
クーポン適用後の価格	showPriceCoupon=1	クーポン適用後の Buy Box 価格
メインカテゴリー BSR	showBsrMain=1	メイン（ルート）カテゴリーでのベストセラーランキング
販売者数	showSellerCount=1	アクティブな販売者の数
評価	(常に返されます)	経時的な商品の星評価
評価数	(常に返されます)	経時的な評価数
月間販売数	(常に返されます)	月間販売数量
サブカテゴリー BSR	(常に返されます)	サブカテゴリーでのベストセラーランキング

対応マーケットプレイス

ドメイン ID	マーケットプレイス
1	Amazon.com（米国）
2	Amazon.co.uk（英国）
3	Amazon.de（ドイツ）
4	Amazon.fr（フランス）
5	Amazon.co.jp（日本）
6	Amazon.ca（カナダ）
8	Amazon.it（イタリア）
9	Amazon.es（スペイン）
10	Amazon.in（インド）
11	Amazon.com.mx（メキシコ）
12	Amazon.com.br（ブラジル）

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

呼び出し方法

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

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

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

パラメーターガイド

必須パラメーター

• asin：照会する Amazon Standard Identification Number です。1 回のリクエストで指定できる ASIN は 1 つだけです。
• domain：Amazon マーケットプレイスのドメイン ID です（上の表を参照）。ユーザーが言及したマーケットプレイスを、必ず正しい数値 ID に対応付けてください。

オプションのパラメーター

• days：取得する過去の日数です（1～365、デフォルトは 90）。短期分析には 30、中期分析には 90、長期分析には 365 を使用します。
• show* フラグ：データ系列を含めるには、任意の show* パラメーターを 1 に設定します。デフォルトでは、主要な系列（Buy Box 価格、評価、評価件数、月間販売数、サブカテゴリーの BSR）のみが返されます。

パラメーターの選び方

1. 価格分析：ユーザーが希望する具体的な価格比較に応じて、必要な showPrice、showPriceList、showPriceDeal、showPriceCoupon を有効にします。
2. FBA と FBM の比較：showPriceFba と showPriceFbm の両方を有効にします。
3. BSR の詳細分析：showBsrMain を有効にすると、常に返されるサブカテゴリーの BSR に加えて、ルートカテゴリーの BSR を取得できます。
4. 競合状況：showSellerCount を有効にすると、競合している出品者の数を確認できます。
5. 商品の全体像：包括的な過去のスナップショットを取得するには、すべての show フラグを有効にします。

使用例

1. 米国商品の基本的な価格履歴

asin: B0XXXXXXXX, domain: 1, days: 90

2. ドイツのマーケットプレイスにおける長期的な BSR の推移（1 年）

asin: B0XXXXXXXX, domain: 3, days: 365, showBsrMain: 1

3. フルフィルメントチャネル間の価格比較

asin: B0XXXXXXXX, domain: 1, days: 30, showPriceFba: 1, showPriceFbm: 1, showPrice: 1

4. セール価格とクーポン価格の追跡

asin: B0XXXXXXXX, domain: 1, days: 90, showPriceDeal: 1, showPriceCoupon: 1

5. 商品の総合的な状態チェック

asin: B0XXXXXXXX, domain: 1, days: 90, showPrice: 1, showPriceList: 1, showPriceDeal: 1, showPricePrime: 1, showPriceFba: 1, showPriceFbm: 1, showPriceCoupon: 1, showBsrMain: 1, showSellerCount: 1

表示ルール

1. データを明確に提示する：時系列データは表で示すか、傾向を説明してください。ユーザーが明示的に求めない限り、主観的なビジネス上の助言は避けてください。
2. BSR の説明：BSR データを表示するときは、数値が低いほど販売ランクが高いことをユーザーに伝えてください。
3. 価格の表示形式：マーケットプレイスに合った通貨記号（米国は $、ドイツ／フランス／スペイン／イタリアは EUR、英国は GBP、日本は JPY など）を付けて価格を表示してください。
4. 時刻の表示形式：タイムスタンプは人が読みやすい日付形式で表示してください。
5. 傾向の要約：データ系列が長い場合は、全体的な傾向（例：「90 日間で価格が $29.99 から $24.99 に下落しました」）を要約し、価格の急落、BSR の急上昇、評価の変化など、重要な変化を強調してください。
6. エラー処理：クエリに失敗した場合は、その理由を説明し、修正方法（例：ASIN が有効か確認する、マーケットプレイスのドメイン ID を確認する）を提案してください。
7. ASIN は 1 つのみ：ユーザーが複数の ASIN について尋ねた場合、クエリは一度に 1 つの ASIN に対して実行する必要があることを伝え、複数回に分けて順次呼び出してください。

重要な制限事項

• クエリごとに ASIN は 1 つのみ：一度に照会できる ASIN は 1 つだけです。複数の ASIN を比較する場合は、リクエストを個別に実行してください。
• 最大 365 日：取得できる過去のデータは、最大 365 日前までです。
• データの粒度：データポイントの間隔は固定の日次ではなく、Keepa が変更を記録したタイミングに応じて不規則になります。

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

該当するケース -- Amazon の商品レベルの過去データに関するクエリ：

ユーザーの発言	シナリオ
"この ASIN の価格推移は？"	価格推移分析
"BSR の推移を見せて", "ランキングはどうなってる？"	BSR の追跡
"最近、価格は下がった？", "お買い得品はある？"	価格下落／お買い得品の検出
"この出品のセラー数は？"	セラー数の推移
"評価の推移は？", "レビュー数の経時変化を見せて"	評価／レビューの追跡
"FBA と FBM の価格", "Buy Box を獲得しているのは誰？"	フルフィルメント価格の比較
"この商品の月間販売数は？"	販売数量の推移
"この ASIN で価格競争はあった？"	競合価格分析
"Keepa のグラフを見せて", "Keepa のデータを見せて"	Keepa データの明示的なリクエスト

該当しないケース -- 商品レベルの過去データの範囲を超えるニーズ：

• 検索語／キーワード分析（代わりに ABA データを使用）
• 広告／PPC キャンペーンデータ
• 出品情報のコピーライティングやコンテンツの最適化
• カテゴリー全体または市場レベルの集計トレンド（このツールは ASIN ごとのデータのみを対象とします）
• リアルタイムの在庫数や在庫状況の確認
• 商品レビューのテキストやセンチメント分析

適用範囲の判断：「商品リサーチ」や「競合分析」と言われた場合でも、特定の ASIN の過去の価格、BSR、販売データの調査が目的であれば、このスキルが該当します。キーワードデータ、市場全体のトレンド、広告指標が必要な場合は該当しません。

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

動的なルールに基づいて課金されます：計算リソースの消費量 = 0.045 × 今回の過去トレンドクエリで消費した Keepa トークン。

重要：このスキルのサービス料金は動的に倍率計算され、一度に大量の計算リソースを消費する場合があります。必ずユーザーに知らせ、続行するかどうかはユーザーに判断してもらってください。

フィードバック：

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

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

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

---

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