linkfox-mpstats-ozon-product-trend

MPSTATS Ozon 商品トレンド（日次時系列）

このスキルは、単一の Ozon（ロシア）SKU の日次時系列データ（販売個数、価格、在庫、評価、オプションで検索順位／可視性の指標）を返します。特定の商品について、成長、季節性、異常を検証する際に最適です。

基本概念

単一 SKU の範囲：各呼び出しで分析する productId は1 つだけです。SKU ごとの一括スナップショット（期間集計）には、代わりに mpstats-ozon-product-detail を使用してください。

日次粒度：レスポンスは、[startDate, endDate] の期間にわたる日次ポイントの配列（トップレベルフィールド data）です。各ポイントには hasData ブール値が含まれます。hasData=false の日は観測データがありません（hasData=true で sales=0 の場合とは異なります）。

T-1 の遅延：MPSTATS のトレンドデータには 1 日の遅延があります。選択できる最新の終了日は昨日です。当日または未来の日付は拒否されます。

検索可視性の追加データ：検索順位／可視性のシグナルを追加するには、includeSearchStats: true を設定します。一部のニッチ市場（特に小規模カテゴリー）では検索統計の対象外の場合があります。その場合、フィールドの一部が欠落したり、空になったりすることがあります。

パラメーター

パラメーター	型	必須	説明
productId	integer	はい	Ozon SKU（数値）
startDate	string	いいえ	期間の開始日。YYYY-MM-DD 形式。最新は昨日
endDate	string	いいえ	期間の終了日。YYYY-MM-DD 形式。最新は昨日
includeFbs	boolean	いいえ	FBO と合わせて FBS データを含める
includeSearchStats	boolean	いいえ	検索順位／可視性のシグナルを追加する

呼び出し方法

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

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

• 常に完全なレスポンスを <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-mpstats-ozon-product-trend-<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. SKU の月次トレンド

{
  "productId": 1786874757,
  "startDate": "2025-03-01",
  "endDate": "2025-03-31"
}

2. 検索可視性を含むトレンド

{
  "productId": 1786874757,
  "startDate": "2025-02-01",
  "endDate": "2025-02-28",
  "includeSearchStats": true
}

3. FBO と FBS を組み合わせたトレンド

{
  "productId": 151623766,
  "startDate": "2025-01-01",
  "endDate": "2025-01-31",
  "includeFbs": true
}

他の Ozon スキルとの連携方法

1. 商品検索 → トレンド確認：mpstats-ozon-product-search を使って SKU を見つけ、仕入れを決定する前に、ここで成長や変動性を確認します。
2. 集計値と時系列：mpstats-ozon-product-detail は期間内の指標をそれぞれ 1 つの数値で示し、このスキルはその数値の背後にある日ごとの推移を示します。
3. 詳細確認 → トレンド確認：brand-products／category-products／seller-products で人気 SKU が見つかった後、このスキルを使って、人気が最近のものか、季節的なものか、継続しているものかを検証します。

表示ルール

1. シンプルなテーブル、またはスパークラインに適した形式を優先してください — 日付ごとに1行とし、date、price、sales、balance、rating、commentsを含めます。90点の系列を1つの段落に詰め込まないでください。
2. hasDataを使って、データの欠落と売上ゼロを区別してください — hasData=falseは、その日の観測データがないことを意味します。売上ゼロの日として報告しないでください。
3. 異常値を指摘してください — 1日での大幅な急増や在庫切れ（hasData=trueの状態でbalance=0が続く場合）は、購入を勧めるのではなく、事実として指摘してください。
4. 通貨はRUBです。上流レイヤーですでに換算されている場合を除きます（各ポイントのcurrencyフィールドには、例として₽のように通貨記号が含まれます）。価格の推移を示す際は通貨を明記してください。
5. 日別の売上高は返されません — ユーザーが日別の売上高を求めた場合は、sales * priceで推定し、推定値であることを注記してください。
6. includeSearchStatsの欠落 — 検索可視性に関するフィールドが返されない場合は、黙って省略せず、「このカテゴリーでは検索順位データは現在利用できません」と記載してください。
7. ビジネス上の助言はしないでください — 状況を示すにとどめ、「この商品ページを購入すべきか」はユーザーに委ねてください。

重要な制限事項

• 1回の呼び出しにつき1つのSKUのみ — productIdのリストは渡せません。必要に応じて、Agentレイヤーでループ処理してください。
• 前日までのデータ — endDateに今日または未来の日付は指定できません。
• 検索統計は任意です — includeSearchStats=trueでも、すべてのニッチ分野でデータが得られるとは限りません。
• Ozonのみ対応 — Wildberriesなど、ほかのロシアのマーケットプレイスには対応していません。
• 欠損日 — データが取得されなかった日には、系列にnullや欠落が含まれる場合があります。nullを売上ゼロとして扱わないでください。

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

該当するケース — 単一SKUの時系列分析：

ユーザーの質問	シナリオ
「先月のOzon SKU 1786874757の売上推移は？」	月次時系列
「このOzonの商品ページは季節性がありますか、それとも安定していますか？」	季節性の確認
「このOzon商品は最近、在庫切れになりましたか？」	在庫異常の検出
「このOzon商品の第1四半期の価格推移は？」	価格推移
「この商品ページの検索順位は上がりましたか？」	検索可視性（includeSearchStatsが必要）

該当しないケース — 単一SKUの時系列分析を超える要件：

• 多数のSKUの一括スナップショット → mpstats-ozon-product-detail
• ブランド／カテゴリー／販売者の詳細分析 → 対応する*-productsスキル
• ID指定前の商品の探索 → mpstats-ozon-product-search

判断基準：質問が「この1つの商品は時間の経過とともにどう変化しましたか」という内容の場合は、このスキルを使用してください。複数SKUの比較や、属性レベルでのフィルタリングには、別のスキルを使用してください。

算力消耗规则

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

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

フィードバック：

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

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

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

---

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