linkfox-amazon-search

Amazon 商品検索

このスキルでは、Amazonストアフロントの検索をシミュレートする方法を説明します。Amazonの出品者が、商品のランキング、価格、評価などを含むリアルタイムの検索結果データを取得できます。

基本概念

このツールは、Amazonのストアフロントでユーザーが検索する操作をシミュレートします。商品の掲載位置、価格、評価、レビュー数、ブランド、配送情報、スポンサー表示などを含む、検索結果ページ（SERP）のライブデータを返します。これはAmazonフロントエンドから直接取得したリアルタイムデータであり、過去の分析データではありません。

ABAデータとの主な違い：ABAデータは、集計された過去の検索語句分析データです。このツールは、現在Amazonでキーワードを検索したときにユーザーが実際に目にする商品リストを返します。

キーワードの言語：キーワードは対象マーケットプレイスの言語で指定してください。たとえば、amazon.comでは英語、amazon.deではドイツ語、amazon.co.jpでは日本語のキーワードを使用します。

卖家精灵销量数据开关（重要）

includeSellerSpriteData は、卖家精灵を使用して競合商品データを補完するかどうかを制御します。呼び出しのたびに明示的に指定する必要があります。

• デフォルトでは false を指定します。Amazonフロントエンドの検索データのみを返し、卖家精灵は呼び出しません。
• ユーザーが商品の月間販売数、月間売上高、ブランド、出品者数、フルフィルメント方式、またはその他の卖家精灵による競合商品データを必要とする場合は、includeSellerSpriteData を有効にできることをユーザーに説明し、呼び出し時に true を指定してください。
• true を指定すると、追加の動的ポイントを消費します。有効にする前に、費用は補完に成功したバッチ数に応じて変動することを明確に伝えてください。
• ユーザーが「競合商品を探して」と言っただけで、自動的に有効にしてはいけません。上記の卖家精灵による補完データが必要な場合、またはユーザーが明示的に有効化を求めた場合に限り、true を指定してください。

販売データが必要な場合の呼び出し例：

{"keyword": "neck massager", "amazonDomain": "amazon.com", "includeSellerSpriteData": true}

パラメーター

パラメーター	型	必須	説明	デフォルト
keyword	string	いいえ	検索キーワード（対象マーケットプレイスの言語に翻訳してください）	-
amazonDomain	string	いいえ	Amazonマーケットプレイスのドメイン	amazon.com
node	string	いいえ	カテゴリーを指定した検索に使用するAmazonカテゴリーのノードID	-
language	string	いいえ	言語ロケールコード（例：en_US、de_DE、ja_JP）	-
sort	string	いいえ	検索結果の並べ替え順	relevanceblender
page	integer	いいえ	ページ番号（1から開始、1ページあたり約20件）	1
deliveryZip	string	いいえ	配送先をシミュレートするための郵便番号	-
device	string	いいえ	デバイスの種類：desktop、mobile、またはtablet	desktop
includeSellerSpriteData	boolean	はい	高度なパラメーター：呼び出しのたびに明示的に指定する必要があります。true の場合、卖家精灵を呼び出して販売数、売上高、ブランド、フルフィルメントなどの競合商品データを補完し、追加の動的計算リソースを消費します。補完が不要な場合は false を指定してください	false（サーバー側のフォールバックのみ）

対応マーケットプレイス

ドメイン	国
amazon.com	アメリカ合衆国
amazon.co.uk	イギリス
amazon.de	ドイツ
amazon.fr	フランス
amazon.it	イタリア
amazon.es	スペイン
amazon.co.jp	日本
amazon.ca	カナダ
amazon.com.au	オーストラリア
amazon.com.br	ブラジル
amazon.in	インド
amazon.nl	オランダ
amazon.se	スウェーデン
amazon.pl	ポーランド
amazon.sg	シンガポール
amazon.sa	サウジアラビア
amazon.ae	アラブ首長国連邦
amazon.com.mx	メキシコ
amazon.com.tr	トルコ
amazon.com.be	ベルギー
amazon.cn	中国
amazon.eg	エジプト

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

並べ替えオプション

値	説明
relevanceblender	おすすめ／関連度（デフォルト）
price-asc-rank	価格：安い順
price-desc-rank	価格：高い順
review-rank	平均カスタマーレビュー
date-desc-rank	新着商品
exact-aware-popularity-rank	売れ筋商品

呼び出し方法

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

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

• 常に完全なレスポンスを <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-amazon-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. マーケットプレイスの決定：ユーザーが指定した対象国を、適切な amazonDomain の値に対応付けます
2. キーワードの設定：検索語を対象マーケットプレイスの言語に翻訳します
3. 並べ替え順の選択：価格、レビュー、新着順での並べ替えをユーザーが希望する場合は、sort パラメーターを設定します
4. ページネーション：必要に応じて page パラメーターを使い、追加の検索結果ページを取得します
5. カテゴリの範囲：特定のカテゴリ内での検索をユーザーが希望する場合は、node パラメーターを指定します
6. 配送のシミュレーション：deliveryZip を使うと、地域ごとの在庫状況と配送情報を確認できます
7. SellerSprite データの補完：呼び出すたびに includeSellerSpriteData を明示的に指定する必要があります。ユーザーが SellerSprite データ、月間販売数、売上高、ブランド、フルフィルメントなどの補完フィールドを明確に求めた場合に限り true を指定し、動的な計算リソースの消費が増えることを事前に伝えてください。それ以外の場合は必ず false を指定します

使用例

1. 米国のマーケットプレイスで基本的なキーワード検索

{"keyword": "wireless earbuds", "amazonDomain": "amazon.com", "includeSellerSpriteData": false}

2. ドイツ語のキーワードでドイツのマーケットプレイスを検索

{"keyword": "kabellose Kopfhoerer", "amazonDomain": "amazon.de", "language": "de_DE", "includeSellerSpriteData": false}

3. 価格の安い順に並べ替えて検索

{"keyword": "phone case", "amazonDomain": "amazon.com", "sort": "price-asc-rank", "includeSellerSpriteData": false}

4. カテゴリ内でベストセラーを検索

{"keyword": "yoga mat", "amazonDomain": "amazon.com", "sort": "exact-aware-popularity-rank", "includeSellerSpriteData": false}

5. 日本のマーケットプレイスで新着商品を検索

{"keyword": "USB充電器", "amazonDomain": "amazon.co.jp", "language": "ja_JP", "sort": "date-desc-rank", "includeSellerSpriteData": false}

6. 複数ページを検索して、より詳細な結果を分析

{"keyword": "laptop stand", "amazonDomain": "amazon.com", "page": 2, "includeSellerSpriteData": false}

7. モバイル端末での検索をシミュレーション

{"keyword": "running shoes", "amazonDomain": "amazon.com", "device": "mobile", "includeSellerSpriteData": false}

8. 配送先郵便番号を指定したカテゴリ内検索

{"keyword": "office chair", "amazonDomain": "amazon.com", "deliveryZip": "10001", "includeSellerSpriteData": false}

9. 高度なクエリ：SellerSprite データの補完を有効にする

{"keyword": "neck massager", "amazonDomain": "amazon.com", "includeSellerSpriteData": true}

表示ルール

1. データを明確に提示：検索結果は、順位、ASIN、タイトル、価格、評価、レビュー数、ブランドなどの主要フィールドを含む、構成の整った表で表示します
2. スポンサー商品を強調：スポンサー広告とオーガニックリスティングのどちらに該当するかを明確に示します
3. 価格の形式：マーケットプレイスに合った通貨記号を付けて価格を表示します
4. 順位の説明：順位は検索結果ページ上の実際の順位を反映していることをユーザーに伝えます
5. ページネーションに関する案内：複数ページにわたる検索結果の場合は、見つかった結果の合計数を伝え、必要に応じて追加ページを取得するよう提案します
6. エラー処理：クエリが失敗した場合は、エラーレスポンスに基づいて理由を説明し、パラメーターの調整を提案します
7. 画像リンク：画像 URL がある場合はその旨を伝えますが、ユーザーから依頼がない限り、インラインでの表示は試みないでください

重要な制限事項

• リアルタイムのみ：このツールが返すのはリアルタイムの検索結果であり、過去のデータではありません。過去の検索語分析には、代わりに ABA データを使用してください
• 呼び出し頻度への配慮：各呼び出しは実際の検索リクエストをシミュレーションします。短時間に過剰な回数を呼び出さないでください
• 1ページあたり約20件：各ページには約20件の商品リスティングが返されます
• キーワードの言語が重要：検索結果の品質は、対象マーケットプレイスに適した言語を使うかどうかに左右されます

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

適用対象 -- Amazon のリアルタイム検索結果に関する問い合わせ：

ユーザーの発言	シナリオ
「Amazon で XX を検索して」	基本的な商品検索
「キーワード XX ではどの商品が表示されますか」	キーワードの検索結果ページ（SERP）分析
「キーワード XX で自分の ASIN は何位ですか」	表示位置／ランキングの確認
「XX の上位検索結果を表示して」	競合状況の把握
「XX の価格帯はいくらですか」	価格比較
「キーワード XX のスポンサープロダクトはありますか」	スポンサー広告の分析
「キーワード XX の新商品はありますか」	新着商品のモニタリング
「Amazon ドイツ／日本／英国で XX を検索して」	複数マーケットプレイスの検索
「XX のベストセラーは何ですか」	ベストセラー商品の発見
「モバイルとデスクトップの検索結果を比較して」	デバイス別の検索結果ページ（SERP）

適用対象外 -- リアルタイム検索結果の範囲を超える要件：

• 過去の検索語句の検索ボリュームやランキングの推移（ABA データを使用）
• 広告キャンペーンの管理や入札の最適化
• 商品レビューの分析や感情分析
• 売上推定や収益分析
• 商品リスティングの最適化やコピーライティングの提案
• 在庫やサプライチェーンのデータ

適用範囲の判断：ユーザーが「商品リサーチ」や「競合分析」と言っても、要するに特定のキーワードで現在 Amazon の検索結果に何が表示されているか（商品の掲載位置、価格、評価）を確認したいのであれば、このスキルが適用されます。過去の推移、検索ボリュームデータ、集計分析を求めている場合は、ABA データのほうが適切です。

算力消耗规则

算力动态计算：

Amazon 搜索基础 costToken（20000）
+ 实际成功执行的卖家精灵补全批次 costToken 之和

• Skill の呼び出しでは includeSellerSpriteData を明示的に指定する必要があります。卖家精灵による補完が不要な場合は false を渡すと、Amazon 検索の基本消費のみが発生します。サーバーでは旧来の呼び出しとの互換性のため、引き続きデフォルト値 false が設定されています。
• 有効にすると、検索結果に対して卖家精灵がバッチ単位で呼び出され、成功したバッチから返される costToken がバッチごとに加算されます。最終的な消費量はレスポンスのトップレベルにある costToken を基準とします。
• 失敗し、costToken が返されなかった卖家精灵のバッチでは、算力は追加されません。
• 複数ページの検索では、各ページが独立したリクエストとなり、算力はそれぞれ個別に計算されます。

ユーザーは算力の消費に応じて料金を支払います。十分に評価してください。このスキルを高頻度で呼び出す必要がある場合や、ユーザーの算力消費量に対する想定が不十分な場合は、必ずユーザーに注意を促し、続行するかどうかはユーザーに判断してもらってください。

フィードバック：

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

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

references/api.md の指定に従って Feedback API を呼び出してください。ユーザーの操作を中断しないでください。

---

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