linkfox-ebay-search

eBay 商品検索

このスキルでは、eBay の出品商品データを検索して取得する方法を説明します。EC の出品者や購入者が商品を探し、価格を比較し、eBay の各国・地域のマーケットプレイス全体で市場動向を分析するのに役立ちます。

主な概念

eBay 商品検索では、eBay のフロントエンドに表示される出品商品データにアクセスできます。キーワード検索に加え、価格帯、商品の状態、購入形式、並べ替え順、出品者の所在地など、豊富なフィルターオプションを利用できます。検索結果には、タイトル、価格、配送情報、出品者の評価、販売数量、商品の状態などの商品詳細が含まれます。

マーケットプレイスの仕組み：ebayDomain パラメーターで、検索対象となる地域別 eBay サイトを指定します。デフォルトは ebay.com（米国）です。ユーザーが国や地域を指定した場合は、対応する eBay ドメインに割り当ててください（例：英国 → ebay.co.uk、ドイツ → ebay.de）。

購入形式：eBay では複数の購入形式に対応しています。入札形式の出品には Auction、固定価格の出品には BIN（今すぐ購入）、価格交渉可能な出品には BO（ベストオファー）を使用します。

パラメーターガイド

パラメーター	型	必須	説明	デフォルト
keyword	string	いいえ	検索キーワード。最大 1024 文字	-
ebayDomain	string	いいえ	eBay マーケットプレイスのドメイン	ebay.com
page	integer	いいえ	ページネーション用のページ番号	1
pageSize	integer	いいえ	1 ページあたりの検索結果数：25、50、100、または 200	50
orderBy	string	いいえ	並べ替え順（下記の並べ替えオプションを参照）	12（ベストマッチ）
priceMin	number	いいえ	価格の下限フィルター	-
priceMax	number	いいえ	価格の上限フィルター	-
itemCondition	string	いいえ	商品の状態コード（複数の場合はパイプ区切り。例：1000|3000）	-
buyingFormat	string	いいえ	購入形式：Auction、BIN、または BO	-
showOnly	string	いいえ	表示フィルター（複数の場合はカンマ区切り。例：Sold,Complete）	-
location	integer	いいえ	出品者の所在地を示す国コード	-
prefLoc	string	いいえ	希望する所在地の範囲：1=国内、2=地域、3=全世界	-
zipCode	string	いいえ	地域別の配送フィルターに使用する ZIP コード／郵便番号	-
categoryId	integer	いいえ	eBay のカテゴリー ID	-
noCache	boolean	いいえ	キャッシュを迂回して最新の検索結果を取得	false

並べ替えオプション

コード	意味
12	ベストマッチ（デフォルト）
1	時間：終了が近い順
10	時間：新着順
15	価格＋送料：安い順
16	価格＋送料：高い順
2	価格：安い順
3	価格：高い順
7	距離：近い順
18	商品の状態：新品を優先
19	商品の状態：中古品を優先

商品の状態コード

コード	状態
1000	新品
1500	新品（詳細を参照）
1750	新品（不具合あり）
2000	認定整備済み
2010	非常に良い状態の整備済み品
2020	良好な状態の整備済み品
2030	まずまずの状態の整備済み品
2500	出品者による整備済み／再生品
2750	新品同様
3000	中古品／使用済み
7000	部品取り用または動作しない商品

showOnly フィルター値

値	意味
Complete	終了した出品
Sold	売却済みの出品のみ
FR	無料返品
RPA	返品を受け付ける出品
AS	正規販売店
Savings	お買い得品と割引
SaleItems	セール商品
Lots	ロット
FS	送料無料
LPickup	現地受け取り

対応している eBay ドメイン

ドメイン	国
ebay.com	米国（デフォルト）
ebay.co.uk	英国
ebay.de	ドイツ
ebay.fr	フランス
ebay.it	イタリア
ebay.es	スペイン
ebay.ca	カナダ
ebay.com.au	オーストラリア
ebay.nl	オランダ
ebay.at	オーストリア
ebay.ch	スイス
ebay.pl	ポーランド
ebay.ie	アイルランド
ebay.com.hk	香港
ebay.com.my	マレーシア
ebay.com.sg	シンガポール

呼び出し方法

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

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

• 常に完全なレスポンスを <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-ebay-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. 基本的なキーワード検索 米国の eBay マーケットプレイスで「wireless earbuds」を検索します：

{"keyword": "wireless earbuds"}

2. 販売済み商品の価格調査 市場価格の目安を把握するため、「iPhone 15 Pro」の販売済み商品を検索します：

{"keyword": "iPhone 15 Pro", "showOnly": "Sold,Complete", "orderBy": "10"}

3. 価格帯を指定したマーケットプレイス検索 eBay UK で 500 ドルから 1000 ドルの新品ノートパソコンを検索します：

{"keyword": "laptop", "ebayDomain": "ebay.co.uk", "priceMin": 500, "priceMax": 1000, "itemCondition": "1000"}

4. 終了間近のオークション商品 終了時刻が最も早い「vintage watch」の出品中オークションを検索します：

{"keyword": "vintage watch", "buyingFormat": "Auction", "orderBy": "1"}

5. 最も安い新品商品の検索 送料無料の最安値の新品「USB-C cable」を検索します：

{"keyword": "USB-C cable", "itemCondition": "1000", "orderBy": "15", "showOnly": "FS"}

6. ページ分割された検索結果 「running shoes」の検索結果を、1 ページあたり 100 件で 3 ページ目まで取得します：

{"keyword": "running shoes", "page": 3, "pageSize": 100}

7. カテゴリーを指定した検索 特定の eBay カテゴリー内を検索します：

{"keyword": "mechanical keyboard", "categoryId": 33963}

8. 場所を指定した検索 ドイツの eBay サイトで、所在地がドイツの商品を検索します：

{"keyword": "Kopfhoerer", "ebayDomain": "ebay.de", "location": 77}

表示ルール

1. データを明確に表示する：検索結果を、タイトル、価格、状態、出品者情報、送料などの主要項目を含む、適切に整形された表で表示します
2. 価格の書式：価格は必ず通貨記号を付けて表示します。価格帯（minPrice から maxPrice）を表示する場合は、範囲として書式を整えます
3. 販売済み／取引完了データ：販売済み商品を表示する場合は、価格調査に役立つよう、販売価格と数量を目立たせます
4. 出品者の信頼性を示す指標：利用可能な場合は、出品者の信頼性をユーザーが評価できるよう、フィードバック率とレビュー数を表示します
5. ページネーションの案内：合計件数が現在のページの件数を超える場合は、合計件数を伝え、さらに表示するためにページネーションを利用するよう案内します
6. スポンサー付き商品：ユーザーが通常の検索結果と宣伝対象の結果を区別できるよう、スポンサー付き出品を明示します
7. エラー処理：クエリが失敗した場合は、問題を説明し、検索パラメーターの調整を提案します
8. リンクの表示：eBay で詳細を確認できるよう、商品リンクを提示します

重要な制限事項

• 過去のデータはありません：このツールが返すのは現在の出品情報のみで、過去の価格推移ではありません
• 結果件数の上限：1 ページあたり最大 200 件
• レート制限：リクエストが過剰な場合は制限されることがあります。noCache: true は必要な場合に限って使用してください
• 通貨：価格は検索対象の eBay ドメインの現地通貨で返されます

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

該当する場合 -- eBay の商品検索と出品データ：

ユーザーの発言	シナリオ
"Search eBay for XX"	基本的な商品検索
"How much does XX sell for on eBay"	販売済み出品の価格調査
"Find cheapest XX on eBay"	価格比較／最安値
"eBay auctions for XX"	オークション出品の検索
"What's selling on eBay UK/Germany"	地域別マーケットプレイスの閲覧
"New XX under $50 on eBay"	コンディションと価格で絞り込んだ検索
"eBay sold prices for XX"	終了済み／販売済み出品の分析
"Find refurbished XX on eBay"	コンディションを指定した検索

該当しない場合 -- eBay の商品出品情報以外が必要なもの：

• eBay セラーアカウントの管理またはストア分析
• eBay の出品作成または編集
• eBay の注文追跡または購入履歴
• プラットフォーム横断の価格比較（eBay と Amazon など）
• eBay 広告またはプロモーション出品の管理

算力消耗规则

15 算力を消耗します。

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

フィードバック：

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

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

references/api.md に記載されている方法で Feedback API を呼び出してください。ユーザーの作業を中断しないでください。

---

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