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 US

All 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 KALODATA_API_KEY in the environment.
Credits — every query spends KaloData credits: 0.2–0.4 for a basic lookup, 1–2 for an analysis/diagnosis playbook. kalo credit shows the remaining quota; 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 credit | remaining API credit quota per endpoint group | | 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> --help for 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 first and follow its mandatory steps (always benchmark against same-category / same-price-band / same-follower-tier peers before drawing conclusions).