linkfox-mpstats-ozon-category-products

MPSTATS Ozon カテゴリー商品

指定したロシア語カテゴリーのパスに含まれる Ozon（ロシア）の全商品を詳しく調査し、各 SKU の販売数、売上高、価格、評価、在庫、在庫回転期間、逸失利益などを返します。特定のカテゴリーでのベストセラー調査、ブルーオーシャン市場のニッチ発見、ブランド勢力図の把握を目的としています。

主な概念

ロシア語のフルパスが必須：categoryPath には、Ozon プラットフォームで使われているロシア語のカテゴリー完全パスを指定し、階層を / で区切る必要があります。たとえば、Одежда/Женская одежда/Футболки и топы женские です。部分的なパス、英訳、またはルートのみの値では、通常、結果が空になります。

パスの確認方法：一般的なワークフローでは、上流の Ozon カテゴリー検索ステップ（ツールチェーンで利用可能な場合）でパスを確認するか、mpstats-ozon-product-detail / mpstats-ozon-product-search から既知の SKU の category フィールドを取得します。

フィルターは AND で結合：filters には、複数フィールドの数値条件を指定します。各条件は {field, op, value, value2?} です。フィルターの詳細は「フィルターリファレンス」を参照してください。

通貨：デフォルトは RUB です。currency で上書きでき、必要に応じて currencyRate も指定できます。

FBO / FBS：includeFbs: true にすると、在庫数と販売数に FBS が含まれます。false の場合は FBO のみです。

パラメーター

パラメーター	型	必須	説明
categoryPath	string	はい	/ で区切ったロシア語のカテゴリー完全パス
startDate	string	いいえ	統計期間の開始日。YYYY-MM-DD 形式。最新日は昨日
endDate	string	いいえ	統計期間の終了日。YYYY-MM-DD 形式。最新日は昨日
page	integer	いいえ	ページ番号。1 から開始
pageSize	integer	いいえ	1 ページあたりの行数。1～100。デフォルトは 100
sortField	string	いいえ	snake_case 形式の列名：sales、revenue、final_price、balance、rating、...
sortDirection	string	いいえ	asc / desc
currency	string	いいえ	通貨コード。デフォルトは RUB
currencyRate	integer	いいえ	デフォルト以外の通貨を使用する場合のカスタムレート
includeFbs	boolean	いいえ	FBS データを含める
filters	array	いいえ	数値フィルターのリスト（以下を参照）

フィルターリファレンス

各 filters エントリー：{"field": "<snake_case>", "op": "<OP>", "value": <num>, "value2": <num?>}。

よく使うフィールド：sales（月間販売数）、final_price（価格 RUB）、rating（0～5）、comments（レビュー数）、balance（在庫数）、revenue（金額 RUB）、days_in_stock、turnover_days、lost_profit、category_position。

演算子：GTE、LTE、GT、LT、EQ、NOT_EQ、BETWEEN（value2 が必要）。

呼び出し方法

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

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

• 常に完全なレスポンスを <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-mpstats-ozon-category-products-<timestamp>.json に書き込みます（<cwd> はスクリプト実行時の作業ディレクトリです。Claude Code では現在のプロジェクトディレクトリです。<session> は環境変数 SESSION_ID から取得し、ユーザーのタスクごとに自動で集約されます。/tmp への書き込みは禁止です。現在のディレクトリに書き込めない場合はエラーになります）
• レスポンス本文が 8 KB 以下の場合：ファイルに保存した後、完全な JSON を stdout に出力します
• レスポンス本文が 8 KB を超える場合：ファイルに保存した後、stdout には要約のみを出力します（トップレベルのフィールド、total／costToken など一般的なカウント、最大のリストフィールドの長さと先頭 3 件のサンプル）
• --inline を追加すると、stdout への全量出力を強制します（同様にファイルにも保存します）

データの読み取りに関する推奨事項：まず要約を確認し、十分な情報があるか判断してください。具体的なフィールドが必要な場合は、JSON 全体をコンテキストに読み込むことを避けるため、保存済みの json ファイルから jq または ConvertFrom-Json を使って必要なデータを抽出してください。

認証と計算リソースの問題を解決する

次のような異常が発生した場合は、references/onboarding.md の案内に従って解決してください。

異常な状況

• API Key が未設定：環境変数 LINKFOX_AGENT_API_KEY も LINKFOXAGENT_API_KEY も設定されていません。
• レスポンスのステータスコードが 401 または 402
• レスポンスに計算リソースまたは残高不足の通知が含まれる：メッセージに「算力余额不足／计费不足／余额不足／quota exceeded／insufficient balance／套餐到期／需充值／请充值」、または同様の意味の内容が含まれています。

使用例

1. レディース T シャツ — 販売数順

{
  "categoryPath": "Одежда/Женская одежда/Футболки и топы женские",
  "sortField": "sales",
  "sortDirection": "desc",
  "pageSize": 100
}

2. ブルーオーシャン市場の調査（販売数 ≥ 50、評価 ≥ 4.5）

{
  "categoryPath": "Одежда/Женская одежда/Футболки и топы женские",
  "filters": [
    {"field": "sales", "op": "GTE", "value": 50},
    {"field": "rating", "op": "GTE", "value": 4.5}
  ],
  "sortField": "revenue",
  "sortDirection": "desc"
}

3. 中価格帯 ＋ 高い在庫回転

{
  "categoryPath": "Электроника/Наушники",
  "filters": [
    {"field": "final_price", "op": "BETWEEN", "value": 1500, "value2": 5000},
    {"field": "turnover_days", "op": "LTE", "value": 30}
  ]
}

4. 市場間比較のための USD 換算ランキング

{
  "categoryPath": "Электроника/Смартфоны",
  "currency": "USD",
  "sortField": "revenue",
  "sortDirection": "desc"
}

5. 逸失利益が大きいカテゴリーの調査

{
  "categoryPath": "Одежда/Мужская одежда/Куртки мужские",
  "filters": [{"field": "lost_profit", "op": "GTE", "value": 500000}],
  "sortField": "lost_profit",
  "sortDirection": "desc"
}

表示ルール

1. コンパクトなカテゴリテーブル — 主な列：productId、title、brand、sellerName、price、monthlySalesUnits、monthlySalesRevenue、rating、balance、position、revenueSharePercent。
2. 売上シェア = このカテゴリクエリ内での割合 — 0～100％です。表示する際は算出基準を明記してください。
3. ロシア語のタイトル／ブランド — 原文のまま保持し、必要に応じて翻訳してください。
4. 通貨の表記 — 通貨を明記してください。換算した場合は、"已按 USD 换算"と記載してください。
5. ページネーション — totalを報告してください。大規模カテゴリ（数万 SKU）の場合は、むやみにページをめくるのではなく、フィルターを絞り込むよう提案してください。
6. カテゴリ内順位 — 数値が小さいほど上位です。categoryPositionを表示する際は、この点に触れてください。

重要な制限事項

• ロシア語のフルパスのみ対応 — パスが部分的な場合や翻訳されている場合、結果は空になります。
• パスの特定は上流で行う必要があります — このエンドポイントではカテゴリツリーを参照できません。まず商品詳細または検索でパスを特定してください。
• ページ上限 — 1ページあたり最大100行です。
• T-1 データ — endDateに今日または未来の日付は指定できません。
• ビジネス上の助言は行いません — データのみを提供します。

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

適用対象 — カテゴリ別のOzon商品指標：

ユーザーの発言	シナリオ
「OzonのカテゴリXで売れ筋商品を教えて」	カテゴリのベストセラー発掘
「ニッチなYでブルーオーシャンのSKUを探して」	ブルーオーシャンのニッチ市場調査
「このカテゴリで中価格帯かつ回転の速い商品を見せて」	複数条件によるニッチ商品の絞り込み
「このOzonカテゴリを支配しているブランドはどれ？」	ブランド勢力図の事前調査（その後、クライアント側でブランド別にグループ化）
「カテゴリXで大きな逸失利益の機会を探して」	在庫切れによる機会損失の調査

適用対象外 — カテゴリの詳細調査を超える要件：

• カテゴリパスが不明 → mpstats-ozon-product-searchまたは商品詳細を使って、正確なロシア語パスを特定します
• ブランド別の詳細調査 → mpstats-ozon-brand-products
• セラー別の詳細調査 → mpstats-ozon-seller-products
• 単一SKUの時系列データ → mpstats-ozon-product-trend
• Wildberries／その他のロシアのマーケットプレイス → 対象外

適用範囲の判断：ディメンションがカテゴリパスで、その配下の商品ごとの集計データが必要な場合にこのスキルを使います。複数カテゴリを比較するには、複数回呼び出して、Agentレイヤーで結果を統合する必要があります。

算力消耗ルール

動的ルールに基づいて課金されます：算力の消費量 = 12。リストが空の場合は0を返します

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

フィードバック：

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

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

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

---

高品質でプロフェッショナルな越境ECスキルをさらにお探しの場合は、LinkFox Skillsをご利用ください。