linkfox-keepa-product-search

Keepa 商品検索

このスキルでは、Keepa の広範な商品データベースを使って Amazon の商品を検索・絞り込む方法を説明します。Amazon の出品者が、複数の条件にわたって特定の基準に合う商品を見つけるのに役立ちます。

基本概念

このツールは、Keepa のデータを活用した高度な Amazon 商品検索を提供します。シンプルな Amazon ストアフロントの検索とは異なり、カテゴリー、価格帯、月間販売数、BSR（ベストセラーランキング）、キーワードの一致（含める語句と除外する語句）、レビュー数、評価、パッケージの寸法、重量、配送方法、過去の販売ランキングなど、複数の条件で絞り込めます。価格、商品タイトル、画像、出品日、素材、重量、過去 12 か月間の月間販売数などを含む、詳細な商品データを返します。

BSR（ベストセラーランキング）：salesRank の値が小さいほど、販売実績が優れています。ランキング 1 位は、そのカテゴリーで最も売れている商品です。「売れ筋商品」と指定された場合、BSR の値が小さい商品を指します。

価格の単位：価格は最小通貨単位（例：USD の場合はセント）で表されます。そのため、$25.99 は 2599 です。クエリの作成時と結果の表示時には、必ず換算してください。

カテゴリー名：categoriesIncludeNames パラメーターでは、複数階層のカテゴリーのパスを、コロン : または > で区切って指定できます。ユーザーの入力を適切な形式に自動変換してください。

パラメーター

マーケットプレイス（必須）

パラメーター	型	必須	説明	デフォルト
domain	string	はい	Amazon マーケットプレイス ID	-

Domain ID の対応表：

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（メキシコ）

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

キーワードによる絞り込み

パラメーター	型	説明
keyword	string	タイトルのキーワードフィルター（大文字と小文字を区別しません。スペースは AND 条件として扱われます。フレーズは二重引用符で囲みます。除外する場合は先頭に - を付けます。& はスペースに置換されます。キーワードは最大 50 個、文字数は最大 1000 文字）

カテゴリーによる絞り込み

パラメーター	型	説明
rootCategory	array[int]	ルートカテゴリー ID（最大 50 個）
rootCategoryNames	array[string]	ルートカテゴリー名（最大 50 個）。rootCategory が空の場合に使用され、システムが ID を自動解決します
categoriesInclude	array[int]	含めるサブカテゴリー ID（最大 50 個）
categoriesIncludeNames	array[string]	含めるサブカテゴリー名（最大 50 個）。: または > 区切りのカテゴリー全体のパスに対応します
categoriesExclude	array[int]	除外するサブカテゴリー ID（最大 50 個）
categoriesExcludeNames	array[string]	除外するサブカテゴリー名（最大 50 個）。カテゴリー全体のパスに対応します

販売数・ランキングによる絞り込み

パラメーター	型	説明
currentSalesGte	integer	現在の BSR — 最小値（数値が大きいほどランキングが低い）
currentSalesLte	integer	現在の BSR — 最大値（数値が小さいほどランキングが高い）
avg90SalesGte	integer	90 日間の平均 BSR — 最小値
avg90SalesLte	integer	90 日間の平均 BSR — 最大値
deltaPercent90SalesGte	integer	90 日間の BSR 変化率 — 最小値
deltaPercent90SalesLte	integer	90 日間の BSR 変化率 — 最大値
monthlySoldGte	integer	月間販売数 — 最小値
monthlySoldLte	integer	月間販売数 — 最大値
srAvgGte	integer	過去の平均 BSR — 最小値（特定の月）
srAvgLte	integer	過去の平均 BSR — 最大値（特定の月）
srAvgMonth	string	過去の BSR の対象月（形式：YYYYMM、過去 36 か月以内）

価格フィルター

パラメーター	型	説明
currentNewGte	integer	現在の新品価格 -- 最低値（通貨の最小単位）
currentNewLte	integer	現在の新品価格 -- 最高値（通貨の最小単位）
currentBuyBoxShippingGte	integer	送料込みの現在のBuy Box価格 -- 最低値（通貨の最小単位）
currentBuyBoxShippingLte	integer	送料込みの現在のBuy Box価格 -- 最高値（通貨の最小単位）

レビュー・評価フィルター

パラメーター	型	説明
currentCountReviewsGte	integer	レビュー数 -- 最小値
currentCountReviewsLte	integer	レビュー数 -- 最大値
currentRatingGte	number	評価 -- 最低値（0.0-5.0）
currentRatingLte	number	評価 -- 最高値（0.0-5.0）

パッケージ・寸法フィルター

パラメーター	型	説明
packageLengthGte / packageLengthLte	integer	パッケージの長さの範囲（mm）
packageWidthGte / packageWidthLte	integer	パッケージの幅の範囲（mm）
packageHeightGte / packageHeightLte	integer	パッケージの高さの範囲（mm）
packageWeightGte / packageWeightLte	integer	パッケージの重量の範囲（グラム）

その他のフィルター

パラメーター	型	説明
brand	array[string]	ブランド名（OR一致）
color	array[string]	色（OR一致）
size	array[string]	サイズ（OR一致）
availableDateGte / availableDateLte	string	出品日の範囲（yyyy-MM-dd）
buyBoxIsAmazon	boolean	Buy Boxの販売者がAmazonであるか
buyBoxIsFBA	boolean	Buy BoxがFBAで配送されるか
isHazMat	boolean	危険物フラグ
variationCountGte / variationCountLte	integer	バリエーション数の範囲
currentCountNewGte / currentCountNewLte	integer	新品オファー数の範囲
outOfStockPercentage90Gte / outOfStockPercentage90Lte	integer	過去90日間の在庫切れ率の範囲
singleVariation	boolean	親ASINごとに1つのバリエーションのみを返す
productType	array[int]	商品タイプ：0=標準、1=ダウンロード可能、2=電子書籍、5=バリエーション親

データオプション

パラメーター	型	説明	デフォルト
history	integer	履歴データを含める（価格履歴、販売ランク、月別販売数）	0（いいえ）
rating	integer	評価情報を含める	1（はい）

ページネーション・並べ替え

パラメーター	型	説明	デフォルト
page	integer	ページ番号（1から開始）	1
perPage	integer	1ページあたりの結果数（最小50、最大100）	50
sort	array[object]	並べ替えルール（最大3件）。各オブジェクト：`{"fieldName": "...", "sortDirection": "asc	desc"}`

並べ替え可能なフィールド：availableDate、currentSales、monthlySold、currentRating、currentCountReviews、currentBuyBoxShipping、currentNew

呼び出し方法

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

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

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

クエリの作成方法

ユーザーの意図に基づいてリクエストパラメーターを作成します。

1. マーケットプレイスを特定する：ユーザーが指定した対象国を、適切な domain ID 値に対応付けます
2. キーワードフィルターを設定する：タイトルによる絞り込みに、肯定語と除外語を指定した keyword を使用します
3. カテゴリー範囲を設定する：カテゴリーで絞り込むには categoriesIncludeNames または rootCategoryNames を使用し、ユーザーの入力を適切なカテゴリーのパス形式に変換します
4. 数値フィルターを適用する：販売数、価格、BSR、レビュー数、評価の条件を、適切な Gte/Lte パラメーターに対応付けます
5. 並べ替え順を設定する：販売数、価格、評価で結果を並べ替えたい場合は、sort 配列を設定します
6. 履歴データを有効にする：月間販売数の推移または価格履歴が必要な場合は、history を 1 に設定します

使用例

1. 米国のマーケットプレイスで、月間販売数が1000を超える電子機器を検索する

{"domain": "1", "rootCategoryNames": ["Electronics"], "monthlySoldGte": 1000}

2. 適正な評価を得ている、指定価格帯の商品を検索する

{"domain": "1", "currentBuyBoxShippingGte": 1500, "currentBuyBoxShippingLte": 5000, "currentRatingGte": 4.0, "keyword": "wireless charger"}

3. 過去6か月以内に出品され、レビュー数が少ない新商品を検索する

{"domain": "1", "availableDateGte": "2025-10-01", "currentCountReviewsLte": 50, "monthlySoldGte": 500}

4. 競合分析のためにBSR順位で絞り込む

{"domain": "1", "categoriesIncludeNames": ["Home & Kitchen"], "currentSalesLte": 5000, "sort": [{"fieldName": "monthlySold", "sortDirection": "desc"}]}

5. 売れ行きが良い、Amazon以外のFBA商品を検索する

{"domain": "1", "buyBoxIsAmazon": false, "buyBoxIsFBA": true, "monthlySoldGte": 300, "currentRatingGte": 4.0}

6. 配送しやすい、軽量で小型の商品を検索する

{"domain": "1", "packageWeightLte": 500, "packageLengthLte": 200, "packageWidthLte": 150, "packageHeightLte": 100, "monthlySoldGte": 200}

7. 日本のマーケットプレイスで履歴データを含めて検索する

{"domain": "5", "keyword": "USB charger", "history": 1, "monthlySoldGte": 100}

8. 危険物を除外して、特定ブランドの商品を検索する

{"domain": "1", "brand": ["Anker", "UGREEN"], "isHazMat": false, "sort": [{"fieldName": "monthlySold", "sortDirection": "desc"}]}

表示ルール

1. データをわかりやすく提示する：ASIN、タイトル、価格、BSR、月間販売数、評価、レビュー数、ブランドなどの主要項目を含む、整然とした表で検索結果を表示します
2. 価格換算：最小通貨単位の価格を標準形式に換算します（例：2599 → $25.99）
3. BSRの説明：BSRデータを表示する場合は、値が小さいほど販売ランキングが高いことをユーザーに伝えます
4. 月間販売数の履歴：履歴データが含まれている場合は、12か月間の販売数の推移をわかりやすく提示します
5. ページネーションに関する案内：結果の総数をユーザーに伝え、必要に応じて追加のページを取得するよう案内します
6. 画像リンク：画像URLが利用できる場合は案内します。ただし、ユーザーから求められない限り、インラインでの表示は試みません
7. エラー処理：クエリに失敗した場合は理由を説明し、フィルター条件の調整を提案します

重要な制限事項

• 結果数の上限：1ページあたり最大100件、最小50件
• 並べ替えの上限：1クエリあたり最大3つの並べ替えルール
• カテゴリーの上限：フィルターあたり最大50個のカテゴリーIDまたはカテゴリー名
• キーワードの上限：keyword パラメーターあたり最大50個のキーワード
• 履歴データのコスト：history=1 を設定すると、レスポンスサイズとトークンコストが大幅に増加します
• 価格の単位：すべての価格は最小通貨単位（セント、ペンスなど）です

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

適用対象 -- 複数条件によるAmazon商品の検索と絞り込み：

ユーザーの発言	シナリオ
"月間販売数がXを超える商品を探して"	販売数量による絞り込み
"XXカテゴリーの商品を検索して"	カテゴリー別の商品発見
"BSRがX未満の商品"	販売ランキングによる絞り込み
"過去Nか月以内に出品された新商品"	新商品の発見
"価格が$Xから$Yの範囲の商品"	価格帯による絞り込み
"評価の高いFBA商品"	フルフィルメントと評価による絞り込み
"重量がXグラム未満の軽量商品"	パッケージ寸法による絞り込み
"XXブランドの商品"	ブランド別検索
"XXの過去の販売データを見せて"	過去の販売データ分析
"高度な商品選定"、「商品スクリーニング」	複数条件による商品リサーチ
"ニッチ商品の探索"、「競争の少ない商品を探して」	競合ギャップ分析
"BSRの推移"、「販売ランキングの履歴」	過去のランキングによる絞り込み

適用対象外 -- 商品検索以外の機能が必要な場合：

• Amazonの検索結果ページをリアルタイムでシミュレーションする（Amazon Searchを使用）
• 過去の検索語の検索ボリュームやランキングの推移を確認する（ABAデータを使用）
• 商品レビューの内容や感情分析
• 広告キャンペーンの管理や入札額の最適化
• リスティングの最適化やコピーライティングの提案
• 在庫やサプライチェーンのデータ

適用範囲の判断：「商品リサーチ」や「商品を探して」とユーザーが言った場合、販売指標、BSR、価格、カテゴリー、その他の構造化された条件による絞り込みを伴うなら、このスキルが適用されます。キーワードで実際のAmazon検索結果ページに表示される内容を確認したい場合は、代わりにAmazon Searchを使用してください。検索語の分析を希望する場合は、ABAデータを使用してください。

計算リソース消費ルール

動的ルールに基づいて課金されます。計算リソースの消費量 = 0.045 ×（商品検索段階で消費したKeepa token + 商品詳細取得段階で消費したKeepa token）。まず商品を検索し、その後商品詳細を取得します。最初の段階で商品が見つからなかった場合は、商品検索段階の消費分のみが課金されます。

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

フィードバック：

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

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

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

---

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