linkfox-keepa-product-request

Keepa 商品データのリクエスト

このスキルでは、Keepa Product Request API を使って Amazon の商品詳細を取得する方法を説明します。Amazon のセラーやアナリストが、複数の Amazon マーケットプレイスから 1 つ以上の ASIN に関する構造化商品データを取得するのに役立ちます。

基本概念

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

重要なポイント：

• 1 回のリクエストで、カンマ区切りで最大 5 件の ASIN を照会できます。
• domain パラメーターには、国コードではなく数値のマーケットプレイス ID を指定します（例：1 = Amazon.com US）。
• history を 1 に設定すると、過去の販売データが含まれます（月間販売数の過去最大 12 か月分、過去 30／90／180 日間の平均販売ランキング）。0 に設定すると、現在の商品情報のみが返されます。
• products[].itemHighlights は、title とは別の短い商品情報をまとめた単一の文字列です。null、空欄、または未設定の場合があります。追加のリクエストパラメーターは不要で、history=0 でも返されることがあります。
• レスポンスには、商品説明の全文やレビュー内容は含まれません。商品ハイライトは、箇条書き（features）や説明文の全文とは異なります。

パラメーターガイド

domain（必須）

Amazon マーケットプレイスの数値 ID です。対応関係は次のとおりです。

Domain ID	Marketplace
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（US）をデフォルトとして使用します。

asin（必須）

Amazon 標準商品識別番号を 1 つ以上指定します。複数の ASIN を指定する場合は、カンマで区切ります。1 回のリクエストで指定できる ASIN は最大 5 件で、文字列全体の長さは 300 文字までです。

history（任意）

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

使用例

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

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

2. 過去の販売データを含む単一 ASIN の検索

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

3. 複数 ASIN の一括検索（Germany）

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

4. Amazon Japan での商品検索

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

5. 複数 ASIN にわたる競合比較（US、販売履歴あり）

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

呼び出し方法

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

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

• 常に完全なレスポンスを <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-keepa-product-request-<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／プランの期限切れ／チャージが必要／チャージしてください」または同様の意味の内容が含まれている。

表示ルール

1. データを明確に提示する：商品情報を、適切に整理された表で表示します。読みやすくするため、関連する項目（寸法、販売データなど）はグループ化します。
2. 価格と通貨：価格は必ず通貨と併記します（例：「$29.99 USD」）。レスポンスの currency フィールドは現地通貨を示します。
3. 販売動向：過去のデータが含まれている場合は、12 か月間の販売動向を表で提示するか、軌跡（増加、減少、横ばい）を説明し、ユーザーが勢いをすばやく把握できるようにします。
4. 寸法と重量：必要に応じて、ミリメートルの値をより直感的な単位に換算します（例：mm とインチ、または mm と cm の両方を表示します）。重量はグラム単位です。
5. 利用できないデータ：値が 0 または -1 のフィールドは、データを利用できないことを示します。実際の測定値として表示せず、「N/A」と記載するか、省略します。
6. 画像の表示：imageUrl がある場合は、ユーザーが商品を視覚的に識別できるように商品画像を表示します。
7. エラー処理：クエリに失敗した場合は、レスポンスに基づいて問題を説明し、修正方法を提案します（例：無効な ASIN 形式、未対応のマーケットプレイス）。
8. 大量の一括結果：ASIN を多数含む一括クエリでは、まず概要表を提示し、リクエストに応じて個々の商品詳細を表示します。
9. 商品ハイライト：stdout の概要や columns だけでなく、完全なレスポンスから products[].itemHighlights を読み取ります。title とは別に、元の値を表示します。欠落している場合、null の場合、または空白の場合は「未返回/不可用」と表示します。Amazon の商品ページに記載がないと推測したり、タイトル、箇条書き、説明文から再構成したりしないでください。

重要な制限事項

• 商品説明全文やレビューは取得できません：API から取得できるのは短い商品ハイライトであり、商品説明の全文やレビュー内容は取得できません。
• 商品ハイライトの利用可否：itemHighlights を引き継ぎ、上流でデータが利用可能なバックエンドのデプロイが必要です。すべての ASIN で値が取得できると約束しないでください。
• リクエストあたりの ASIN は最大 5 件：一括クエリで指定できる ASIN は最大 5 件です。
• ASIN 文字列の長さ制限：asin パラメーターの最大長は 300 文字です。
• 過去データは任意です：月別販売履歴は、history が 1 に設定されている場合にのみ返されます。
• データの鮮度：lastUpdate フィールドは、商品データが最後に更新された日時を示します。

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

適用対象 -- ASIN による商品データの取得：

ユーザーの発言	シナリオ
"Look up this ASIN", "Get product details for B0XXXXXXXX"	単一 ASIN の検索
"查这个 ASIN 的 Item Highlights", "标题之外的商品亮点/补充信息"	title とは別に、既存の itemHighlights を取得
"What's the price of this product on Amazon"	価格の照会
"How many units does this product sell per month"	月間販売数の確認
"Compare these ASINs", "batch lookup these products"	複数 ASIN の比較
"Show me the sales trend for this ASIN"	過去の販売データ分析
"What category is this product in"	カテゴリ／分類の照会
"Product dimensions", "how much does it weigh"	サイズ・重量の照会
"FBA fees for this product"	手数料の見積もり
"When was this product listed", "listing date"	出品期間／発売日の確認
"Is this product FBA or FBM"	出荷方法の確認

適用対象外 -- ASIN 単位の商品データを超える情報が必要な場合：

• 検索語／キーワード分析（代わりに ABA データツールを使用してください）
• 商品の全説明文、レビューのテキスト、または新しい出品文の作成（既存の title と itemHighlights の取得には対応しています）
• 広告／PPC キャンペーンデータ
• セラーアカウントまたはストア単位の分析データ
• 特定の ASIN を指定しない商品リサーチ（例：「キッチンカテゴリで人気上昇中の商品を探して」）
• 価格履歴チャートまたは Buy Box の経時的な履歴（利用できるのは現在のランキングデータと平均ランキングデータのみです）

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

計算リソース消費ルール

動的ルールに基づいて課金されます：計算リソースの消費量 = 0.045 × 今回の商品詳細の照会で消費した Keepa token 数。

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

フィードバック：

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

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

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

---

高品質で専門的な越境 EC スキルをさらに利用するには、LinkFox Skills を設定してください。