linkfox-keepa-product-detail

Keepa 商品データリクエスト

このスキルでは、Keepa 商品リクエスト API を介して Amazon 商品の詳細を取得する方法を説明します。Amazon の販売者やアナリストが、複数の Amazon マーケットプレイスにおいて、1 つ以上の ASIN の構造化された商品データを取得できます。

基本概念

Keepa 商品リクエスト API は、Keepa を通じて取得した Amazon の詳細な商品出品データを返します。1 つ以上の ASIN とマーケットプレイスを指定すると、価格、タイトル、メイン画像、出品日、素材、重量、寸法、販売ランキング、月間販売個数（現在および過去最大 12 か月分の履歴）、FBA 手数料、評価、レビュー件数、カテゴリー階層など、包括的な商品情報が返されます。

重要なポイント：

• 1 回のリクエストで、カンマ区切りで最大 100 個の ASIN を照会できます。
• domain パラメーターは数値のマーケットプレイス ID（例：1 = Amazon.com（米国））であり、国コードではありません。
• history を 1 に設定すると、販売履歴データ（月間販売数の過去 12 か月分まで、過去 30／90／180 日間の平均販売ランキング）が含まれます。0 に設定すると、現在の商品情報のみが返されます。
• レスポンスには、商品説明やレビュー本文は含まれません。

パラメーターガイド

domain（必須）

数値の Amazon マーケットプレイス ID です。対応表は以下のとおりです。

Domain ID	マーケットプレイス
1	Amazon.com (US)
2	Amazon.co.uk (UK)
3	Amazon.de (Germany)
4	Amazon.fr (France)
5	Amazon.co.jp (Japan)
6	Amazon.ca (Canada)
8	Amazon.it (Italy)
9	Amazon.es (Spain)
10	Amazon.in (India)
11	Amazon.com.mx (Mexico)
12	Amazon.com.br (Brazil)

ユーザーがマーケットプレイスを指定しない場合は、1（米国）をデフォルトにします。

asin（必須）

Amazon 標準識別番号です。複数の ASIN を指定する場合は、カンマで区切ります。1 回のリクエストで最大 100 個の ASIN を指定でき、文字列の合計長は最大 3000 文字です。

history（任意）

過去 12 か月分の月間販売数や、過去 30／90／180 日間の平均販売ランキングなどの履歴データを含めるかどうかを指定します。履歴を含めるには 1、基本情報のみを返すには 0（デフォルト）を設定します。

使用例

1. 単一 ASIN の検索（米国マーケットプレイス、基本情報）

{"asin": "B0088PUEPK", "domain": "1"}

2. 販売履歴データを含む単一 ASIN

{"asin": "B0088PUEPK", "domain": "1", "history": 1}

3. 複数 ASIN の一括検索（ドイツ）

{"asin": "B0088PUEPK,B00U26V4VQ,B07M68S376", "domain": "3", "history": 1}

4. Amazon Japan での商品検索

{"asin": "B09V3KXJPB", "domain": "5", "history": 0}

5. 複数 ASIN にわたる競合比較（米国、販売履歴付き）

{"asin": "B0CXYZ1234,B0CXYZ5678,B0CXYZ9012,B0CXYZABCD", "domain": "1", "history": 1}

API の使用方法

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

表示ルール

1. データをわかりやすく表示する：商品詳細を、構造化された見やすい表にまとめます。関連する項目（寸法、販売データなど）はグループ化して、読みやすくします。
2. 価格と通貨：価格は必ず通貨と併記します（例：「$29.99 USD」）。レスポンスの currency フィールドに現地通貨が示されます。
3. 販売傾向：履歴データが含まれる場合は、12 か月間の販売傾向を表にまとめるか、推移（成長、減少、安定）を説明して、ユーザーが販売の勢いをすばやく把握できるようにします。
4. 寸法と重量：必要に応じてミリメートルの値をより直感的な単位に換算します（例：mm とインチ、または mm と cm の両方を表示）。重量の単位はグラムです。
5. 取得できないデータ：値が 0 または -1 のフィールドは、データを取得できないことを示します。実際の測定値として表示せず、「該当なし」と記すか、省略します。
6. 画像の表示：imageUrl がある場合は、ユーザーが商品を目で確認できるよう商品画像を表示します。
7. エラー処理：クエリが失敗した場合は、レスポンスに基づいて問題を説明し、修正方法（無効な ASIN 形式、未対応のマーケットプレイスなど）を提案します。
8. 大量の一括検索結果：多数の ASIN を一括検索した場合は、まず概要表を提示し、必要に応じて個々の商品詳細も表示できることを案内します。

重要な制限事項

• 商品説明やレビューは取得できません：API は商品説明文やレビューの内容を返しません。
• 1 リクエストあたりの ASIN は最大 100 件：一括クエリで指定できる ASIN は最大 100 件です。
• ASIN 文字列の長さ制限：asin パラメーターの最大文字数は 3000 文字です。
• 過去のデータは任意です：月間販売履歴は、history を 1 に設定した場合にのみ返されます。
• データの鮮度：lastUpdate フィールドは、商品データが最後に更新された日時を示します。

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

該当する — ASIN による商品データの取得：

ユーザーの発言	シナリオ
「この ASIN を調べて」、「B0XXXXXXXX の商品詳細を取得して」	単一 ASIN の検索
「この商品の Amazon での価格は？」	価格の照会
「この商品は月に何個売れていますか？」	月間販売数の確認
「これらの ASIN を比較して」、「これらの商品を一括検索して」	複数 ASIN の比較
「この ASIN の販売動向を見せて」	過去の販売データの分析
「この商品はどのカテゴリーに属していますか？」	カテゴリー／分類の検索
「商品の寸法」、「重さはどのくらい？」	物理的仕様の照会
「この商品の FBA 手数料」	手数料の見積もり
「この商品が出品されたのはいつですか？」、「出品日」	出品期間／発売日の確認
「この商品は FBA と FBM のどちらですか？」	配送方法の確認

該当しない — ASIN レベルの商品データを超える情報が必要な場合：

• 検索語／キーワード分析（代わりに ABA データツールを使用してください）
• 商品レビューや商品ページのコピーライティングコンテンツ
• 広告／PPC キャンペーンデータ
• セラーアカウントまたはストアレベルの分析
• 特定の ASIN を指定しない商品リサーチ（例：「キッチンカテゴリーで人気上昇中の商品を探して」）
• 価格履歴チャートや Buy Box の経時的な履歴（利用できるのは現在のランクと平均ランクのデータのみです）

適用範囲の判断：「商品リサーチ」や「競合分析」とユーザーが言った場合でも、特定の ASIN があり、価格、販売数、寸法、カテゴリーなどの構造化された商品データを求めているなら、このスキルが該当します。キーワードレベルの分析、特定の ASIN を指定しない市場全体の動向、または広告指標を求めている場合、このスキルは該当しません。

フィードバック：

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

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

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

大きなレスポンスの処理

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

python scripts/response_io.py run --script scripts/keepa_product_detail.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 Skills を設定してください。