linkfox-kalodata-tiktok-product

Kalodata - TikTok 商品検索と詳細

このスキルでは、Kalodata データソースを通じた TikTok Shop 商品の2段階のワークフローをサポートします。

1. TikTok Shop 商品ランキングを閲覧し、上位商品やベストセラー商品を見つけます。
2. productId を指定して、1つの商品について詳しい情報を取得します。

ユーザーがベストセラーランキング、人気商品、または商品探しを求めている場合は、ランキングエンドポイントを使用します。ユーザーがすでに productId を持っている場合や、ランキング結果から商品を1つ選択した場合は、詳細エンドポイントを使用します。

基本概念

商品ランキングエンドポイントは、region、dateRange、currency、language、および任意の sortField で絞り込んだ、ページ分けされたランキングを返します。各商品行には、識別情報、価格、販売数量、売上（動画、ライブ配信、ショーケースの各チャネル別）、売上成長率、コミッション率、発売日が含まれます。結果は pageNumber（1～5）と pageSize（5～100）でページ分けされます。

商品詳細エンドポイントは、productId を指定して TikTok Shop の1つの商品情報を取得します。商品の価格帯、販売数、売上（チャネル別）、コミッション率、発売日、レビュー数、カテゴリ階層、販売元ショップ、および関連する動画／ライブ配信／クリエイターの件数を返します。productId は通常、ランキングの応答フィールド product_id から取得します。

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

データフィールド

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

フィールド	説明
product_id	商品の一意の ID。詳細を取得する際に productId として渡します
product_name	商品名
unit_price	1点あたりの価格（通貨は地域に準拠。例：米国では USD）
sales_volumn	販売数量（フィールド名は volumn と綴られています）
revenue	総売上／GMV。動画＋ライブ配信＋ショーケースの各売上の合計です
video_revenue	動画チャネルからの売上
live_revenue	ライブ配信チャネルからの売上
showcase_revenue	ショーケース／橱窗チャネルからの売上
revenue_growth_rate	売上成長率（％）
commission_rate	コミッション率（パーセント値。25.0 は 25％）
launch_date	商品の発売日（YYYY-MM-DD）

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

フィールド	説明
product_region	商品の市場地域（例：us）
product_shop_id	この商品が属するショップの ID
pri_cate_id / sec_cate_id / ter_cate_id	第1／第2／第3カテゴリの ID
min_price / max_price	指定された通貨での最低価格／最高価格
product_review_count	商品レビュー数
delivery_type	配送タイプ（例：local）
video_number / live_number / creator_number	関連する動画／ライブ配信／クリエイターの件数
shopping_mall_revenue	ショッピングモール（商城）チャネルからの売上

詳細情報の売上チャネル内訳：revenue = video_revenue + live_revenue + shopping_mall_revenue。

パラメーターガイド

商品ランキング（/kalodata/product/rank）

パラメーター	型	必須	説明
region	string	いいえ	TikTok Shop の市場地域コード。例：US。指定がない場合のデフォルトは US です
dateRange	string	いいえ	相対的な期間。例：last7Day、last30Day
currency	string	いいえ	金額指標の通貨。例：USD
language	string	いいえ	レスポンスの言語。例：zh-CN、en-US
category_ids	array	いいえ	カテゴリー ID リストのフィルター
shop_id	string	いいえ	ショップ ID のフィルター
creator_id	string	いいえ	クリエイター ID のフィルター
video_id	string	いいえ	指定した動画に関連する商品を返します
livestream_id	string	いいえ	指定したライブ配信に関連する商品を返します
revenue_range	string	いいえ	売上／GMV 範囲のフィルター
is_affiliate	string	いいえ	アフィリエイトのフィルター：PUBLIC_PLAN または NON_AFFILIATE
commission_rate	number	いいえ	アフィリエイトのコミッション率。例：0.15
is_tts_product	integer	いいえ	フルマネージド商品のフィルター：1 または 0
unit_price_range	string	いいえ	商品の単価範囲のフィルター
sortField	object	いいえ	並べ替えの指定。デフォルトのランキングを使用する場合は省略します
pageNumber	integer	いいえ	ページ番号、1～5
pageSize	integer	いいえ	ページサイズ、5～100

商品詳細（/kalodata/product/detail）

パラメーター	型	必須	説明
productId	string	はい	ランキングの product_id フィールドにある TikTok 商品 ID（精度を維持するため文字列）
region	string	いいえ	市場地域コード。例：US
dateRange	string	いいえ	期間。例：last7Day、last30Day
language	string	いいえ	レスポンスの言語。例：zh-CN、en-US
currency	string	いいえ	金額指標の通貨。例：USD

呼び出し方法

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

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

• 常に完全なレスポンスを <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-kalodata-tiktok-product-<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. 米国の TikTok 人気商品を閲覧する（過去 7 日間）

{"region":"US","dateRange":"last7Day","pageSize":20,"pageNumber":1,"currency":"USD"}

2. ある商品の詳細を取得する

{"productId":"1729508370969629931","region":"US","dateRange":"last7Day","currency":"USD"}

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

Run kalodata_product_search.py first, choose a row's product_id, then pass that value as productId to kalodata_product_detail.py.

表示ルール

1. ランキング結果は、商品名、商品 ID、価格、販売数量、売上（チャネル別内訳）、成長率、コミッション率、発売日を含む表で表示してください。
2. 詳細結果は、識別情報、価格帯、販売数、売上（チャネル別内訳）、コミッション、カテゴリ階層、所有ショップ、関連する動画／ライブ配信／クリエイター数をまとめたプロフィールとして表示してください。
3. 金額指標を表示する際は、必ず dateRange、region、currency を明記してください。
4. 正確なフィールド名 sales_volumn を使用してください。
5. commission_rate は直接のパーセンテージ（25.0 = 25%）であり、ベーシスポイントではありません。% 記号を付けて表示してください。
6. revenue_growth_rate はパーセンテージです。% 記号を付けて表示してください。
7. 売上チャネルの内訳：ランキングの revenue = video_revenue + live_revenue + showcase_revenue、詳細の revenue = video_revenue + live_revenue + shopping_mall_revenue です。必要に応じて内訳を表示してください。
8. ユーザーが対応している sortField を明示的に指定しない限り、ランキング順を維持してください。

重要な制限事項

• ランキングはキーワード検索ではありません。地域と期間に基づいてランキングを閲覧します。
• 詳細の取得には productId が必要です。商品名だけでは商品を特定できません。まずランキングの product_id から productId を取得してください。
• ランキングのレスポンスには total やページ数は含まれません。結果数は data.length です。
• pageNumber は 1～5、pageSize は 5～100 に制限されています。
• 有効なリクエストでも結果が空の場合（例：未対応の region）は、errcode 200 が返され、data フィールドがないことがあります。その場合でも課金されます。
• 一時的な上流エラーは、Kalodata の HTTP 5xx メッセージ（例：522/554）を伴う errcode 501 として発生することがあります。同じパラメーターで 1～2 回再試行してください。パラメーターを自動的に変更しないでください。
• 商品以外のエンティティについては、該当する Kalodata の動画／クリエイター／ショップ／ライブ配信スキルを使用してください。

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

該当 -- TikTok の商品ランキングまたは商品詳細の検索：

ユーザーの表現	シナリオ
"TikTok商品榜单", "TikTok商品排行"	商品ランキングの検索
"TikTok热销榜", "TikTok爆品排行", "TikTok选品榜单"	売れ筋／人気商品のランキング
"kalodata商品榜", "kaloda排行"	データソースの直接指定
"TikTok商品详情", "TikTok商品资料"	単一商品の詳細検索
"商品价格", "商品销量"	商品価格／販売数
"kalodata product rank/detail", "product analytics"	商品詳細の直接指定

該当しない -- TikTok 商品の範囲を超えるもの：

• TikTok の動画／クリエイター／ショップ／ライブ配信のランキングまたは詳細
• キーワードによる商品検索
• Amazon／Shopify／1688 の商品リサーチ（プラットフォーム固有のスキルを使用してください）
• TikTok 広告／広告キャンペーンの管理またはコンテンツ作成

計算リソース消費ルール

呼び出し 1 回につき、計算リソースを 7.0 消費します。

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

フィードバック：

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

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

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

---

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