linkfox-seerfar-ozon-category-search

Seerfar Ozon カテゴリー検索

このスキルは、Seerfar の分析データベースから、特定の Ozon カテゴリーの商品一覧を取得します。categoryId を指定すると、カテゴリー単位の集計値（総販売数、総売上、平均価格、平均評価、季節性）に加えて、各商品の販売数、価格、評価、レビュー件数、ブランド、販売者を返します。カテゴリー選定の分析、カテゴリー内のベストセラーの特定、カテゴリーの市場規模や価格帯の分析を始める際に利用できます。

主な概念

データの単位は、1つのカテゴリーに属する商品です：categoryId を1つ指定すると、そのカテゴリーの商品一覧と実績指標に加え、カテゴリー単位の集計値が返されます。これはカテゴリー単位のビューであり、ショップやキーワード単位のビューではありません。

categoryId の取得元：categoryId は Ozon のカテゴリー識別子です。_ でつないだ階層パス（例：15621032_15621049_115951147）で、Ozon のカテゴリー文書または他の Seerfar Ozon ツールから取得できます。カテゴリー名しか分からない場合は、このスキルを呼び出す前に、上流の Seerfar Ozon ソースで categoryId に変換してください。

カテゴリー集計値と商品行：レスポンスには、カテゴリー単位の合計値（totalSales、totalRevenue、avgPrice、rating、seasonalityAmplitude、seasonalityCoef、startDate／endDate）と、ページ分割された商品一覧（data／products）の両方が含まれます。カテゴリーの規模を把握するには集計値を、個別商品を分析するには商品行を使用してください。

販売数と価格の通貨：sales／monthlySalesUnits は販売個数、price／revenue はロシアルーブル（₽）です。通貨は currency で示されます。

期間：デフォルトでは直近30日間のデータを取得します（実際の期間は startDate／endDate に表示されます）。過去の月のスナップショットを取得するには、date に yyyy-MM（例：2026-02）を指定してください。

パラメーター

パラメーター	型	必須	説明
categoryId	string	はい	Ozon のカテゴリー ID。例：15621032_15621049_115951147（階層レベルは _ でつなぎます）。
page	object	はい	ページネーション {page, pageSize, orders[]}。
page.page	integer	いいえ	ページ番号。1から指定します（デフォルトは1）。
page.pageSize	integer	いいえ	ページサイズ。デフォルトは20です。最大20。これを超える値は拒否されます（errcode 1002）。
page.orders	array	いいえ	並べ替えルール。要素は {field, direction}（両方必須）で、direction は DESC／ASC です。よく使われるフィールド：sales、price、revenue、reviewRating。
date	string	いいえ	過去の月を指定する yyyy-MM（例：2026-02）。省略すると直近30日間が対象です。
fulfillment	string	いいえ	フルフィルメントのフィルター。FBO／FBS／RFBS／FBP／OZON のいずれかを指定します。省略するとすべてが対象です。配列ではなく、単一の文字列です。
uId	string	いいえ	ユーザー ID。
memberId	string	いいえ	メンバー ID（データの帰属先）。

必須パラメーターは categoryId と page のみです。

呼び出し方法

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

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

• 常に完全なレスポンスを <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-seerfar-ozon-category-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. カテゴリーのベストセラー（30日間の販売数で並べ替え）

{"categoryId": "15621032_15621049_115951147", "page": {"page": 1, "pageSize": 20, "orders": [{"field": "sales", "direction": "DESC"}]}}

2. カテゴリーの売上上位商品

{"categoryId": "15621032_15621049_115951147", "page": {"page": 1, "pageSize": 20, "orders": [{"field": "revenue", "direction": "DESC"}]}}

3. カテゴリーの高価格帯商品（価格が最も高い商品）

{"categoryId": "15621032_15621049_115951147", "page": {"page": 1, "pageSize": 20, "orders": [{"field": "price", "direction": "DESC"}]}}

4. 過去月のスナップショット

{"categoryId": "15621032_15621049_115951147", "date": "2026-02", "page": {"page": 1, "pageSize": 20, "orders": [{"field": "sales", "direction": "DESC"}]}}

5. FBO で配送される商品のみを対象にする

{"categoryId": "15621032_15621049_115951147", "fulfillment": "FBO", "page": {"page": 1, "pageSize": 20, "orders": [{"field": "sales", "direction": "DESC"}]}}

6. カテゴリー内の次のページに進む

{"categoryId": "15621032_15621049_115951147", "page": {"page": 2, "pageSize": 20, "orders": [{"field": "sales", "direction": "DESC"}]}}

クエリの作成方法

1. 必ず page.orders を渡します：カテゴリーには多数の商品が含まれる場合があります。注目する指標で並べ替えます（ベストセラーは sales DESC、売上上位は revenue DESC、高価格帯は price DESC、レビュー評価上位は reviewRating DESC）。
2. pageSize は 20 以下にします：ゲートウェイのページサイズ上限は 20 です。ページ送りには page.page を使い、次のページがあるかどうかは hasNextPage で確認します。
3. まず categoryId を解決します：ユーザーが ID ではなくカテゴリー名を指定した場合は、このスキルを呼び出す前に、上流の Seerfar Ozon ソースから categoryId を取得します。
4. カテゴリー全体の規模の把握には集計値を使います：totalSales、totalRevenue、avgPrice、rating はカテゴリー全体の概要を示します。商品ごとの詳細を確認する前に、販売規模や価格帯の評価に使用します。
5. 過去との比較には date を使います：現在の 30 日間の期間と過去の月を比較するには、date に yyyy-MM を渡します。
6. fulfillment は単一の文字列です：配列ではなく、FBO／FBS／RFBS／FBP／OZON のいずれか 1 つを渡します。

表示ルール

1. データのみを提示します：主観的なアドバイスは含めず、カテゴリーの集計値と商品指標を見やすい表で示します。
2. カテゴリーの情報を先に示し、その後に商品列を表示します：カテゴリー名（categoryInfo.cnTitlePath／enTitlePath から取得し、正しいカテゴリーであることを確認します）を示し、続けて totalSales、totalRevenue、avgPrice、rating、季節性（seasonalityAmplitude／seasonalityCoef）、日付範囲を表示します。さらに、配送方式の内訳（sellerType マップ）を FBO／FBS／RFBS／…の割合として 1 行で示し、その後に sku、title、price、sales、revenue、reviewRating、reviewCount、brandName、sellerName の表を表示します。
3. 通貨：price／revenue の単位はルーブル（₽）です。currency の記号を付けて表示します。
4. 配送方式：fulfillment は配列（例：["FBO"]）です。複数の値は / で連結します。
5. 統合フィールドと元のフィールド：productId／rating／brand／monthlySalesUnits／monthlySalesRevenue／productPageUrl は、それぞれ sku／reviewRating／brandName／sales／revenue／productUrl に対応します。いずれか一方を表示し、元のフィールドを優先します。
6. ページ送りの案内：hasNextPage が true の場合は、page.page を指定して次のページを取得できることをユーザーに伝えます。また、pageSize の上限が 20 であることも案内します。
7. 空のカテゴリー：存在しない categoryId を指定すると、total=0 でデータなしの成功応答が返ります。システムエラーとして報告するのではなく、ID が誤っている可能性をユーザーに伝えます。
8. エラー処理：code が "200" ではない場合（または errcode が 200 ではない場合）、msg／errmsg に記載された理由を説明し、修正方法（page を追加する、pageSize を小さくする、レート制限時に再試行する）を提案します。

重要な制限事項

• categoryId と page はどちらも必須です。いずれかを省略すると errcode 400 が返ります。
• pageSize の上限は 20 です。これを超えると errcode 1002 が返ります。
• カテゴリー内でのテキスト／キーワード検索には対応していません：このエンドポイントで絞り込めるのは、カテゴリー（および任意の fulfillment と date）のみです。キーワードで商品を検索するには、Seerfar Ozon のマーケットキーワード検索スキルを使用してください。
• total はページ内の行数であり、カテゴリー内の商品総数ではありません。さらにページを取得するかどうかは hasNextPage で判断します。
• sellerType は販売者の種類ではなく、配送方式の内訳です：名前にかかわらず、トップレベルの sellerType は配送モデル → 商品数（{FBO, RFBS, FBP, FBS, OZON}）のマップです。本土／越境（local/cross-border）の情報は含まれません。カテゴリー名のパス（CN／EN／RU）と crossBorderSellable は categoryInfo に含まれます。

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

適用対象 — Ozon の 1 つのカテゴリーの商品と集計データを分析する場合：

ユーザーの表現	シナリオ
「この Ozon カテゴリーの商品を分析して」／「このカテゴリーの規模はどれくらい？」	カテゴリー規模の算出（totalSales / totalRevenue / avgPrice）
「このカテゴリーで最も売れている商品は？」	ベストセラーの抽出（販売数で並べ替え）
「このカテゴリーで売上高が最も高い商品は？」	売上高上位商品の抽出（売上高で並べ替え）
「このカテゴリーの価格帯／客単価は？」	価格帯の分析（価格で並べ替え）
「このカテゴリーで評価が最も高い商品は？」	高評価商品の抽出（reviewRating で並べ替え）
「このカテゴリーの先月のデータは？」	過去の月次スナップショット（date）
「このカテゴリーの FBO 商品は？」	フルフィルメントの絞り込み

適用対象外 — 1 つのカテゴリーの商品リストを超える情報が必要な場合：

• 1 つの店舗／販売者の商品一覧 → Seerfar Ozon 店舗検索スキルを使用します。
• マーケットレベルのキーワード発見 → Seerfar Ozon マーケットキーワード検索スキルを使用します。
• キーワードの抽出 → Seerfar Ozon キーワード抽出スキルを使用します。
• 単一商品の詳細情報すべて → 商品レベルの Seerfar Ozon ソースを使用します（このスキルが返すのはカテゴリー単位のフィールドのみです）。

境界の判断：ユーザーがすでに categoryId を持っている（または上流のソースから解決済みである）状態で、そのカテゴリーの商品を販売数／価格／評価で列挙、ランキング、または規模算出したい場合は、ここから開始します。店舗の商品一覧、キーワードの発見、または単一商品の詳細情報を求めている場合は、対応する Seerfar Ozon スキルに振り分けます。

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

計算リソースを 15 消費します。

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

フィードバック：

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

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

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

---

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