linkfox-kalodata-tiktok-livestream

Kalodata - TikTok ライブ配信の検索と詳細

このスキルは、Kalodata データソースを利用した 2 段階の TikTok ライブ配信ワークフローに対応しています。

1. TikTok Shop のライブ配信ランキングを閲覧し、成果の高いショッパブルライブ配信（带货直播）を見つけます。
2. livestreamId を指定して、1 件のライブ配信の詳細なパフォーマンスを取得します。

ユーザーがランキング、人気のライブ配信、またはライブ配信の検索を希望している場合は、検索（ランキング）エンドポイントを使用します。ユーザーがすでに livestreamId を持っている場合、またはランキング結果から 1 件のライブ配信を選択した場合は、詳細エンドポイントを使用します。

基本概念

ライブ配信ランキングエンドポイントは、region、dateRange、language、currency、および任意の sortField で絞り込んだ、ページ分割されたランキングを返します。デフォルトでは、ランキングは revenue（GMV）の降順です。各ライブ配信の行には、識別情報、配信時刻、規模、クリエイターの情報が含まれます。結果は pageNumber（1～5）と pageSize（5～100）でページ分割されます。レスポンスには合計件数が含まれません。ページの項目数が pageSize を下回るまでページを取得してください。ランキングエンドポイントの金額フィールド（revenue、unit_price）は文字列として返されます。

ライブ配信詳細エンドポイントは、livestreamId で指定したショッパブルな TikTok ライブ配信を1 件取得します。単一のライブ配信の全詳細（12 フィールド）を含む1 要素の配列を返します。詳細には viewers、数値型の revenue、gpm、product_number が含まれます。ページ分割はなく、total もありません。livestreamId は通常、ランキングレスポンスの livestream_id フィールドから取得します。

2 つのエンドポイントではフィールド名と型が異なります：詳細では viewers（ランキングでは views）を使用します。詳細の revenue は数値（ランキングの revenue は文字列）です。詳細には gpm があり、unit_price はありません（ランキングには unit_price があり、gpm はありません）。一方のエンドポイントのフィールド名や型が、もう一方でも同じだと想定しないでください。

どちらのエンドポイントでも、統計データの反映に遅延（T+1）が生じる場合があります。リクエストとレスポンスの詳細は references/api.md を参照してください。

データフィールド

ランキング行（/kalodata/livestream/rank の data 内の各項目）：

フィールド	型	説明
livestream_id	string	ライブ配信の一意の ID。詳細を取得する際は、これを livestreamId として渡します
livestream_title	string	ライブ配信のタイトル
creator_id	string	クリエイターの一意の ID（精度を保つため文字列）
creator_handle	string	クリエイターのハンドル名／ユーザー名
livestream_start_time	integer	開始時刻、エポックミリ秒
livestream_end_time	integer	終了時刻、エポックミリ秒
livestream_duration	integer	配信時間（秒）
revenue	string	指定した currency での総収益／GMV — 文字列として返されます。例："185590.52"
unit_price	string	指定した currency での平均単価 — 文字列として返されます。例："265.89"
views	integer	総視聴回数（注：RANK では views を使用します）
record_type	string	レコードタイプ（例：SHORT）

詳細行（/kalodata/livestream/detail の data 内の単一項目）：

フィールド	型	説明
livestream_id	string	ライブ配信の一意の ID（指定した livestreamId と一致）
livestream_title	string	ライブ配信のタイトル（例：24 HOUR STREAM）
creator_id	string	クリエイターの一意の ID（精度を保つため文字列）
creator_handle	string	クリエイターのハンドル名／ユーザー名（例：pokepiglt）
livestream_start_time	integer	開始時刻、エポックミリ秒
livestream_end_time	integer	終了時刻、エポックミリ秒
livestream_duration	integer	配信時間（秒）
record_type	string	レコードタイプ（例：SHORT）
viewers	integer	総視聴者数（注：DETAIL では views ではなく viewers を使用します）
revenue	number	指定した currency でのライブ配信の収益／GMV（数値）（例：185590.52）。ここでは数値ですが、RANK エンドポイントでは文字列です
gpm	number	インプレッション 1,000 回あたりの GMV（収益）— DETAIL のみにあり、RANK にはありません
product_number	integer	ライブ配信中に販売／紹介された商品の数

金額フィールドは RANK では文字列、DETAIL では数値です。 数値として比較または書式設定する前に、RANK の revenue／unit_price を float()、Number()、または ConvertFrom-Json で数値に変換してください。読み取るエンドポイントに応じて正確なフィールド名を使用してください（RANK では views、DETAIL では viewers）。

パラメーターガイド

ライブ配信ランキング（/kalodata/livestream/rank） — すべてのパラメーターは任意です：

パラメーター	型	必須	説明
region	string	いいえ	市場地域コード（例：US）
dateRange	string	いいえ	期間（例：last7Day、last30Day）
pageNumber	integer	いいえ	ページ番号、1～5
pageSize	integer	いいえ	ページサイズ、5～100
language	string	いいえ	応答言語（例：zh-CN、en-US）
currency	string	いいえ	金額指標の通貨（例：USD）
category_id	string	いいえ	カテゴリー ID フィルター
shop_id	string	いいえ	ショップ ID フィルター
creator_id	string	いいえ	クリエイター ID フィルター
product_id	string	いいえ	商品 ID フィルター
followers_range	string	いいえ	クリエイターのフォロワー数範囲フィルター
sortField	object	いいえ	並べ替えの指定。デフォルトのランキング順を使用する場合は {} を渡します

ライブ配信詳細（/kalodata/livestream/detail）：

パラメーター	型	必須	説明
livestreamId	string	はい	対象ライブ配信の一意の ID（キャメルケース）。例：7661409374878878494。通常はランキングのフィールド livestream_id から取得します
region	string	いいえ	市場地域コード（例：US）
dateRange	string	いいえ	期間（例：last7Day、last30Day）
language	string	いいえ	応答言語（例：zh-CN、en-US）
currency	string	いいえ	金額指標の通貨（例：USD）

呼び出し方法

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

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

• 常に完全なレスポンスを <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-kalodata-tiktok-livestream-<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. 米国のTikTokライブ配信ランキングを確認する

{"region":"US","dateRange":"last7Day","pageSize":10,"pageNumber":1}

2. 1件のライブ配信の詳細を取得する

{"livestreamId":"7661409374878878494","region":"US","dateRange":"last7Day"}

3. 発見から詳細取得までのワークフロー

Run kalodata_livestream_search.py first, choose a row's livestream_id, then pass that value as livestreamId to kalodata_livestream_detail.py.

表示ルール

1. データのみを提示：ランキングは見やすい表（ライブ配信タイトル、クリエイターのハンドル名、売上、視聴回数、配信時間、単価、開始／終了時刻）で表示し、詳細は1件分のプロフィールとしてまとめてください。主観的なビジネスアドバイスは含めないでください。
2. ランキング順：デフォルトの順序は revenue（GMV）の降順です。明示的な rank フィールドはなく、順位は並び順で示されます。ユーザーがサポート対象の sortField を明示的に要求しない限り、この順序を維持してください。
3. 通貨の明記：ランキングでは revenue／unit_price とともに、詳細では revenue／gpm とともに、要求された currency を表示してください。
4. RANK の金額は文字列：RANK の revenue と unit_price は文字列（例："185590.52"）で返されます。数値として比較または書式設定する前に、数値に変換してください。DETAIL の revenue は数値です。jq／ConvertFrom-Json で抽出する際は、正確なフィールド名を使用してください。
5. 視聴者数と視聴回数：ランキングの行には views を、詳細の行には viewers を使用し、混同しないでください。
6. GPM：gpm は千回あたりのGMV（詳細のみ）です。パーセンテージではなく、適切な精度（例：903.79）で表示してください。
7. 時間フィールド：livestream_start_time／livestream_end_time はエポックミリ秒、livestream_duration は秒です。表示時は、読みやすい現地時刻に変換してください。
8. 期間：データが対象とする dateRange（例：「過去7日間」）を必ず明記してください。
9. ページネーションの案内：ランキングのレスポンスには合計件数／ページ数がありません。1ページ分の結果がすべて返された場合、次のページをリクエストできることをユーザーに案内してください（pageNumber は最大5）。
10. 単一のエンティティ：詳細は1件のライブ配信を表します。ランキングやリーダーボードとして提示しないでください。

重要な制限事項

• ランキングはキーワード検索ではありません：地域や期間で絞り込んだライブ配信ランキングを参照します。キーワードでライブ配信を検索する機能ではありません。
• 詳細の取得には livestreamId が必要です：タイトルだけではライブ配信を特定できません。ランキングの livestream_id フィールドから livestreamId を取得してください。
• 最大5ページ、ページサイズは5～100です：pageNumber は1～5に制限されます。範囲外の場合は errcode 501, errmsg "page_number 范围为 1-5，当前: <n>" が返されます。pageSize は5～100の範囲で指定してください。
• 合計数／ページ数はありません：どちらのレスポンスにも total やページ数を示すフィールドは含まれません。ランキングのページを順に取得し、pageSize より少ない項目数が返されたら終了してください。
• エンドポイントによってフィールド名／型が異なります：DETAIL では viewers（RANK では views）を使用します。DETAIL の revenue は数値（RANK の revenue は文字列）です。DETAIL には gpm があり、unit_price はありません（RANK には unit_price があり、gpm はありません）。フィールド名や型が引き継がれると想定しないでください。
• データの遅延：どちらのエンドポイントでも、統計データに遅延（T+1）が生じる場合があります。
• 一時的な上流エラー：ゲートウェイから errcode 501, errmsg "调用 Kalodata 接口失败: Kalodata API HTTP 554: " が返されることがあります（一時的な上流 Kalodata エラー）。同じパラメーターで1～2回再試行してください。パラメーターは変更しないでください。
• 未対応の並べ替え／フィルター：リクエストした sortField をゲートウェイが受け付けない場合、回避策を試してはいけません。ユーザーに伝え、デフォルトのランキング順に切り替えてください。
• ライブ配信以外のエンティティには、該当する Kalodata スキルを使用してください：クリエイター／商品／動画／ショップのランキングや詳細を取得する場合が該当します。

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

該当 -- TikTok ライブ配信のランキング、またはライブ配信の詳細を取得する場合：

ユーザーの表現	シナリオ
"TikTok直播排行榜", "TikTok直播排行"	ライブ配信ランキングの取得
"TikTok热销直播", "top TikTok livestreams"	地域別のライブ配信ランキング
"近7天TikTok直播榜", "美国TikTok直播排名"	期間／地域で絞り込んだランキング
"Kalodata直播榜"	データソースを直接指定
"TikTok直播详情", "TikTok直播数据"	1件のライブ配信詳細の取得
"这场直播的观看人数", "这场直播卖了多少钱"	特定のライブ配信の視聴者数／売上／GPM
"TikTok livestream detail", "kalodata livestream search/detail"	詳細／ランキングデータの直接取得

該当しない -- TikTok ライブ配信以外の情報が必要な場合：

• TikTok のクリエイター／商品／動画／ショップのランキングや詳細（該当する Kalodata スキルを使用してください）
• livestreamId が不明なライブ配信の詳細（最初にランキングエンドポイントから ID を取得してください）
• Amazon／Shopify／1688／その他のプラットフォームのライブ配信データ
• TikTok の広告キャンペーン管理やコンテンツ作成

適用範囲の判断：TikTok Shop／TikTok eコマースの文脈でユーザーが「直播榜」または「直播排行」と言った場合は、ランキングエンドポイントを使用してください。特定のライブ配信の詳細指標（売上、視聴者数、配信時間、GPM）を尋ねており、livestreamId がある（またはランキングから取得できる）場合は、詳細エンドポイントを使用してください。

算力の消費ルール

呼び出し1回につき、算力を7.0消費します。

ユーザーは算力の消費に応じて料金を支払います。この点を十分に考慮してください。このスキルを頻繁に呼び出す必要がある場合、またはユーザーが算力の消費量を十分に把握していないと思われる場合は、必ずユーザーに注意を促し、続行するかどうかはユーザーに判断してもらってください。

フィードバック：

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

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

references/api.md の指定に従って Feedback API を呼び出してください。ユーザーの作業を中断しないでください。

---

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