linkfox-sellersprite-product-search

SellerSprite 商品検索

このスキルでは、SellerSprite の商品データベースを通じて Amazon の商品データを検索、絞り込み、分析する方法を説明します。Amazon セラーがデータに基づいて商品選定を判断できるよう支援します。

主な概念

SellerSprite 商品検索では、豊富な絞り込み項目を備えた Amazon 商品データベースを利用できます。リアルタイムデータ（直近 30 日間）に加え、前年同月比や前月比の比較に使える月次の過去スナップショットにも対応しています。サポートされる marketplace コードは、US、UK、DE、FR、JP、CA、IT、ES、MX、IN のみです（ゲートウェイのスキーマと同じです）。

BSR（ベストセラーランキング）：BSR の値が小さいほど、そのカテゴリーでの販売実績が優れていることを示します。BSR が 1 の商品は、そのカテゴリーで最も売れている商品です。ユーザーが「BSR が改善した」と言う場合は数値が下がったことを意味し、「BSR が下落した」と言う場合は数値が上がったことを意味します。

データスナップショット：dataSnapshotMonth パラメーターで、検索する期間を指定します。リアルタイムの直近 30 日間のデータには nearly（デフォルト）を、月次の過去スナップショットを検索するには yyyyMM 形式の文字列（例：202412）を使用します。季節分析や前年同月比の比較に便利です。

キーワードの一致タイプ：キーワードで検索する場合、次の 3 種類の一致方式を使用できます。

• フレーズ一致（デフォルト）：商品タイトルにキーワードのフレーズが含まれている必要があります
• あいまい一致：関連語を含む、より広範な一致です
• 完全一致：文字列が厳密に一致するものを検索します

パラメーターガイド

検索と絞り込み

パラメーター	型	説明	デフォルト
keyword	string	検索キーワード。対象マーケットプレイスの言語に翻訳してください（例：US では英語、DE ではドイツ語）	-
matchType	integer	1 = フレーズ一致、2 = あいまい一致、3 = 完全一致	1
excludeKeywords	string	結果から除外するキーワード	-
marketplace	string	マーケットプレイスコード（許可されている値のみ）：US、UK、DE、FR、JP、CA、IT、ES、MX、IN	US
nodeLabel	string	Amazon のカテゴリー名	-
nodeIdPath	string	Amazon のカテゴリーのノード ID	-
filterSubNode	boolean	サブカテゴリーのノードで絞り込むかどうか（nodeLabel または nodeIdPath が設定されている場合のみ有効）	-
dataSnapshotMonth	string	yyyyMM 形式のデータスナップショットの月、またはリアルタイムの直近 30 日間を示す nearly	nearly

価格と財務情報

パラメーター	型	説明
minPrice / maxPrice	number	価格帯の絞り込み
minProfit / maxProfit	number	粗利益率の範囲（1～100、単位：%）
minRevenue / maxRevenue	number	月間売上の範囲
minFba / maxFba	number	FBA 手数料の範囲

販売数とランキング

パラメーター	型	説明
minUnits / maxUnits	integer	月間販売数の範囲
minAmzUnit / maxAmzUnit	integer	子 ASIN の直近 30 日間の販売数の範囲（dataSnapshotMonth: "nearly" など、直近 30 日間形式のデータを検索する場合 のみ）
minUnitsGrowthRate / maxUnitsGrowthRate	number	月間販売成長率（%）
minBsr / maxBsr	integer	メインカテゴリーの BSR ランクの範囲
minBsrGrowthRate / maxBsrGrowthRate	number	BSR 成長率（%）
minBsrGrowthCount / maxBsrGrowthCount	integer	BSR 成長件数
minSubNodeBsrRank / maxSubNodeBsrRank	integer	サブカテゴリーの BSR ランク（filterSubNode = true が必要）

レビューと評価

パラメーター	型	説明
minRating / maxRating	number	評価スコアの範囲（0～5）。3.8～4.3 は商品改善の機会を示します
minRatings / maxRatings	integer	評価数の範囲（0～10000）
minRatingsGrowthCount / maxRatingsGrowthCount	integer	月間の新規評価数
minListingQualityScore / maxListingQualityScore	number	出品品質スコアの範囲

商品属性

参数	类型	说明
minVariations / maxVariations	整数	变体数范围
minWeights / maxWeights	数値	重量范围
weightUnit	文字列	重量単位：g、kg、oz、lb（重量フィルターを使用する場合は必須）
dimensionType	文字列	パッケージの寸法タイプ（マーケットプレイス固有のコード）
minSellers / maxSellers	整数	販売者数の範囲

バッジとフルフィルメント

パラメーター	タイプ	説明
badgeBestSeller	文字列	Best Seller バッジ：Y / N / 空欄（すべて）
badgeAmazonsChoice	文字列	Amazon's Choice バッジ：Y / N / 空欄（すべて）
badgeNewRelease	文字列	New Release バッジ：Y / N / 空欄（すべて）
fulfillment	文字列	フルフィルメントタイプ：AMZ、FBA、FBM（複数の場合はカンマ区切り）
showVariation	文字列	バリエーションを表示：Y / N（デフォルトは N）

販売者とブランド

パラメーター	タイプ	説明
sellerNation	文字列	販売者の国コード（例：US、CN、HK）。複数の場合はカンマ区切り
includeSellers / excludeSellers	文字列	特定の販売者を含める／除外する
includeBrands / excludeBrands	文字列	特定のブランドを含める／除外する

出品とページネーション

パラメーター	タイプ	説明	デフォルト
hideUnlistedProduct	ブール値	出品が終了した商品を非表示にする	true
listedWithinLastMonths	整数	過去 N か月以内に出品（1、3、6、12、または24）	-
page	整数	ページ番号（1から開始）。ページネーションでアクセスできるのは最初の2,000件のみです	1
size	整数	1ページあたりの結果数（10～100）。page * size は2,000以下である必要があります	20

並べ替え

2つのフィールドを持つ order オブジェクトを使用します。

フィールド	タイプ	説明
field	文字列	並べ替えフィールド：total_units、total_amount、bsr_rank、price、rating、reviews、profit、reviews_rate、available_date、questions、total_units_growth、total_amount_growth、reviews_increasement、bsr_rank_cv、bsr_rank_cr、amz_unit。業務上の並べ替えキーを意図的に省略する場合は "" を使用します（ゲートウェイのスキーマに準拠）
desc	文字列	降順の場合は "true"、昇順の場合は "false"

デフォルトの並べ替え：total_units の降順。

オプションのゲートウェイ／セッションフィールド

ホスティング環境から提供されている場合は、chatId、uid、requestId、teamId を文字列として渡せます（references/api.md を参照）。単発のスクリプト呼び出しでは不要です。

呼び出し方法

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

出力ポリシー（スクリプトのデフォルト動作）：

• 常に完全なレスポンスを <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-sellersprite-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. ニッチ市場で売上の高い商品を検索 米国マーケットプレイスでキーワード「ヨガマット」の商品を検索し、月間販売数が500個を超えるものを月間販売数の降順で並べ替えます。

{
  "keyword": "yoga mat",
  "marketplace": "US",
  "minUnits": 500,
  "order": {"field": "total_units", "desc": "true"}
}

2. 競争の少ない新たな商品機会を発見 米国で最近出品された商品（過去6か月以内）のうち、評価数が50件未満で月間売上高が$5,000を超えるものを検索します。

{
  "keyword": "desk organizer",
  "marketplace": "US",
  "listedWithinLastMonths": 6,
  "maxRatings": 50,
  "minRevenue": 5000,
  "order": {"field": "total_units", "desc": "true"}
}

3. 商品改善の機会を発掘 評価が3.8〜4.3（改善に適した範囲）で、月間販売数が300を超える特定カテゴリーの商品を検索します。

{
  "keyword": "phone case",
  "marketplace": "US",
  "minRating": 3.8,
  "maxRating": 4.3,
  "minUnits": 300,
  "order": {"field": "total_units", "desc": "true"}
}

4. 利益率の高い商品の選定 粗利益率が40%を超え、価格が$15〜$50で、月間販売数が100以上の商品を検索します。

{
  "marketplace": "US",
  "minProfit": 40,
  "minPrice": 15,
  "maxPrice": 50,
  "minUnits": 100,
  "order": {"field": "profit", "desc": "true"}
}

5. 季節商品の前年比較 昨年12月のスナップショットデータを取得し、現在のデータと比較して季節商品の計画に役立てます。

{
  "keyword": "christmas lights",
  "marketplace": "US",
  "dataSnapshotMonth": "202412",
  "minUnits": 200,
  "order": {"field": "total_units", "desc": "true"}
}

6. 中国人セラーの競争状況 月間販売数の多いカテゴリーから、中国人セラーが出品し、FBAで配送される商品を検索します。

{
  "keyword": "bluetooth speaker",
  "marketplace": "US",
  "sellerNation": "CN",
  "fulfillment": "FBA",
  "minUnits": 200,
  "order": {"field": "total_units", "desc": "true"}
}

7. ベストセラーおよびAmazon's Choiceのバッジを獲得した商品 ベストセラーバッジを獲得し、販売実績の高い商品を検索します。

{
  "keyword": "water bottle",
  "marketplace": "US",
  "badgeBestSeller": "Y",
  "order": {"field": "total_units", "desc": "true"}
}

8. 販売成長率の高い急成長商品 月間販売成長率が50%を超える商品を検索します。

{
  "keyword": "standing desk",
  "marketplace": "US",
  "minUnitsGrowthRate": 50,
  "order": {"field": "total_units_growth", "desc": "true"}
}

表示ルール

1. データを明確に提示：クエリ結果を構造化された表で表示します。優先する主な列は、ASIN、商品名、価格、月間販売数、月間売上高、BSR順位、評価、評価数、粗利益率、配送方法です。
2. BSRの補足：BSRデータを表示する際は、数値が小さいほど順位が高いことをユーザーに伝えます。
3. 粗利益率に関する注記：粗利益率はパーセンテージです。価格からFBA手数料と推定コストを差し引いて算出した推定値であることをユーザーに伝えます。
4. ページネーションへの配慮：合計件数が返却されるページサイズを超える場合は、合計件数をユーザーに伝え、最初の2,000件以内でのみページまたはサイズを調整するよう提案します。totalが2,000を超える場合は、最初の2,000件より後のレコードは検索できないことを明確に伝え、フィルターを絞り込むよう提案します。
5. スナップショットのラベル付け：過去のスナップショットデータを表示する場合は、リアルタイムデータと混同しないよう、データの期間を明確に示します（例：「2024年12月のスナップショットデータ」）。
6. エラー処理：クエリが失敗した場合は、messageフィールドに基づいて理由を説明し、検索条件の調整を提案します。
7. 重量単位の確認：ユーザーが単位を指定せずに重量フィルターを指定した場合は、実行前に重量単位（g、kg、oz、lb）を確認します。
8. キーワードの翻訳：ユーザーがターゲットのマーケットプレイスと異なる言語でキーワードを指定した場合は、適切な言語に翻訳し、その翻訳を明記します。

重要な制限事項

• 結果数の上限：各ページで返されるレコードは10〜100件です。ページネーションで検索できるのは、ソートされた結果セットの最初の2,000件までです（page * sizeは2,000を超えてはなりません）。その範囲外のレコードを探すには、フィルターを絞り込んでください。
• 過去のスナップショット：利用できるのは過去の月次スナップショットのみです。未来の日付はサポートされていません。
• 重量単位の指定が必須：重量フィルターを使用する場合は、weightUnitも指定する必要があります。
• サブカテゴリーBSR：サブカテゴリーのBSR順位フィルターは、filterSubNodeがtrueに設定されている場合にのみ機能します。
• 出品時期に指定できる値：listedWithinLastMonthsパラメーターで指定できる値は、1、3、6、12、24のみです。
• 子ASINの過去30日間販売フィルター：minAmzUnit / maxAmzUnitは、過去30日間を対象としたクエリ（通常はdataSnapshotMonth: "nearly"）にのみ適用されます。過去のyyyyMMスナップショットには使用しないでください。

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

該当するケース — Amazon の商品レベルのデータ検索：

ユーザーの発言	シナリオ
「XX カテゴリーで売上の高い商品を探して」	ニッチ商品の検索
「競争の少ない商品を見せて」「新商品のチャンスを探して」	ブルーオーシャン商品の発見
「利益率の高い商品はどれ？」	収益性のスクリーニング
「売上が伸びている商品」「トレンドの商品」	成長トレンドの検出
「中国の販売者がよく売っている商品は？」	競合状況の分析
「最近発売されて売れている商品」	新商品の追跡
「レビュー評価は低いが売上の良い商品」	商品改善の機会
「このカテゴリーを昨年と比較して」	季節性／前年比分析
「売上が 1,000 件以上で、30 ドル未満の FBA 商品」	複数条件による商品絞り込み
「XX カテゴリーのベストセラー」	バッジに基づく商品の発見

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

• ABA の検索語／キーワード分析（代わりに ABA Data Explorer を使用してください）
• 広告／PPC キャンペーンデータ
• 商品レビュー本文の分析
• 商品リスティングのコピーライティングまたは最適化
• サプライヤーの調達または製造コスト
• 物流と在庫計画

適用範囲の判断：ユーザーが「商品リサーチ」や「市場分析」と言っていても、売上、価格、BSR、評価、その他の商品属性による Amazon 商品の絞り込みが中心であれば、このスキルが適しています。キーワードの検索ボリューム、検索語のランキング、クリック率やコンバージョン率のシェアについて尋ねている場合は、ABA Data Explorer スキルのほうが適しています。

計算ポイントの消費ルール

計算ポイントを 15 消費します。

ユーザーは計算ポイントの消費に対して料金を支払います。十分に検討してください。このスキルを高頻度で呼び出す必要がある場合や、ユーザーが計算ポイントの消費量を十分に把握していない場合は、必ずユーザーに注意を促し、続行するかどうかをユーザーに判断してもらってください。

フィードバック：

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

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

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

---

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