linkfox-sorftime-amazon-product-query

Sorftime 製品検索

このスキルでは、Sorftime を使って Amazon の商品を複数の観点から検索・絞り込みする方法を説明します。Amazon の販売者が商品を見つけ、競合を分析し、市場機会を調査するのに役立ちます。

基本概念

Sorftime 製品検索は、16 種類のクエリタイプによる多次元の商品検索、単一条件または複数条件の AND 結合、および 2024 年 1 月以降の月次履歴スナップショットの参照に対応しています。データには、価格、BSR ランキング、月間販売数、FBA 手数料、利益分析が含まれます。

主な特長：このツールは商品の検索と絞り込みに使用します。特定の ASIN の詳細なトレンドデータ（販売数・価格・BSR の履歴）が必要な場合は、代わりに Sorftime Product Detail スキルを使用してください。

データフィールド

レスポンスデータには、次のカテゴリが含まれます（フィールドの詳細については references/api.md を参照してください）。

• 基本情報：ASIN、タイトル、ブランド、商品ページ URL、画像（メイン画像＋一覧画像）、親 ASIN、バリエーション数、重量、サイズ
• 価格と利益：現在価格、セール価格（クーポン適用後）、取り消し線付き価格、クーポン、FBA 手数料（詳細な内訳を含む）、プラットフォーム手数料、利益額と利益率
• 販売：月間販売数、月間売上、1 日あたりの販売数、1 日あたりの売上（値が -1 の場合は推定できません）
• ランキング：BSR ランク、カテゴリー、サブカテゴリーのランキング
• 評価：評価スコア、評価数
• 商品ページ情報：出品日、オンライン日数
• 販売者：Buybox 販売者名／ID／国、FBA のステータス、販売者数
• 商品ページの特長：A+ コンテンツ、動画、ブランドストア

対応マーケットプレイス

US（米国）、GB（英国）、DE（ドイツ）、FR（フランス）、IN（インド）、CA（カナダ）、JP（日本）、ES（スペイン）、IT（イタリア）、MX（メキシコ）、AE（アラブ首長国連邦）、AU（オーストラリア）、BR（ブラジル）、SA（サウジアラビア）

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

注：Sorftime では小文字のコード（例：us、gb、de）を使用します。また、英国のコードは uk ではなく gb です。

调用方式

• API 端点：POST /sorftime/amazon/productQuery（完整参数/响应/错误码见 references/api.md）
• Python 脚本：python scripts/sorftime_product_search.py '<JSON 参数>' [--inline]
• 成本约束：本工具会消耗算力；同一会话同一参数组合默认只调用一次，脚本带 24h 本地缓存。失败/空结果不得自动换关键词、翻页或改邮编连续试探；需要继续检索时先向用户说明会产生额外消耗。

输出策略（脚本默认行为）：

• 始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-sorftime-amazon-product-query-<timestamp>.json（<cwd> 为脚本执行时的工作目录，在 Claude Code 里即当前项目目录；<session> 取自环境变量 SESSION_ID，按用户任务自动聚合；禁止写入 /tmp，当前目录不可写则报错）
• 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout
• 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 total/costToken、最大列表字段的长度 + 前 3 条样本）
• 加 --inline 强制全量打印到 stdout（同样落盘）

读数据建议：先看摘要判断是否足够；需要具体字段时优先用 jq或ConvertFrom-Json 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。

解决认证和算力问题

发生以下异常情况时，采用 references/onboarding.md 引导解决问题：

异常情况

• 未配置API Key：环境变量未配置 LINKFOX_AGENT_API_KEY，也未配置 LINKFOXAGENT_API_KEY。
• 响应401或402状态码
• 响应提示算力或余额不足：消息含"算力余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值"，或类似含义的内容。

クエリの作成方法

主なパラメーターは marketplace（必須）、queryMode、queryType、queryValue です。クエリシステムには 2 つのモードと 16 種類のフィルタータイプがあり、柔軟に組み合わせられます。

クエリ作成の原則

1. 必ずマーケットプレイスを指定します：us、de、jp など、小文字のサイトコードを使用します
2. 適切なクエリモードを選択します：単一のフィルターには queryMode=1、複数のフィルターを AND 条件で組み合わせるには queryMode=2 を使用します
3. queryType と queryValue の形式を一致させます：queryType ごとに指定の形式があります。下の表を参照してください。形式が一致しない場合、エラーが発生します
4. 価格の単位に注意します：価格フィルター（queryType=8）は smcurrency 単位（USD の場合はセント）を使用します。したがって、$19.99 は 1999 です
5. 必要に応じて範囲の片側を省略します：片方を省略すると範囲の上限または下限を指定できます。,1000 は「1000 以下」、100, は「100 以上」を意味します
6. 過去の比較には queryMonth を使用します：形式は yyyy-MM です。時間の経過による変化を確認するには、queryMonth を指定せずに 2 回目の呼び出しを行い、比較します

クエリタイプ（queryMode=1 の queryType）

queryType	名前	queryValue の形式	例
1	ASIN 類似商品	ASIN	B0CVM8TXHP
2	カテゴリー	NodeId	3743561
3	ブランド	ブランド名	Anker
4	出品者名	ストア名	AnkerDirect
5	出品者 ID	SellerId	A294P4X9EWVXLJ
6	ABA キーワード	キーワード	Power Bank
7	タイトル／属性の一致	キーワード	10,000mAh 30W
8	価格帯	min,max（セント単位）	1,1000（=$0.01~$10）
9	月間販売数の範囲	min,max	100,1000
10	季節商品	月のリスト	1,2,3（1～3月がピーク）
11	出品日の範囲	start,end（yyyy-MM-dd）	2024-06-01,2024-12-01
12	評価の範囲	min,max	3,5
13	レビュー数の範囲	min,max	10,500
14	ランクの範囲	bsr_min,bsr_max;sub_min,sub_max	500,5000;1,100
15	フルフィルメント	FBA / FBM	FBA,FBM
16	バリエーション数	min,max	1,50

重要：queryType=1（ASIN 類似商品）は、指定した ASIN 自体ではなく、それに類似した商品を検索します。単一商品の詳細を検索するには、Sorftime Product Detail スキルを使用してください。

過去のスナップショット（queryMonth）

queryMonth（形式：yyyy-MM）を設定すると、過去の月の商品データのスナップショットを検索できます。これにより、過去の価格、ランキング、販売数を現在のデータと比較できます。

• 対応範囲：2024年1月から現在まで（約2年間）
• 米国、GB、DE は「無制限」の全期間遡及モードに対応しています
• その他のサイトでは、遡及検索で上位100商品まで対応しています
• AU、BR、IN は遡及検索に対応していません

よくあるシナリオのクエリ例

1. 指定した ASIN の競合商品

queryMode: 1, queryType: 1, queryValue: B0CVM8TXHP, marketplace: us

2. カテゴリーの上位商品を閲覧する

queryMode: 1, queryType: 2, queryValue: 3743561, marketplace: us

3. ブランドの商品ポートフォリオを分析する

queryMode: 1, queryType: 3, queryValue: Anker, marketplace: us

4. ABA キーワードで検索する

queryMode: 1, queryType: 6, queryValue: Power Bank, marketplace: us

5. 季節商品を見つける（第4四半期がピーク）

queryMode: 1, queryType: 10, queryValue: 10,11,12, marketplace: us

6. 過去のデータと現在のデータを比較する

queryMonth: 2024-11, queryMode: 1, queryType: 2, queryValue: 3743561, marketplace: us
-> Compare with current data (no queryMonth) to see price/sales changes

7. 複数条件：販売数の多い新しい FBA 商品

queryMode: 2
queryValue: [{"QueryType":11,"Content":"2024-06-01,"},{"QueryType":9,"Content":"300,"},{"QueryType":15,"Content":"FBA"}]
marketplace: us

8. 低価格で販売数の多い商品を見つける

queryMode: 2
queryValue: [{"QueryType":8,"Content":",2000"},{"QueryType":9,"Content":"500,"}]
marketplace: us

9. 出品者の商品ポートフォリオを確認する

queryMode: 1, queryType: 4, queryValue: AnkerDirect, marketplace: us

表示ルール

1. データのみを提示：クエリ結果は、主観的なビジネス上の助言を加えず、わかりやすい表で表示してください
2. ランキングの補足：ランキングデータを表示する際は、数値が小さいほど順位が高いことをユーザーに伝えてください
3. ページネーションに関する注意：検索結果は1ページあたり最大100商品、最大200ページまで返されます。結果が大量の場合は、要点を示してページネーションを行うようユーザーに伝えてください
4. 販売数の推定に関する注意：販売数／売上のフィールドにある -1 は「推定不可」を意味します。-1 をそのまま表示するのではなく、その旨をユーザーに説明してください
5. エラー処理：クエリに失敗した場合は、msg フィールドに基づいて理由を説明し、クエリ条件の調整を提案してください

重要な制限事項

• ページネーション：1ページあたり最大100商品、最大200ページ
• **履歴の対応
• 非構造化データ：結果は _dataQuery_executeDynamicQuery による二次分析に対応していません
• 販売数の推定：標準外のカテゴリーの商品では、販売数のフィールドが -1 になる場合があります
• ABA キーワード検索（queryType=6）：現在は ABA キーワードのみ対応しており、任意の検索語には対応していません

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

該当するケース - Amazonでの商品検索と絞り込み：

ユーザーの発言	シナリオ
「このカテゴリーで売れている商品を探して」	カテゴリーの調査
「Ankerブランドの人気商品には何がありますか」	ブランド分析
「このASINの競合商品は何ですか」	競合商品の発見
「季節商品をいくつか探して」	季節商品の発見
「新商品のうち、月間販売数が500を超えるものはどれですか」	条件で絞り込んだ商品の発見
「昨年のダブルイレブン時点での、このカテゴリーの価格スナップショット」	過去のスナップショット比較
「この出品者はほかにどんな商品を販売していますか」	出品者の取扱商品
「利益率が30％を超えるFBA商品を絞り込んで」	利益重視の絞り込み
「月間販売数が1000以上で、評価が星4つ以上の商品」	複数条件での絞り込み
「タイトルにwireless chargerを含む商品」	タイトルのキーワード検索

該当しないケース - 商品検索の範囲を超えるリクエスト：

• 特定のASINの詳細なトレンド／履歴データ（Sorftime Product Detailを使用）
• ABA検索語のランキングデータ（ABA Data Explorerを使用）
• 広告／PPC戦略
• 商品レビューの内容分析
• 特許または商標の確認

適用範囲の判断：「競合分析」や「市場調査」を求められた場合、カテゴリー、ブランド、価格帯など複数の切り口から商品を発見して比較する必要があれば、このスキルが該当します。特定のASINの過去のトレンド曲線が必要な場合は、Prt Detailスキルを使用してください。キーワードの検索ボリュームデータが必要な場合は、ABA Data Explorerを使用してください。

計算リソースの消費ルール

動的ルールに基づいて課金されます：計算リソースの消費量 = Sorftime内部クエリ回数 × 6。Sorftime内部クエリ回数：必要なクエリ回数は検索条件によって異なり、その回数はSorftimeが決定します。

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

フィードバック：

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

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

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

---

高品質で専門的な越境ECスキルをさらにご覧になるには、LinkFox Skillsにアクセスしてください。