keyapi-tiktok-ecommerce

Comprehensive TikTok Shop market intelligence — analyze products, shops, categories, pricing, GMV, reviews, and competitive dynamics across the entire e-commerce ecosystem.

This skill provides deep market intelligence on TikTok Shop using the KeyAPI MCP service. It covers the full e-commerce data spectrum: individual product analytics, shop-level performance, category hierarchy navigation, creator-driven sales attribution, and live-stream commerce data — all backed by large-scale historical datasets.

Use this skill when you need to:

• Research product opportunities by analyzing sales trends, GMV, pricing, and competition
• Evaluate specific products or shops with comprehensive performance metrics
• Understand TikTok Shop category structures and identify high-growth niches
• Analyze customer reviews and sentiment for product intelligence
• Identify top shops and products in a category for competitive benchmarking
• Attribute sales to specific creators or live-stream events

author: KeyAPI license: MIT repository: https://github.com/EchoSell/keyapi-skills

Prerequisites

author: KeyAPI license: MIT repository: https://github.com/EchoSell/keyapi-skills

MCP Server Configuration

All tool calls in this skill target the KeyAPI MCP server:

Server URL : https://mcp.keyapi.ai
Auth Header: Authorization: Bearer $KEYAPI_TOKEN

Setup (one-time):

# 1. Install dependencies
npm install

# 2. Set your API token (get one free at https://keyapi.ai/)
export KEYAPI_TOKEN=your_token_here

# 3. List all available tools to verify the connection
node scripts/run.js --list-tools

author: KeyAPI license: MIT repository: https://github.com/EchoSell/keyapi-skills

Analysis Scenarios

Product Nodes

Shop Nodes

Category Nodes

author: KeyAPI license: MIT repository: https://github.com/EchoSell/keyapi-skills

Workflow

Step 1 — Identify the Research Objective and Select Nodes

Clarify the user's goal and identify the appropriate entry point and supporting nodes.

Common entry points:

• User provides a product share link → Start with get_product_id_from_share_link to resolve product_id.
• User provides a product name or keyword → Use product_list_analytics to discover matching products.
• User asks about a category → Resolve the full category hierarchy first (see Step 1a below).
• User provides a shop name or ID → Use shop_list_analytics or shop_detail_analytics.
• Competitive market analysis → Combine product_ranking_analytics + shop_ranking_analytics + category filters.

Step 1a — Resolve Category IDs

⚠️ When the user asks about a product category or wants to filter by category, always resolve the full category hierarchy first:

1. Call primary_categories_analytics → obtain category_id (L1)
2. Call secondary_categories_analytics with category_id → obtain category_l2_id (L2)
3. Call tertiary_categories_analytics with category_l2_id → obtain category_l3_id (L3)

Use the appropriate level of category ID as a filter in subsequent product or shop queries.

Step 2 — Retrieve API Schema

Before calling any node, inspect its input schema to confirm required parameters and valid values:

node scripts/run.js --schema \x3Ctool_name>

# Examples
node scripts/run.js --schema product_list_analytics
node scripts/run.js --schema get_product_id_from_share_link

For analytics nodes, pay particular attention to filter parameters such as category_id, category_l2_id, category_l3_id, region, min_spu_avg_price, max_spu_avg_price, product_sort_field, sort_type, and page_num/page_size.

Step 3 — Call APIs and Cache Results Locally

Execute the required tool calls and persist all responses to the local cache.

Calling a tool (using scripts/run.js):

# Single page call — result is cached automatically
node scripts/run.js --tool \x3Ctool_name> --params '\x3Cjson_args>' --pretty

# Fetch all pages at once (auto-pagination)
node scripts/run.js --tool \x3Ctool_name> --params '\x3Cjson_args>' --all-pages --page-size 50

# Force a fresh call, skip cache
node scripts/run.js --tool \x3Ctool_name> --params '\x3Cjson_args>' --no-cache

Example — resolve product_id from share link:

node scripts/run.js --tool get_product_id_from_share_link \
  --params '{"share_url":"https://www.tiktok.com/t/ZPH7PbVhQDwt7-vS8eu/"}' --pretty

Example — get product analytics (all pages):

node scripts/run.js --tool product_list_analytics \
  --params '{"region":"US","category_id":"600001"}' \
  --all-pages

Pagination for analytics endpoints:

All *_analytics endpoints use page_num (1-indexed) and page_size (max 10). run.js injects these automatically if not specified. Use --all-pages to iterate all pages automatically.

--page-num 1  --page-size 10   → first page (default)
--all-pages                    → all pages merged into one result

Cache directory structure:

.keyapi-cache/
├── products/
│   └── {product_id}/
│       ├── detail.json              # get_product_detail / product_detail_analytics
│       ├── reviews.json             # get_product_reviews / product_reviews_analytics
│       ├── trends.json              # product_trends_analytics
│       ├── creators.json            # product_creators_analytics
│       ├── videos.json              # product_videos_analytics
│       └── livestreams.json         # product_livestreams_analytics
├── shops/
│   └── {shop_id}/
│       ├── detail.json              # shop_detail_analytics
│       ├── products.json            # get_shop_products / shop_products_analytics
│       ├── creators.json            # shop_creators_analytics
│       ├── videos.json              # shop_videos_analytics
│       ├── livestreams.json         # shop_livestreams_analytics
│       └── trends.json              # shop_trends_analytics
├── categories/
│   ├── primary.json                 # primary_categories_analytics
│   ├── secondary_{category_id}.json # secondary_categories_analytics
│   └── tertiary_{category_l2_id}.json # tertiary_categories_analytics
├── searches/
│   ├── products/
│   │   └── {md5_of_query_params}.json  # product_list_analytics
│   └── shops/
│       └── {md5_of_query_params}.json  # shop_list_analytics
└── rankings/
    ├── products_{params_hash}.json   # product_ranking_analytics
    └── shops_{params_hash}.json      # shop_ranking_analytics

Cache-first policy:

Before every API call, check whether a cached result already exists for the given entity and node. If a valid cache file exists, load from disk and skip the API call. Category data is especially stable and should be aggressively cached.

Cover image processing:

After each API call, scan all response image URLs. If any URL's host matches echosell-images.tos-ap-southeast-1.volces.com, collect those URLs and call batch_download_cover_images in a single batch request. Replace the original URLs in your working dataset with the converted URLs returned by this node.

Step 4 — Synthesize and Report Findings

After collecting all API responses, produce a structured market intelligence report tailored to the user's objective:

For product analysis:

1. Product Overview — Title, price range, seller info, category path (L1 → L2 → L3), rating.
2. Sales Performance — Historical sales volume, GMV trend, growth rate, seasonality patterns.
3. Customer Sentiment — Review volume, rating distribution, key positive/negative themes from reviews.
4. Creator & Content Attribution — Top creators promoting the product, video and live-stream conversion rates.
5. Competitive Position — Ranking within category, price positioning vs. competing products.

For shop analysis:

1. Shop Profile — Shop name, category focus, total products, seller tier.
2. Revenue Intelligence — GMV history, monthly sales trend, growth trajectory.
3. Product Portfolio — Top-performing products, category distribution, price range strategy.
4. Creator Ecosystem — Associated creators, their individual GMV contributions, collaboration patterns.
5. Market Position — Category ranking, competitive comparison.

For category/market analysis:

1. Category Landscape — Category hierarchy, total market size estimate, top sub-categories.
2. Top Products & Shops — Ranking leaders, their metrics, and differentiation factors.
3. Trend Analysis — Rising vs. declining sub-categories, emerging product types.
4. Opportunity Signals — Underserved niches, high-growth segments, pricing white spaces.

author: KeyAPI license: MIT repository: https://github.com/EchoSell/keyapi-skills

Common Rules

author: KeyAPI license: MIT repository: https://github.com/EchoSell/keyapi-skills

Error Handling