linkfox-kalodata-tiktok-shop

Kalodata - TikTok Shop の検索と詳細

このスキルでは、Kalodata のデータソースを使って、次の 2 段階の TikTok Shop ワークフローを実行できます。

1. TikTok Shop の店舗ランキングを参照し、好調な店舗を見つけます。
2. shopId を指定して、1 店舗の詳細情報を取得します。

ランキングや店舗の検索、店舗間の比較をユーザーが希望している場合は、検索（ランキング）エンドポイントを使用します。ユーザーがすでに shopId を指定している場合や、ランキング結果から店舗を選択済みの場合は、詳細エンドポイントを使用します。

基本概念

店舗ランキングエンドポイントは、region、dateRange、language、currency でフィルタリングされたページ分け済みのランキングを返します。デフォルトの並び順は revenue（GMV）の降順で、各行には明示的な rank 順位が含まれます。各店舗の行には、識別情報、規模、売上チャネルの内訳、成長率が含まれます。

店舗詳細エンドポイントは、shopId を指定して 1 店舗 の情報を取得します。店舗の識別情報、規模、売上チャネルの内訳、クリエイター数／動画数／ライブ配信数を返します。shopId は通常、ランキングレスポンスの shop_id フィールドから取得します。

⚠️ 店舗の RANK エンドポイントと DETAIL エンドポイントでは、フィールド名が異なります。 詳細では self_account_revenue を使用します（ランキングでは self_promotion_revenue）。また、shoppingmall_revenue は内部にアンダースコアがありません（ランキングでは shopping_mall_revenue）。さらに、詳細では seller_type を使用します（ランキングでは shop_type）。詳細では creator_number／video_number／live_number／product_number が返されますが、ランキングでは返されません。また、詳細では rank／revenue_growth_rate／on_sell_product_count は返されません。必ず各エンドポイントの正確なフィールド名を使用してください。

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

データフィールド

ランキングの行には、次のフィールドが含まれます。

フィールド	説明
rank	順位（1 = 売上上位）
shop_name	店舗の表示名
shop_id	店舗の一意な ID。詳細情報の取得時に shopId として渡します
shop_type	店舗の種類（例：BRAND）
revenue	指定した通貨での合計 GMV
sales_volumn	販売数量。フィールド名の綴りは volumn です
on_sell_product_count	現在販売中の商品数
unit_price	指定した通貨での平均単価
revenue_growth_rate	売上成長率（%）。マイナスになる場合があります
self_promotion_revenue	自己販促による売上（店铺自营/自播自推）
affiliate_revenue	アフィリエイトによる売上（达人分销）
shopping_mall_revenue	ショッピングモールによる売上（商城）

詳細の行には、次のフィールドが含まれます。

フィールド	説明
shop_id	店舗の一意な ID（精度を保つため文字列）
shop_name	店舗の表示名
seller_type	販売者／店舗の種類（例：BRAND）。shop_type ではなく seller_type であることに注意してください
region	市場の地域（例：US）
revenue	指定した通貨での合計売上／GMV
sales_volumn	販売数量。フィールド名の綴りは volumn です
product_number	販売中の商品数
unit_price	指定した通貨での平均単価
self_account_revenue	自社アカウントによる売上（店铺自营/自播自推）。self_promotion_revenue ではなく self_account_revenue であることに注意してください
affiliate_revenue	アフィリエイトによる売上（达人分销）
shoppingmall_revenue	ショッピングモールによる売上（商城）。shopping と mall の間にアンダースコアがないことに注意してください
creator_number	店舗と提携しているクリエイターの数（达人合作数）
video_number	関連動画の数
live_number	関連ライブ配信の数

売上チャネルの内訳：ランキングエンドポイントでは revenue = self_promotion_revenue + affiliate_revenue + shopping_mall_revenue です。詳細エンドポイントでは revenue ≈ self_account_revenue + affiliate_revenue + shoppingmall_revenue です。各項目は revenue とは独立して丸められる場合があります（例：詳細では shoppingmall_revenue が 10431.0、ランキングでは 10431.39 と返されます）。そのため、内訳は概算として扱い、厳密な一致を前提としないでください。

パラメーターガイド

ショップランキング（/kalodata/shop/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_ids	array	いいえ	カテゴリー ID のリストによるフィルター
revenue_range	string	いいえ	売上／GMV の範囲によるフィルター
shop_type	string	いいえ	ショップの種類によるフィルター：BRAND または RETAILER
sortField	object	いいえ	並べ替えの指定。デフォルトの売上ランキングを使用する場合は {} を指定します

ショップ詳細（/kalodata/shop/detail）

パラメーター	型	必須	説明
shopId	string	はい	ランキングのフィールド shop_id にあるショップ固有 ID
category_id	string	いいえ	任意のカテゴリー ID ディメンション
region	string	いいえ	市場地域コード。例：US
dateRange	string	いいえ	期間。例：last7Day、last30Day
language	string	いいえ	レスポンスの言語。例：zh-CN、en-US
currency	string	いいえ	金額指標の通貨。例：USD

呼び出し方法

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

出力ポリシー（スクリプトのデフォルトの動作）：

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

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

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

以下の異常が発生した場合は、references/onboarding.md に沿って解決してください。

異常

• API Key が未設定：環境変数 LINKFOX_AGENT_API_KEY も LINKFOXAGENT_API_KEY も設定されていません。
• 401 または 402 のステータスコードが返された場合
• 計算リソースまたは残高不足を示すレスポンス：メッセージに「計算リソースの残高不足／課金不足／残高不足／quota exceeded／insufficient balance／プランの期限切れ／チャージが必要／チャージしてください」、または同様の意味の内容が含まれている場合。

使用例

1. 過去 7 日間の米国 TikTok ショップ上位

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

2. 1 件のショップの詳細を取得

{"shopId":"7495514739648989419","region":"US","dateRange":"last7Day","currency":"USD"}

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

Run kalodata_shop_search.py first, choose a row's shop_id, then pass that value as shopId to kalodata_shop_detail.py.

表示ルール

1. ランキング結果は、順位、ショップ名、ショップの種類、売上、販売数、商品数、単価、成長率を含むテーブルで表示します。
2. 詳細結果は、基本情報、規模、売上チャネルの内訳、クリエイター／動画／ライブ配信の数をまとめたプロフィールとして表示します。
3. 指標を表示する際は、必ず dateRange、region、currency を明記します。
4. 売上チャネルの内訳は概算です（「データフィールドに関する注記」を参照）。厳密な合計ではなく、内訳として表示します。
5. フィールド名は正確に sales_volumn を使用します。詳細では shoppingmall_revenue（アンダースコアなし）と self_account_revenue を使用し、ランキングでは shopping_mall_revenue と self_promotion_revenue を使用します。2 つのエンドポイントのフィールド名を混在させないでください。
6. creator_number、video_number、live_number、product_number は整数の件数として表示します。
7. ユーザーがサポートされている sortField を明示的にリクエストしない限り、ランキング順を維持します。

重要な制限事項

• ランキングはキーワード検索ではなく、地域や期間ごとのランキングを参照します。
• 詳細情報の取得には shopId が必要です。店舗名だけで店舗を検索することはできません。ランキングの shop_id フィールドまたはユーザーから shopId を取得してください。
• ランキングのレスポンスには合計件数やページ数が含まれません。ページの項目数が pageSize 未満になるまでページネーションを続けてください。
• pageNumber は1～5、pageSize は5～100に制限されています。
• 詳細情報にはページネーションがありません。1店舗の場合、data は1要素の配列であり、total はありません。
• ランキングと詳細のエンドポイントではフィールド名が異なります（「データフィールド」を参照）。データを抽出する際は、正確なフィールド名を使用してください。
• 一時的な上流エラーは、Kalodata の HTTP 554 メッセージを伴う errcode 501 として表示されることがあります。同じパラメーターで1～2回再試行してください。パラメーターを自動的に変更しないでください。
• 店舗以外のエンティティには、該当する Kalodata の商品／動画／クリエイター／ライブ配信スキルを使用してください。

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

適用対象 -- TikTok Shop の店舗ランキングまたは単一店舗の詳細情報：

ユーザーの発言	シナリオ
"TikTok店铺排行榜", "TikTok小店排行"	店舗ランキングの検索
"TikTok热销店铺", "top TikTok shops"	地域別のTikTok店舗ランキング
"近7天TikTok店铺榜", "美国TikTok店铺排名"	期間指定／地域で絞り込んだランキング
"TikTok店铺详情", "TikTok小店资料"	単一店舗の詳細情報の検索
"店铺销售额", "店铺销量", "店铺达人合作数"	店舗の売上高／販売数／クリエイター数
"kalodata shop search/detail"	データソースを直接参照

適用対象外 -- TikTok Shop の店舗情報以外を必要とする場合：

• TikTok のクリエイター／商品／動画／ライブ配信のランキングまたは詳細情報
• Amazon／Shopify／1688／その他のプラットフォームの店舗データ
• TikTok 広告キャンペーンの管理またはコンテンツの作成

計算資源の消費ルール

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

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

フィードバック：

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

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

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

---

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