linkfox-kalodata-tiktok-shop

Kalodata - TikTok Shop Search & Detail

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

1. Browse TikTok Shop store (店铺) leaderboards to discover high-performing stores.
2. 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.

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.

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.

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
category_ids	array	No	Category ID list filter
revenue_range	string	No	Revenue / GMV range filter
shop_type	string	No	Shop type filter: BRAND or RETAILER
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
category_id	string	No	Optional category ID dimension
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

How to call

• API endpoint：POST /kalodata/shop/rank or POST /kalodata/shop/detail(for full parameters/responses/error codes see references/api.md）
• Python script：python scripts/kalodata_shop_search.py '<JSON 参数>' [--inline] or python scripts/kalodata_shop_detail.py '<JSON 参数>' [--inline]
• Cost constraints: This tool consumes compute credits; within the same session, the same parameter combination is called only once by default, and the script has a 24h local cache. On failure/empty results, do not automatically change keywords, page through, or change the postal code to probe continuously; if you need to continue searching, first explain to the user that it will incur additional consumption.

Output strategy (default script behavior)：

• AlwaysWrite the full response to <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-kalodata-tiktok-shop-<timestamp>.json（<cwd> is the working directory when the script runs, which in Claude Code is the current project directory;<session> is taken from the environment variable SESSION_ID, automatically aggregated according to the user's task;Writing to /tmp is prohibited; if the current directory is not writable, report an error)
• Response body <= 8 KB: after saving to disk, print the full JSON to stdout
• Response body > 8 KB: after saving to disk, stdout outputs only a summary (top-level fields, common counts such as total/costToken, the length of the largest list field + first 3 samples)
• Add --inline to force full printing to stdout (also saved to disk)

Data reading suggestions: First look at the summary to judge whether it is sufficient; when specific fields are needed, prefer jq or ConvertFrom-Json to extract as needed from the saved json file, avoiding putting the entire JSON into context.

Resolve authentication and compute issues

When the following abnormal situations occur, use references/onboarding.md to guide problem resolution:

Abnormal situations

• API Key not configured: the environment variable is not configured LINKFOX_AGENT_API_KEY, and LINKFOXAGENT_API_KEY。
• Response is 401 or 402 status code
• Response indicates insufficient compute or balance: the message contains "insufficient compute balance/insufficient billing/insufficient balance/quota exceeded/insufficient balance/package expired/recharge required/please recharge", or content with similar meaning.

Usage Examples

1. Top TikTok shops in the US over the last 7 days

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

2. Fetch one shop's detail

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

3. Discovery-to-detail workflow

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

Display Rules

1. Present ranking results in a table with rank, shop name, shop type, revenue, sales volume, product count, unit price, and growth rate.
2. Present detail results as one grouped profile: identity, scale, revenue channel split, and creator/video/live counts.
3. Always label dateRange, region, and currency when showing metrics.
4. Revenue channel breakdown is approximate (see Data Fields note); present the split as a breakdown, not an exact equality.
5. 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.
6. Show creator_number, video_number, live_number, product_number as plain integer counts.
7. Preserve ranking order unless the user explicitly requests a supported 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.

User Expression & Scenario Quick Reference

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

User Says	Scenario
"TikTok store leaderboard", "TikTok small shop ranking"	Store ranking lookup
"TikTok hot-selling stores", "top TikTok shops"	Store leaderboard by region
"last 7 days TikTok store leaderboard", "US TikTok store ranking"	Time-windowed / region-filtered ranking
"TikTok store details", "TikTok small shop profile"	Single-store detail lookup
"store sales revenue", "store sales volume", "number of store creator collaborations"	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

Compute consumption rules

Each call consumes 7.0 compute power.

Users will be charged due to compute power consumption. Please fully assess: when this skill needs to be called frequently, or when the user has insufficient expectations for the amount of compute power consumed, be sure to remind the user, and let the user decide whether to continue.

Feedback:

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

1. The functionality or purpose described in this skill does not match actual behavior
2. The skill's results do not match the user's intent
3. The user expresses dissatisfaction or praise about this skill
4. 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.