linkfox-keepa-product-history

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

このスキルでは、Amazon 商品の過去の時系列データを照会・分析し、Amazon セラーが価格の変動、BSR の傾向、評価の変化、その他の主要な商品指標を時系列で追跡する方法を説明します。

主な概念

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

時系列の形式：すべてのデータ系列は、{time, value} オブジェクトの配列として返されます。time はタイムスタンプ、value はその時点の指標の値です。BSR データには、points 配列とともに categoryName フィールドが含まれます。

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 の使用方法

このツールは LinkFox ツールゲートウェイ API を呼び出します。呼び出し方法、リクエストパラメーター、レスポンスの構造については、references/api.md を参照してください。クエリを実行するには、scripts/keepa_product_history.py を直接実行することもできます。

パラメーターガイド

必須パラメーター

• asin：照会する Amazon 標準識別番号です。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. 商品の全体像：すべての表示フラグを有効にすると、包括的な過去のスナップショットを取得できます。

使用例

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 回につき 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、販売データの確認にあたるなら、このスキルが適用されます。キーワードデータ、市場全体のトレンド、広告指標が必要な場合は適用されません。

フィードバック：

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

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

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

大きなレスポンスの処理

エージェントのコンテキストがあふれないよう、レスポンスをディスクに保存し、必要なフィールドのみを抽出してください。

python scripts/response_io.py run --script scripts/keepa_product_history.py --out-dir <DIR> '<params>'
python scripts/response_io.py read <file> --fields "<paths>"   # or --path "<JMESPath>"

--out-dir は、Git の作業ツリー外に指定してください（例：Unix では /tmp/...、Windows では %TEMP%/...）。保存されたレスポンスには、PII、価格、認証に関する機密データが含まれる場合があります。コミットしないでください。ファイルは自動削除されないため、作業が終わったら削除してください。

run は完全なレスポンスをファイルに書き込み、スキーマのプレビューとファイルパスのみを出力します。read は特定のフィールドを抽出し、スライスには --limit/--offset、出力形式には --format json|jsonl|csv|table を指定できます。

この方法を優先する場合 — たとえば、次のようなレスポンスの特性に応じて判断してください：

• レコードあたりのフィールド数が多い、または不要なフィールドがある
• バッチ／ページ分割された結果（1 回の呼び出しで複数の項目を取得）
• 長文フィールド（説明、レビュー、HTML、時系列データ）
• すぐに使用するのではなく、後続のステップでも出力を再利用する

小規模で一度しか使わないレスポンスの場合は、メインスクリプトを直接呼び出してもかまいません。

⚠️ プレビューは、スキーマとサンプルを省略表示したものであり、全データではありません。フィールド単位の判断には、read を使って保存済みファイルから読み込んでください。

---

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