linkfox-echotik-list-video-rank

EchoTik - TikTok動画ランキング

EchoTikのデータソースを通じて、TikTok Shopの動画ランキングデータを取得します。越境セラーやマーケターが、日次、週次、月次ランキングで好成績を収めている動画を見つけるのに役立ちます。地域別に無料のフィルターを使って動画を一覧表示するlinkfox-echotik-list-videoとは異なり、このツールは選択した指標で並べ替えた、日付指定のランキングを返します。

基本概念

EchoTikはTikTok Shopの分析プラットフォームです。このツールは、選択した日、週、月の動画ランキングを、選択したランキング指標で並べ替えて返します。

必須入力：date、rankType、region、videoRankFieldはすべて必須です。必須フィールドにデフォルト値はありません。

関連スキル：日付指定のランキングではなく、地域別に無料のフィルター（クリエイター／商品／再生数の範囲／広告／AIフラグ）を使って動画を一覧表示するには、linkfox-echotik-list-videoを使用してください。このスキルは、日付を指定した動画ランキング向けです。

データフィールド

レスポンスのdata[*]動画オブジェクトには、ドキュメント化されたフィールドが25個あります。指標名はtotalで始まりますが、ランキング期間の累計値を表します。主なフィールドは次のとおりです。

フィールド	説明
videoId / officialUrl / coverUrl	動画ID／TikTok URL／カバー画像URL
videoDesc / duration / createDate	説明／長さ（秒）／公開日
userId / uniqueId / nickName / avatar	クリエイターID／TikTokアカウントID／ニックネーム／アバター
category / region	クリエイターのカテゴリ／マーケットプレイスコード
totalViewsCnt / totalDiggCnt / totalCommentsCnt	期間内の再生数／いいね数／コメント数
totalSharesCnt / totalFavoritesCnt	期間内のシェア数／お気に入り数
totalVideoSaleCnt / totalVideoSaleGmvAmt	期間内の動画経由の販売数（推定）／売上GMV（推定）
salesFlagText / createdByAiText	販売動画フラグ／AI動画フラグ（是／否）
productCategoryList / videoProducts	販売商品のカテゴリ／商品
sourceType / sourceTool	商品のソース／ソースツール

型を含む全フィールドの一覧はreferences/api.mdにあります。このデータ構造はlinkfox-echotik-list-videoとは異なります（width／height／ratio、1d／7d／30dの内訳、isAdTextはありません）。

パラメーターガイド

パラメーター	型	必須	デフォルト	説明
date	string	はい	-	クエリ日付。YYYY-MM-DD形式
rankType	integer	はい	-	ランキングの種類（値は以下を参照）
region	string	はい	-	マーケットプレイスコード。対応する一覧は以下を参照
videoRankField	integer	はい	-	ランキング指標（値は以下を参照）
productCategoryId	string	いいえ	-	販売動画ランキングの絞り込みに使う、レベル1の商品カテゴリID
createdByAi	string	いいえ	-	AI動画フィルター：trueまたはfalse
pageNum	integer	いいえ	1	ページ番号。1から開始
pageSize	integer	いいえ	50	ページサイズ。10の倍数で指定し、最大100

rankTypeの値

値	意味
1	日次ランキング（日）
2	週次ランキング（週）
3	月次ランキング（月）

videoRankFieldの値

値	意味	検証済み
1	再生数順（播放量）	✓ 200
2	動画経由の販売数順（视频销量）	✓ 200

指標の欠損：videoRankFieldで指定した指標でランキングする場合、他の指標のフィールドは0を返すことがあります（販売数順の場合、再生数／いいね数／コメント数が0になることがあります。再生数順の場合、販売数／GMVが0になることがあります）。

対応マーケットプレイス

US（米国）、ID（インドネシア）、TH（タイ）、PH（フィリピン）、MY（マレーシア）、VN（ベトナム）、GB（英国）、MX（メキシコ）、SG（シンガポール）、SA（サウジアラビア）、BR（ブラジル）、ES（スペイン）、JP（日本）、DE（ドイツ）、IT（イタリア）、FR（フランス）

ユーザーがマーケットプレイスを指定しない場合は、確認するか、USをデフォルトとして使用してください。

呼び出し方法

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

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

• 常に完全なレスポンスを <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-echotik-list-video-rank-<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. 指定日の米国動画再生数ランキング

{
  "date": "2026-08-10",
  "rankType": 1,
  "region": "US",
  "videoRankField": 1,
  "pageNum": 1,
  "pageSize": 20
}

2. 英国の週間動画ランキング

{
  "date": "2026-08-10",
  "rankType": 2,
  "region": "GB",
  "videoRankField": 1
}

3. AI動画に絞り込んだ米国の月間売上ランキング

{
  "date": "2026-08-01",
  "rankType": 3,
  "region": "US",
  "videoRankField": 2,
  "createdByAi": "true",
  "productCategoryId": "601450",
  "pageNum": 1,
  "pageSize": 20
}

表示ルール

1. データは表で表示：動画の説明（長い場合は省略）、再生数、いいね数、コメント数、シェア数、動画の売上、動画のGMV、公開日、クリエイター ID を表示してください。
2. 順位順：結果は選択した videoRankField に基づいてすでに順位付けされています。順位を維持して表示してください。
3. 元動画へのリンク：officialUrl がある場合は、ユーザーが TikTok で動画を見られるようにリンクを提供してください。
4. 推定値に関する注意：動画の売上とGMVは推定値です。概算であることをユーザーに伝えてください。
5. 結果件数：total のレコード数と現在のページを必ず伝えてください。結果が多い場合は、ページ送りを提案してください。

重要な制限事項

1. 必須フィールドは4つすべて：date、rankType、region、videoRankField は必須です。デフォルト値は適用されません。
2. ランキングデータには1～2日の遅延があります：直近のランキングデータは取得できず、errcode:10000（「一致するデータがありません」）が返される場合があります。必要に応じて、より前の日付を指定してください。
3. ランキングと一覧の違い：これは日付を指定したランキングです。地域ごとの動画一覧を自由なフィルター（クリエイター／再生数の範囲／広告／AI フラグ）で取得するには、linkfox-echotik-list-video を使用してください。
4. 二次処理には非対応：結果はライブクエリで取得されます。二次的な SQL／データ処理は利用できません。

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

該当する場合 — TikTok 動画ランキング／チャート：

ユーザーの表現	シナリオ
「TikTok视频排行」／「TikTok top video chart」	期間と指標を選択した動画ランキング
「本周TikTok最火的视频」	週間ランキング（rankType:2）
「本月TikTok带货视频榜」	月間売上ランキング（rankType:3）
「TikTok带货视频排行」	販売動画のランキング（売上／GMV の列を確認）
「英国TikTok视频榜单」	region=GB のランキング

該当しない場合 — 日付指定の動画ランキングを超える内容が必要な場合：

• 自由なフィルターを使った地域ごとの動画一覧（linkfox-echotik-list-video を使用）
• productId で指定した1つの商品に関する動画（linkfox-echotik-product-video を使用）
• 動画のダウンロード URL の解決（linkfox-echotik-get-video-download-url を使用）
• TikTok の商品／販売者ランキング

適用範囲の判断：ユーザーが日付または地域を指定して「動画ランキング／動画一覧／人気動画」を求めている場合、このスキルが該当します。ランキングではなく、クリエイター、再生数の範囲、広告／AI フラグで動画を絞り込みたい場合は、linkfox-echotik-list-video を使用してください。

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

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

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

フィードバック：

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

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

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

---

高品質でプロフェッショナルな越境ECスキルについては、LinkFox Skillsをご覧ください。