Kalodata-tiktok e‑commerce data query

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 /scripts/kalo.py product rank --region US

All examples below write kalo as shorthand for python3 /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:

1. 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.
2. Save it — kalo config set --key (stored in ~/.config/kalodata/config.toml, mode 0600), or set KALODATA_API_KEY in the environment.
3. 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

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 --help for per-command flags and examples

Typical flows

• Trending research: kalo product rank --region US --range last7Day → kalo product detail → kalo video rank --product
• Creator scouting: kalo creator rank --category --followers 10000-1000000 → kalo creator detail (has contact email)
• Category drilldown: kalo category search "beauty" → kalo category detail → kalo shop rank --category

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).