linkfox-kalodata-tiktok-shop

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Kalodata - TikTok Shop Search & Detail

Kalodata - TikTok Shop 搜索与详情

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

Browse TikTok Shop store (店铺) leaderboards to discover high-performing stores.
Fetch one store's full detail by
```
shopId
```
.

Use the search (ranking) endpoint when the user wants rankings, store discovery, or store comparison. Use the detail endpoint when the user already has a

shopId

or has selected one store from a ranking result.

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

浏览TikTok Shop店铺排行榜，发掘高表现店铺。
通过
```
shopId
```
获取单个店铺的完整详情。

当用户需要排行榜、店铺发掘或店铺对比时，使用搜索（排行）端点；当用户已有

shopId

或从排行结果中选定某一店铺时，使用详情端点。

Core Concepts

核心概念

The shop ranking endpoint returns a paginated leaderboard filtered by

region

dateRange

language

, and

currency

. The default ranking order is by

revenue

(GMV) descending, and each row carries an explicit

rank

position. Each shop row includes identity, scale, revenue channel split, and growth.

The shop detail endpoint fetches one store by

shopId

. It returns the store's identity, scale, revenue channel split, and creator/video/live counts. The

shopId

usually comes from the ranking response field

shop_id

⚠️ Field names differ between the shop RANK and shop DETAIL endpoints. Detail uses
self_account_revenue
(rank uses
self_promotion_revenue
),
shoppingmall_revenue
with no internal underscore (rank uses
shopping_mall_revenue
), and
seller_type
(rank uses
shop_type
). Detail returns
creator_number
/
video_number
/
live_number
/
product_number
(rank does not), and does not return
rank
/
revenue_growth_rate
/
on_sell_product_count
. Always use the exact endpoint field names.

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

references/api.md

for full request and response details.

店铺排行端点返回经过

region

（地区）、

dateRange

（日期范围）、

language

（语言）和

currency

（货币）过滤的分页排行榜。默认按

revenue

（GMV，商品交易总额）降序排列，每一行都包含明确的

rank

（排名）位置。每条店铺数据包含身份信息、规模、收入渠道拆分及增长情况。

店铺详情端点通过

shopId

获取单个店铺的数据，返回店铺的身份信息、规模、收入渠道拆分，以及创作者/视频/直播数量。

shopId

通常来自排行响应结果中的

shop_id

字段。

⚠️ 店铺排行端点与店铺详情端点的字段名称存在差异：详情端点使用
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

。

Data Fields

数据字段

Ranking rows include:

Field	Description
rank	Rank position (1 = top by revenue)
shop_name	Shop display name
shop_id	Shop unique ID; pass this as `shopId` for detail lookup
shop_type	Shop type (e.g. `BRAND` )
revenue	Total GMV in the requested currency
sales_volumn	Sales volume; field is spelled `volumn`
on_sell_product_count	Number of products currently on sale
unit_price	Average unit price in the requested currency
revenue_growth_rate	Revenue growth rate (%), can be negative
self_promotion_revenue	Revenue from self-promotion (店铺自营/自播自推)
affiliate_revenue	Revenue from affiliate (达人分销)
shopping_mall_revenue	Revenue from the shopping mall (商城)

Detail rows include:

Field	Description
shop_id	Shop unique ID (string to preserve precision)
shop_name	Shop display name
seller_type	Seller/shop type (e.g. `BRAND` ) — note: `seller_type` , not `shop_type`
region	Market region (e.g. `US` )
revenue	Total revenue / GMV in the requested currency
sales_volumn	Sales volume; field is spelled `volumn`
product_number	Number of products on sale
unit_price	Average unit price in the requested currency
self_account_revenue	Revenue from self-account (店铺自营/自播自推) — note: `self_account_revenue` , not `self_promotion_revenue`
affiliate_revenue	Revenue from affiliate (达人分销)
shoppingmall_revenue	Revenue from the shopping mall (商城) — note: NO underscore between `shopping` and `mall`
creator_number	Number of creators cooperating with the shop (达人合作数)
video_number	Number of related videos
live_number	Number of related livestreams

Revenue channel split: on the rank endpoint
revenue
=
self_promotion_revenue
+
affiliate_revenue
+
shopping_mall_revenue
; on the detail endpoint
revenue
≈
self_account_revenue
+
affiliate_revenue
+
shoppingmall_revenue
. Components may round independently of
revenue
(e.g.
shoppingmall_revenue
returns
10431.0
on detail vs
10431.39
on rank), so treat the split as approximate, not an exact equality.

排行数据行包含：

Field	Description
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	商城渠道收入

详情数据行包含：

Field	Description
shop_id	店铺唯一ID（字符串类型以保留精度）
shop_name	店铺显示名称
seller_type	卖家/店铺类型（例如 `BRAND` ）——注意：是 `seller_type` 而非 `shop_type`
region	市场地区（例如 `US` ）
revenue	请求货币对应的总收入/GMV
sales_volumn	销量；注意字段拼写为 `volumn`
product_number	在售商品数量
unit_price	请求货币对应的平均单价
self_account_revenue	自营/自播自推渠道收入——注意：是 `self_account_revenue` 而非 `self_promotion_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
），因此拆分结果为近似值，并非精确相等。

Parameter Guide

参数指南

Shop ranking (
/kalodata/shop/rank
)

Parameter	Type	Required	Description
region	string	No	Market region code, e.g. `US`
dateRange	string	No	Time window, e.g. `last7Day` , `last30Day`
pageNumber	integer	No	Page number, 1-5
pageSize	integer	No	Page size, 5-100
language	string	No	Response language, e.g. `zh-CN` , `en-US`
currency	string	No	Currency for monetary metrics, e.g. `USD`
sortField	object	No	Sorting specification; pass `{}` for default revenue ranking

Shop detail (
/kalodata/shop/detail
)

Parameter	Type	Required	Description
shopId	string	Yes	Shop unique ID from ranking field `shop_id`
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/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`
sortField	object	否	排序规则；传入 `{}` 则使用默认的收入排序

店铺详情（
/kalodata/shop/detail
）

参数	类型	是否必填	描述
shopId	string	是	排行结果中 `shop_id` 字段对应的店铺唯一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]

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

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

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

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

jq

或

ConvertFrom-Json

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

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
```
参数可强制将全量内容打印到标准输出（同时仍会写入文件）

读数据建议：先查看摘要判断是否满足需求；如需提取具体字段，优先使用

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. Top TikTok shops in the US over the last 7 days

json

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

2. Fetch one shop's detail

json

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

3. Discovery-to-detail workflow

text

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

1. 过去7天美国地区的顶级TikTok店铺

json

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

2. 获取单个店铺的详情

json

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

3. 从发掘到详情的完整流程

text

先运行kalodata_shop_search.py，选择某一行的shop_id，再将该值作为shopId传入kalodata_shop_detail.py。

Display Rules

展示规则

Present ranking results in a table with rank, shop name, shop type, revenue, sales volume, product count, unit price, and growth rate.
Present detail results as one grouped profile: identity, scale, revenue channel split, and creator/video/live counts.
Always label
```
dateRange
```
,
```
region
```
, and
```
currency
```
when showing metrics.
Revenue channel breakdown is approximate (see Data Fields note); present the split as a breakdown, not an exact equality.
Use the exact field name
```
sales_volumn
```
. On detail use
```
shoppingmall_revenue
```
(no underscore) and
```
self_account_revenue
```
; on rank use
```
shopping_mall_revenue
```
and
```
self_promotion_revenue
```
. Do not mix the two endpoints' field names.

Show

creator_number

video_number

live_number

product_number

as plain integer counts.

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

排行结果以表格形式展示，包含排名、店铺名称、店铺类型、收入、销量、商品数量、单价及增长率。
详情结果以分组档案形式展示：身份信息、规模、收入渠道拆分、创作者/视频/直播数量。
展示指标时需标注
```
dateRange
```
、
```
region
```
和
```
currency
```
信息。
收入渠道拆分结果为近似值（见数据字段说明）；展示时需说明为拆分结果，而非精确相等。
使用准确的字段名
```
sales_volumn
```
。详情端点使用
```
shoppingmall_revenue
```
（无下划线）和
```
self_account_revenue
```
；排行端点使用
```
shopping_mall_revenue
```
和
```
self_promotion_revenue
```
。请勿混淆两个端点的字段名。

creator_number

、

video_number

、

live_number

、

product_number

以纯整数形式展示。

除非用户明确请求支持的
```
sortField
```
排序规则，否则保持排行顺序不变。

Important Limitations

重要限制

Ranking is not keyword search; it browses leaderboards by region and time window.
Detail requires
```
shopId
```
; it cannot find a shop by name alone. Obtain
```
shopId
```
from the ranking
```
shop_id
```
field or the user.
The ranking response does not include total/page count; paginate until a page returns fewer than
```
pageSize
```
items.
```
pageNumber
```
is limited to 1-5 and
```
pageSize
```
is limited to 5-100.
Detail has no pagination;
```
data
```
is a 1-element array for a single shop, with no
```
total
```
.
Field names differ between the rank and detail endpoints (see Data Fields) — use the exact names when extracting.
Transient upstream errors may appear as
```
errcode 501
```
with a Kalodata HTTP 554 message. Retry the same parameters once or twice; do not change parameters automatically.
Use the matching Kalodata product/video/creator/livestream skills for non-shop entities.

排行功能不支持关键词搜索；仅支持按地区和时间范围浏览排行榜。
详情查询需要
```
shopId
```
；无法仅通过店铺名称查询详情。
```
shopId
```
需来自排行结果的
```
shop_id
```
字段或由用户提供。
排行响应结果不包含总条数/总页数；需分页直到某一页返回的结果数量少于
```
pageSize
```
。
```
pageNumber
```
限制为1-5，
```
pageSize
```
限制为5-100。
详情查询无分页；
```
data
```
为包含单个店铺数据的1元素数组，无
```
total
```
字段。
排行端点与详情端点的字段名称存在差异（见数据字段说明）——提取数据时请使用准确的字段名。
临时上游错误可能表现为
```
errcode 501
```
及Kalodata HTTP 554消息。可重试相同参数1-2次；请勿自动修改参数。
如需查询非店铺实体（创作者/商品/视频/直播），请使用对应的Kalodata技能。

User Expression & Scenario Quick Reference

用户表述与场景速查

Applicable -- TikTok Shop store ranking or single-store detail:

User Says	Scenario
"TikTok店铺排行榜", "TikTok小店排行"	Store ranking lookup
"TikTok热销店铺", "top TikTok shops"	Store leaderboard by region
"近7天TikTok店铺榜", "美国TikTok店铺排名"	Time-windowed / region-filtered ranking
"TikTok店铺详情", "TikTok小店资料"	Single-store detail lookup
"店铺销售额", "店铺销量", "店铺达人合作数"	Store revenue / sales / creator count
"kalodata shop search/detail"	Direct data source reference

Not applicable -- Needs beyond TikTok Shop stores:

TikTok creator/product/video/livestream rankings or details
Amazon / Shopify / 1688 / other platforms' store data
TikTok ad campaign management or content creation

适用场景——TikTok Shop店铺排行或单店详情查询：

用户表述	场景
"TikTok店铺排行榜"、"TikTok小店排行"	店铺排行查询
"TikTok热销店铺"、"top TikTok shops"	按地区筛选的店铺排行榜
"近7天TikTok店铺榜"、"美国TikTok店铺排名"	按时间范围/地区筛选的排行查询
"TikTok店铺详情"、"TikTok小店资料"	单店详情查询
"店铺销售额"、"店铺销量"、"店铺达人合作数"	店铺收入/销量/创作者数量查询
"kalodata shop search/detail"	直接引用数据源的查询

不适用场景——超出TikTok Shop店铺范畴的需求：

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。