kalodata

KaloData TikTok Shop アナリティクス（kalo）

KaloData による TikTok Shop の e コマース分析 — 商品、ショップ、クリエイター、動画、ライブ配信、カテゴリーのランキングと詳細情報を確認できます。

実行

CLI はこのスキルに同梱されています（scripts/kalo.py、Python 3.11+ の標準ライブラリのみを使用。インストールは不要です）。

python3 <this-skill-dir>/scripts/kalo.py product rank --region US

以下の例では、python3 <this-skill-dir>/scripts/kalo.py の略称として kalo を使用します。

標準出力には TOON（トークン指向）形式で出力されます。生の JSON を出力するには、任意のコマンドに --json を追加してください。 エラーは、対処方法を示す help: 行とともに構造化されて標準出力に出力されます。終了コード：0 は正常、1 はエラー、2 は使用方法のエラーです。

セットアップ — 最初のクエリの前に確認してください

すべてのコマンドで KaloData API キーが必要です（secret-key ヘッダーで送信されます）。セッションで最初の クエリを実行する前に kalo config を実行し、api_key を確認してください。missing と表示されたら、そこで中止してください。キーを推測したり、クエリを再試行したりしないでください。次の 3 つの手順をユーザーに案内し、返答を待ちます。

1. キーを取得する — https://www.kalodata.com/open-center/account にサインインし、 generate key をクリックします。まだアカウントをお持ちでない場合は、まず https://www.kalodata.com/open-center/home で登録してください。 すでにクレジットベースの課金で KaloData API を呼び出している場合は、同じキーをここでも使用できます — 新しいキーは必要ありません。

2. キーを保存する — kalo config set --key <API_KEY>（~/.config/kalodata/config.toml に保存されます。 ファイルのモードは 0600 です）。または、環境変数に KALODATA_API_KEY を設定します。

3. クレジット — クエリごとに Kalo クレジットを消費します。1 回の呼び出しあたりの実測コスト：

   呼び出し	クレジット
   任意のランキングまたは詳細情報の取得	0.2
   product images	0.01
   creator images	0.1
   product specs	0.1
   video url	0.5
   product comments（上流キャッシュが更新される場合のみ）	1
   credit balance、credit logs	無料

   コストは本番環境で計測されています。このスキルの source-type: SKILL ヘッダーでは、ランキングや詳細情報の取得に一律 0.2 クレジットが課金されます。プレイブックは多数の呼び出しを行うため、合計で 1〜2 クレジットになります。 kalo credit で残高を確認できます。チャージは https://www.kalodata.com/pricing で行ってください。

ユーザーが依頼したクエリについて、クレジットコストを知らせたり尋ねたりする必要はありません。そのまま実行してください。コストに触れるのは、大規模な並列呼び出し（データ収集プレイブックや、数十件の詳細情報の取得）で残高が不足する可能性がある場合（まず kalo credit を確認してください）、またはユーザーから尋ねられた場合に限ります。

コマンド

コマンド	内容
kalo product rank	商品ランキング。--category、--keyword、--price、--launch、--shop、--creator を指定できます
kalo product detail <id...>	価格帯、ショップ ID、売上推移、商品説明
kalo product comments <id...>	レビュー分析：問題点、好意的な点、使用シナリオ（更新ごとに 1 クレジット）
kalo product specs <id...>	セールスポイント（ハイライト）と仕様属性。--lang zh-CN で翻訳します
kalo product images <id...>	商品ギャラリーの画像 URL
kalo shop rank	ショップランキング。--type BRAND|RETAILER、--keyword を指定できます
kalo shop detail <id...>	売上内訳、上位商品の ID
kalo creator rank	クリエイターランキング。--followers、--engagement、--product を指定できます
kalo creator detail <id|@handle...>	連絡先のメールアドレス／ハンドル、GPM、推移。ハンドルの照合は曖昧検索です — 返された creator_handle を確認してください
kalo creator images <id...>	アバター URL。最大 100 件のクリエイター ID を指定できます
kalo video rank	ショッピング可能な動画のランキング。--product、--creator、--keyword、--ai を指定できます
kalo video detail <id...>	動画の全指標と推移
kalo video url <id...>	再生可能な mp4 URL
kalo live rank	ライブ配信ランキング。--keyword を指定できます
kalo live detail <id...>	視聴者数、GPM、上位商品の ID
kalo category rank	カテゴリーランキング。--level 1|2|3 を指定できます
kalo category detail <id...>	カテゴリーの売上内訳と推移
kalo category search <kw>	キーワードからカテゴリー ID を検索
kalo credit	このキーのクレジット残高
kalo credit logs	クレジットの利用先。--range、--type、--page を指定できます
kalo config	認証情報とデフォルト設定の表示／設定

規約

• すべての一覧コマンドでは、--region --range --page（1-5）--limit（5-100）--sort --asc --fields --json を指定できます
• リージョン：US GB ID TH VN PH MY SG JP MX DE IT FR ES BR；期間は last7Day、last30Day、yyyy-MM、または yyyy-MM-dd~yyyy-MM-dd の形式です
• 数値範囲は「min-max」形式で、両端に数値を指定します。例：--revenue 1000-50000
• 商品／ショップのランキングまたは商品詳細で --images を追加すると、画像 URL を含められます。クリエイターのアバターは kalo creator images から取得します（クリエイターランキングには画像列がありません）
• 署名付きメディア URL（product images、creator images、video url）は、呼び出しから約5分後に有効期限が切れます。ユーザーに渡すか、すぐにダウンロードしてください。キャッシュには保存しないでください
• コマンドごとのフラグと使用例を確認するには、kalo <command> --help を実行します

一般的なワークフロー

• トレンド調査：kalo product rank --region US --range last7Day → kalo product detail <id> → kalo video rank --product <id>
• クリエイターの調査：kalo creator rank --category <id> --followers 10000-1000000 → kalo creator detail <id>（連絡先メールアドレスが含まれます）
• カテゴリーの詳細調査：kalo category search "beauty" → kalo category detail <id> → kalo shop rank --category <id>

プレイブック

複雑な分析（商品／クリエイターの診断、カテゴリーの仕入れ調査、クリエイターの推薦、バイラル動画の手法、ショットごとの脚本作成）を行う場合は、まず references/playbooks.md を読み、必須の手順に従ってください （結論を出す前に、必ず同じカテゴリー／同じ価格帯／同じフォロワー層の対象と比較してください）。