SKILL.md
KaloData TikTok Shop analytics (kalo)
TikTok Shop e-commerce analytics from KaloData — rankings and details for products, shops, creators, videos, livestreams and categories.
Run
The CLI ships inside this skill (scripts/kalo.py, Python 3.11+ stdlib only — nothing to install):
python3 <this-skill-dir>/scripts/kalo.py product rank --region USAll examples below write kalo as shorthand for python3 <this-skill-dir>/scripts/kalo.py.
Output is TOON (token-oriented) on stdout; add --json to any command for raw JSON. Errors are structured on stdout with actionable help: lines. Exit codes: 0 ok, 1 error, 2 usage.
Setup — check this before the first query
Every command needs a KaloData API key (sent as the secret-key header). Before the first query of a session run kalo config and look at api_key. If it says missing, stop — don't guess a key and don't retry the query. Walk the user through these three steps and wait:
- Get a key — sign in at https://www.kalodata.com/open-center/account and click
generate key. No account yet? Register at https://www.kalodata.com/open-center/home first. If they already call the KaloData API on credit-based billing, that same key works here — no new key needed.
- Save it —
kalo config set --key <API_KEY>(stored in~/.config/kalodata/config.toml,
mode 0600), or set KALODATAAPIKEY in the environment.
- Credits — every query spends KaloData credits: 0.2–0.4 for a basic lookup, 1–2 for an
analysis/diagnosis playbook. Check the balance and top up at https://www.kalodata.com/pricing.
Once the key is set, mention the credit cost when a request would fan out into many calls (a playbook, or dozens of detail lookups), so the spend isn't a surprise.
Commands
| command | what | ||
|---|---|---|---|
kalo product rank |
top products; --category --keyword --price --launch --shop --creator | ||
kalo product detail <id...> |
price range, shop id, revenue trend | ||
kalo shop rank |
top shops; --type BRAND\ | RETAILER --keyword | |
kalo shop detail <id...> |
revenue split, top product ids | ||
kalo creator rank |
top creators; --followers --engagement --product | ||
| `kalo creator detail <id\ | @handle...>` | contact email/handle, GPM, trend; handle match is fuzzy — verify the returned creator_handle | |
kalo creator images <id...> |
avatar URLs for a batch of creator ids | ||
kalo video rank |
top shoppable videos; --product --creator --keyword --ai | ||
kalo video detail <id...> |
full video metrics + trend | ||
kalo live rank |
top livestreams; --keyword | ||
kalo live detail <id...> |
viewers, GPM, top product ids | ||
kalo category rank |
top categories; --level 1\ | 2\ | 3 |
kalo category detail <id...> |
category revenue split + trend | ||
kalo category search <kw> |
resolve category ids by keyword | ||
kalo config |
show/set credentials and defaults |
Conventions
- All list commands take --region --range --page (1-5) --limit (5-100) --sort --asc --fields --json
- Regions: US GB ID TH VN PH MY SG JP MX DE IT FR ES BR; ranges like last7Day, last30Day, yyyy-MM, or yyyy-MM-dd~yyyy-MM-dd
- Numeric ranges are "min-max" with both ends numeric, e.g. --revenue 1000-50000
- Add --images on product/shop/creator rank or product detail to include image URLs
- Run
kalo <command> --helpfor per-command flags and examples
Typical flows
- Trending research:
kalo product rank --region US --range last7Day→kalo product detail <id>→kalo video rank --product <id> - Creator scouting:
kalo creator rank --category <id> --followers 10000-1000000→kalo creator detail <id>(has contact email) - Category drilldown:
kalo category search "beauty"→kalo category detail <id>→kalo shop rank --category <id>
Playbooks
For complex analysis — product/creator diagnosis, category sourcing research, creator recommendation, viral-video methodology, shot-by-shot script writing — read [references/playbooks.md](references/playbooks.md) first and follow its mandatory steps (always benchmark against same-category / same-price-band / same-follower-tier peers before drawing conclusions).