linkfox-sorftime-product-search

Sorftime 製品検索

このスキルでは、Sorftime を使って Amazon の製品を複数の軸で検索・絞り込みする方法を説明します。Amazon セラーが製品を見つけ、競合を分析し、市場機会を探るのに役立ちます。

基本概念

Sorftime 製品検索では、16 種類の検索条件に対応した多次元の製品取得、単一条件または複数条件を AND で組み合わせた検索、2024 年 1 月からの過去の月次スナップショットの参照が可能です。データには、価格、BSR ランキング、月間販売数、FBA 手数料、利益分析が含まれます。

主な違い：このツールは、製品を横断して検索・絞り込みするためのものです。特定の ASIN の詳細なトレンドデータ（販売数／価格／BSR の履歴）が必要な場合は、Sorftime Product Detail スキルを使用してください。

データフィールド

フィールド	API 名	説明	例
ASIN	asin	Amazon 標準識別番号	B0CVM8TXHP
製品タイトル	title	商品リスティングのタイトル	Anker Portable Charger...
ブランド	brand	ブランド名	Anker
現在価格	price	クーポン適用前の価格、現地通貨（例：USD）	29.99
セール価格	salesPrice	クーポン適用後の実際の販売価格、現地通貨	25.99
取り消し線価格	oldPrice	元の表示価格、現地通貨	39.99
クーポン	coupon	>0 = 割引額（500=$5）；<0 = 割合（-10=10%オフ）	-15
BSR ランク	salesRank	メインカテゴリーでのベストセラーランキング	1523
月間販売数	monthlySalesUnits	30 日間の販売数量（リスティング単位）；-1 = 推定不可	4500
月間売上	monthlySalesRevenue	推定月間売上、現地通貨；-1 = 該当なし	116955.00
1 日あたりの販売数	listingSalesVolumeOfDaily	1 日あたりの販売数量；-1 = 推定不可	150
1 日あたりの売上	listingSalesOfDaily	1 日あたりの売上、現地通貨；-1 = 該当なし	3898.50
評価	rating	現在の評価（0.0～5.0）	4.70
評価数	ratings	評価の件数	12580
リスティング日	availableDate	リスティング日（yyyy-MM-dd）	2022-03-15
掲載日数	onlineDays	リスティング開始からの日数	850
FBA 手数料	fbaFees	FBA フルフィルメント手数料、現地通貨	5.40
プラットフォーム手数料	platformFee	プラットフォームの販売手数料、現地通貨	3.90
利益	profitAmount	販売価格 - FBA 手数料 - 販売手数料、現地通貨	16.69
利益率	profitRate	利益率。例：25.83 = 25.83%	25.83
FBA ステータス	isFBA	Buybox の販売者が FBA を利用しているかどうか	true
Buybox 販売者	buyboxSeller	Buybox を獲得した販売者名	AnkerDirect
販売者の国	buyboxSellerAddress	販売者の国コード（CN、US）；Amazon が運営する場合は null	CN
販売者 ID	buyBoxSellerId	Buybox 販売者 ID	A294P4X9EWVXLJ
カテゴリー	category	メインカテゴリー [name, NodeId]	["Cell Phones", "2811119011"]
サブカテゴリー	bsrCategory	サブカテゴリーのランキング一覧	[{nodeId, name, rank, date}]
バリエーション	variationNum	バリエーションの数	5
親 ASIN	parentAsin	バリエーションがある場合の親 ASIN。ない場合は null	B0088PUEPK
重量	weight	重量（グラム）	350
サイズ	size	寸法（cm）[最長、2 番目に長い、最短]	[18.5, 8.2, 3.1]
メイン画像	imageUrl	メインの商品画像 URL	https://...
リスティング URL	asinUrl	Amazon 商品ページの URL	https://www.amazon.com/dp/...

対応マーケットプレイス

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

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

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

API の使用方法

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

クエリの作成方法

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

クエリ作成の原則

1. 必ずマーケットプレイスを指定する：us、de、jpなど、小文字のサイトコードを使用します
2. 適切なクエリモードを選ぶ：単一のフィルターにはqueryMode=1を使用します。複数のフィルターをAND条件で組み合わせるにはqueryMode=2を使用します
3. queryTypeとqueryValueの形式を一致させる：各queryTypeには特定の形式が必要です。下表を参照してください。形式が一致しない場合、エラーになります
4. 価格の単位に注意する：価格フィルター（queryType=8）では通貨の最小単位（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自体ではなく、そのASINに類似する商品を検索します。単一商品の詳細を照会するには、Sorftime Product Detailスキルを使用してください。

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

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

• 対応範囲：2024年1月から現在まで（約2年間）
• US、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ページです
• 過去データの参照期間：2024年1月以降のみです。AU、BR、INはサポートされていません
• 非構造化データ：結果は_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の過去のトレンド曲線が必要な場合は、Product Detailスキルを使用してください。キーワードの検索ボリュームデータが必要な場合は、ABA Data Explorerを使用してください。

フィードバック：

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

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

references/api.mdの指定に従ってフィードバックAPIを呼び出してください。ユーザーの作業を中断しないでください。

大きなレスポンスの処理

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

python scripts/response_io.py run --script scripts/sorftime_product_search.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にアクセスしてください。