linkfox-kalodata-tiktok-product

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Kalodata - TikTok Product Search & Detail

Kalodata - TikTok商品搜索与详情

This skill supports a two-step TikTok Shop product workflow via the Kalodata data source:

Browse TikTok Shop product leaderboards to discover top-ranked and best-selling products.
Fetch one product's full detail by
```
productId
```
.

Use the ranking endpoint when the user wants best-seller rankings, hot products, or product discovery. Use the detail endpoint when the user already has a

productId

or has selected one product from a ranking result.

本技能通过Kalodata数据源支持TikTok Shop商品查询的两步流程：

浏览TikTok Shop商品排行榜，发现高排名及热销商品。
通过
```
productId
```
获取单个商品的完整详情。

当用户需要畅销榜、热门商品或商品选品时，使用排行榜接口；当用户已有

productId

或从排行榜结果中选中某款商品时，使用详情接口。

Core Concepts

核心概念

The product ranking endpoint returns a paginated leaderboard filtered by

region

dateRange

currency

language

, and optional

sortField

. Each product row includes identity, price, sales volume, revenue (split across video, live, and showcase channels), revenue growth rate, commission rate, and launch date. Results are paginated with

pageNumber

(1-5) and

pageSize

(5-100).

The product detail endpoint fetches one TikTok Shop product by

productId

. It returns the product's price range, sales, revenue (with channel split), commission rate, launch date, review count, category hierarchy, owning shop, and associated video/live/creator counts. The

productId

usually comes from the ranking response field

product_id

Both endpoints may reflect a statistical delay (T+1). See

references/api.md

for full request and response details.

商品排行榜接口返回分页的排行榜数据，可按

region

、

dateRange

、

currency

、

language

及可选的

sortField

进行筛选。每条商品数据包含商品标识、价格、销量、销售额（拆分自视频、直播、橱窗渠道）、销售额增长率、佣金率及上架日期。结果通过

pageNumber

（1-5）和

pageSize

（5-100）分页展示。

商品详情接口通过

productId

获取单个TikTok Shop商品的数据。返回内容包括商品的价格区间、销量、销售额（含渠道拆分）、佣金率、上架日期、评论数、分类层级、所属店铺，以及关联的视频/直播/创作者数量。

productId

通常来自排行榜响应中的

product_id

字段。

两个接口的数据可能存在统计延迟（T+1）。完整的请求和响应详情请参考

references/api.md

。

Data Fields

数据字段

Ranking rows include:

Field	Description
product_id	Product unique ID; pass this as `productId` for detail lookup
product_name	Product title
unit_price	Price per unit (currency follows region, e.g. USD for US)
sales_volumn	Units sold (field is spelled `volumn` )
revenue	Total revenue / GMV; equals video + live + showcase revenue
video_revenue	Revenue from the video channel
live_revenue	Revenue from the live-stream channel
showcase_revenue	Revenue from the showcase / 橱窗 channel
revenue_growth_rate	Revenue growth rate (%)
commission_rate	Commission rate as a direct percentage (25.0 = 25%)
launch_date	Product launch date (YYYY-MM-DD)

Detail rows additionally include:

Field	Description
product_region	Product market region (e.g. `us` )
product_shop_id	ID of the shop this product belongs to
pri_cate_id / sec_cate_id / ter_cate_id	Primary / secondary / tertiary category IDs
min_price / max_price	Minimum / maximum price in the requested currency
product_review_count	Number of product reviews
delivery_type	Delivery type (e.g. `local` )
video_number / live_number / creator_number	Associated video / live / creator counts
shopping_mall_revenue	Revenue from the shopping mall (商城) channel

Detail revenue channel split:
revenue
=
video_revenue
+
live_revenue
+
shopping_mall_revenue
.

排行榜数据包含：

字段	描述
product_id	商品唯一ID；查询详情时需将此作为 `productId` 传入
product_name	商品标题
unit_price	单价（货币类型随地区而定，例如美国地区为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	一级/二级/三级分类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
。

Parameter Guide

参数指南

Product ranking (
/kalodata/product/rank
)

Parameter	Type	Required	Description
region	string	No	TikTok Shop market region code, e.g. `US` . Default `US` when unspecified
dateRange	string	No	Relative time window, e.g. `last7Day` , `last30Day`
currency	string	No	Currency for monetary metrics, e.g. `USD`
language	string	No	Response language, e.g. `zh-CN` , `en-US`
sortField	object	No	Sorting specification; omit for default ranking
pageNumber	integer	No	Page number, 1-5
pageSize	integer	No	Page size, 5-100

Product detail (
/kalodata/product/detail
)

Parameter	Type	Required	Description
productId	string	Yes	TikTok product ID from ranking field `product_id` (string to preserve precision)
region	string	No	Market region code, e.g. `US`
dateRange	string	No	Time window, e.g. `last7Day` , `last30Day`
language	string	No	Response language, e.g. `zh-CN` , `en-US`
currency	string	No	Currency for monetary metrics, e.g. `USD`

商品排行榜（
/kalodata/product/rank
）

参数	类型	是否必填	描述
region	string	否	TikTok Shop市场区域代码，例如 `US` 。未指定时默认值为 `US`
dateRange	string	否	相对时间范围，例如 `last7Day` 、 `last30Day`
currency	string	否	货币类型，用于金额指标，例如 `USD`
language	string	否	响应语言，例如 `zh-CN` 、 `en-US`
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]

成本约束：本工具会消耗积分；同一会话同一参数组合默认只调用一次，脚本带 24h 本地缓存。失败/空结果不得自动换关键词、翻页或改邮编连续试探；需要继续检索时先向用户说明会产生额外消耗。

输出策略（脚本默认行为）：

始终将完整响应写入
```
<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（同样落盘）

读数据建议：先看摘要判断是否足够；需要具体字段时优先用

jq

或

ConvertFrom-Json

从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。

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]

成本约束：本工具会消耗积分；同一会话中同一参数组合默认仅调用一次，脚本带有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
```
参数可强制将全量内容打印到标准输出（同样会写入文件）

读数据建议：先查看摘要判断信息是否足够；如需具体字段，优先使用

jq

或

ConvertFrom-Json

从保存的JSON文件中按需抽取，避免将整份JSON带入上下文。

解决认证和积分问题

发生以下异常情况时，采用 references/onboarding.md 引导解决问题：

出现以下异常情况时，参考

references/onboarding.md

引导用户解决：

异常情况

未配置API Key：环境变量未配置
```
LINKFOX_AGENT_API_KEY
```
，也未配置
```
LINKFOXAGENT_API_KEY
```
。
响应401或402状态码
响应提示积分或余额不足：消息含"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值"，或类似含义的内容。

未配置API Key：环境变量未配置
```
LINKFOX_AGENT_API_KEY
```
，也未配置
```
LINKFOXAGENT_API_KEY
```
。
响应401或402状态码
响应提示积分或余额不足：消息包含“积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值”或类似含义的内容。

Usage Examples

使用示例

1. Browse top TikTok products in the US (last 7 days)

json

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

2. Fetch one product's detail

json

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

3. Discovery-to-detail workflow

text

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

1. 浏览美国地区近7天的TikTok热门商品

json

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

2. 获取单个商品的详情

json

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

3. 从排行榜到详情的完整流程

text

先运行kalodata_product_search.py，选择某条数据的product_id，然后将该值作为productId传入kalodata_product_detail.py。

Display Rules

显示规则

Present ranking results in a table with product name, product ID, price, sales volume, revenue (with channel split), growth rate, commission rate, and launch date.
Present detail results as one grouped profile: identity, price range, sales, revenue (channel split), commission, category hierarchy, owning shop, and associated video/live/creator counts.
Always label
```
dateRange
```
,
```
region
```
, and
```
currency
```
when showing monetary metrics.
Use the exact field name
```
sales_volumn
```
.
```
commission_rate
```
is a direct percentage (25.0 = 25%), not basis points — show with a % sign.
```
revenue_growth_rate
```
is a percentage — show with a % sign.

Revenue channel split: ranking

revenue

video_revenue

live_revenue

showcase_revenue

; detail

revenue

video_revenue

live_revenue

shopping_mall_revenue

. Present the split when useful.

Preserve ranking order unless the user explicitly requests a supported
```
sortField
```
.

排行榜结果以表格形式展示，包含商品名称、商品ID、价格、销量、销售额（含渠道拆分）、增长率、佣金率及上架日期。
详情结果以分组档案形式展示：商品标识、价格区间、销量、销售额（渠道拆分）、佣金率、分类层级、所属店铺，以及关联的视频/直播/创作者数量。
展示金额指标时，必须标注
```
dateRange
```
、
```
region
```
和
```
currency
```
。
使用准确的字段名
```
sales_volumn
```
。
```
commission_rate
```
为直接百分比（25.0即25%），而非基点——需显示%符号。
```
revenue_growth_rate
```
为百分比——需显示%符号。

销售额渠道拆分：排行榜中

revenue

video_revenue

live_revenue

showcase_revenue

；详情中

revenue

video_revenue

live_revenue

shopping_mall_revenue

。必要时展示拆分数据。

除非用户明确要求使用支持的
```
sortField
```
排序，否则保留排行榜的原始顺序。

Important Limitations

重要限制

Ranking is not keyword search; it browses leaderboards by region and time window.
Detail requires
```
productId
```
; it cannot find a product by name alone. Obtain
```
productId
```
from the ranking
```
product_id
```
first.
The ranking response does not include
```
total
```
or page count; result count is
```
data.length
```
.
```
pageNumber
```
is limited to 1-5 and
```
pageSize
```
is limited to 5-100.
A valid-but-empty request (e.g. an unsupported
```
region
```
) may return
```
errcode 200
```
with no
```
data
```
field and still be billed.
Transient upstream errors may appear as
```
errcode 501
```
with a Kalodata HTTP 5xx message (e.g. 522/554). Retry the same parameters once or twice; do not change parameters automatically.
Use the matching Kalodata video/creator/shop/livestream skills for non-product entities.

排行榜不支持关键词搜索；仅可按地区和时间范围浏览榜单。
查询详情需要
```
productId
```
；无法仅通过商品名称查找商品。需先从排行榜的
```
product_id
```
获取
```
productId
```
。
排行榜响应不包含
```
total
```
或总页数；结果数量为
```
data.length
```
。
```
pageNumber
```
限制为1-5，
```
pageSize
```
限制为5-100。
格式有效但内容无效的请求（例如不支持的
```
region
```
）可能返回
```
errcode 200
```
且无
```
data
```
字段，但仍会产生计费。
上游临时错误可能表现为
```
errcode 501
```
及Kalodata HTTP 5xx消息（例如522/554）。可重试相同参数1-2次；不得自动修改参数。
如需查询非商品实体数据（视频/创作者/店铺/直播），请使用对应的Kalodata技能。

User Expression & Scenario Quick Reference

用户表达与场景速查

Applicable -- TikTok product ranking or product detail lookup:

User Says	Scenario
"TikTok商品榜单", "TikTok商品排行"	Product ranking lookup
"TikTok热销榜", "TikTok爆品排行", "TikTok选品榜单"	Best-seller / hot product ranking
"kalodata商品榜", "kaloda排行"	Direct data source reference
"TikTok商品详情", "TikTok商品资料"	Single product detail lookup
"商品价格", "商品销量"	Product price / sales
"kalodata product rank/detail", "product analytics"	Direct product detail reference

Not applicable -- Needs beyond TikTok products:

TikTok video / creator / shop / livestream rankings or details
Keyword-based product search
Amazon / Shopify / 1688 product research (use the platform-specific skills)
TikTok advertising / ad campaign management or content creation

适用场景——TikTok商品排行榜或商品详情查询：

用户表述	场景
"TikTok商品榜单"、"TikTok商品排行"	商品排行榜查询
"TikTok热销榜"、"TikTok爆品排行"、"TikTok选品榜单"	畅销/热门商品排行榜查询
"Kalodata商品榜"、"Kaloda排行"	直接引用数据源查询
"TikTok商品详情"、"TikTok商品资料"	单个商品详情查询
"商品价格"、"商品销量"	商品价格/销量查询
"Kalodata product rank/detail"、"product analytics"	直接查询商品详情

不适用场景——超出TikTok商品范围的需求：

TikTok视频/创作者/店铺/直播的排行榜或详情查询
基于关键词的商品搜索
Amazon/Shopify/1688平台的商品调研（请使用对应平台的专属技能）
TikTok广告/广告活动管理或内容创作

积分消耗规则

每次调用消耗 7.0 积分。

用户会因积分消耗而支付费用。请充分评估：当需要高频调用本技能，或用户对积分消耗量预期不足时，务必提醒用户，由用户决定是否继续。

Feedback:

Auto-detect and report feedback via the Feedback API when any of the following apply:

The functionality or purpose described in this skill does not match actual behavior
The skill's results do not match the user's intent
The user expresses dissatisfaction or praise about this skill
Anything you believe could be improved

Call the feedback API as specified in

references/api.md

. Do not interrupt the user's flow.

For more high-quality, professional cross-border e-commerce skills, visit LinkFox Skills.

每次调用消耗7.0积分。

用户会因积分消耗产生费用。请充分评估：当需要高频调用本技能，或用户对积分消耗量预期不足时，务必提醒用户，由用户决定是否继续。

反馈：

当出现以下任意情况时，通过反馈API自动检测并提交反馈：

本技能描述的功能或用途与实际行为不符
技能结果与用户意图不符
用户表达对本技能的不满或赞扬
任何你认为可以改进的内容

请按照

references/api.md

中的说明调用反馈API，不要中断用户的操作流程。

如需更多高质量的专业跨境电商技能，请访问LinkFox Skills。