Kalodata Product Research

Kalodata Product Research

Query and analyze TikTok Shop products using Kalodata's product intelligence API with intelligent filtering and research goal detection.

Overview

Enables querying and analyzing TikTok Shop products using Kalodata's product intelligence API with intelligent filtering and research goal detection. Provides category-based queries, flexible filtering, intelligent goal detection, and comprehensive product analytics.

When to Use

Trigger phrases:

• "kalodata product research"

• "Product Discovery: Find trending or emerging products in any TikTok Shop cat"

• "Competitive Analysis: Analyze creator count, pricing, and revenue patterns"

• "Market Research: Understand category performance and trends"

• Product Discovery: Find trending or emerging products in any TikTok Shop category

• Competitive Analysis: Analyze creator count, pricing, and revenue patterns

• Market Research: Understand category performance and trends

• Trend Identification: Spot products with rising revenue trends

• Opportunity Finding: Discover low-competition niches

The Process

1. Identify research goal – Determine what you want to find (trending, emerging, winners, etc.)
2. Configure query parameters – Set category, date range, filters, sorting
3. Execute product query – Run the query using the ProductResearcher
4. Analyze results – Review metrics, trends, and competitive patterns
5. Take action – Make business decisions based on insights

When NOT to Use

• Task is outside your authorization scope
• You need to implement controls (use implementing-* skills)
• Task is about analysis, not action (use analyzing-* skills)
• You don't have access to target systems
• Task requires compliance expertise (consult professionals)
• Task is about defense, not offense (use defensive skills)

Red Flags

• Trying to query real-time data (this skill works with historical research data)
• Not specifying a category or using invalid category IDs
• Ignoring date ranges (can lead to incomplete or outdated data)
• Using filters incompatible with your research goal

Verification

• Query returns products within specified date range
• AI goal detection correctly adjusts filters for emerging/trending/bestsellers
• Metrics (revenue, creators, conversion rates) display correctly
• Trend analysis matches manual verification from Kalodata dashboard

Do Not Use This Skill When

This section covers do not use this skill when for the kalodata-product-research skill. Key operations include input validation, core processing, and output verification. Refer to the skill overview for detailed usage instructions.

1. Category-Based Queries

Query products by primary or secondary category ID:

• cateIds: Main category filter
• showCateIds: Display category for results

2. Flexible Filters

3. Sorting Options

4. AI Filter Intelligence

Automatically adjusts filters based on research goals:

5. Pagination

• Automatic pagination via pageNo and pageSize
• Built-in paginate() helper for bulk retrieval
• getTotalCount() for estimating total results

6. Structured Insights

Returns processed data with business-ready insights:

interface ProcessedProduct {
  id: string;
  title: string;
  price: { min: number; max: number };
  revenue: number;
  revenueTrend: number[];
  sales: number;
  creators: number;
  conversionRate: number;
  launchDate: string;
  rating: number;
  isOverseas: boolean;
  isFullService: boolean;
  insights: {
    trendDirection: 'rising' | 'stable' | 'declining';
    competitionLevel: 'low' | 'medium' | 'high';
    opportunityScore: number;
  };
}

API Reference

ProductResearcher Class

class ProductResearcher {
  constructor(options: ClientOptions);
  
  // Query methods
  queryByCategory(params: QueryParams): Promise<ProcessedProduct[]>;
  queryByGoal(params: GoalQueryParams): Promise<ProcessedProduct[]>;
  
  // Pagination
  paginate(params: QueryParams, maxPages?: number): AsyncGenerator<ProcessedProduct[]>;
  
  // Utilities
  getTotalCount(params: QueryParams): Promise<number>;
  getCategories(): Promise<Category[]>;
}

QueryParams Interface

interface QueryParams {
  categoryId: string;
  dateRange: { start: string; end: string };
  filters?: {
    priceMin?: number;
    priceMax?: number;
    revenueMin?: number;
    revenueMax?: number;
    creatorMin?: number;
    creatorMax?: number;
    salesChannel?: 'online' | 'offline' | 'all';
    strategy?: 'affiliate' | 'self-operated' | 'all';
  };
  sort?: { field: string; type: 'ASC' | 'DESC' }[];
  pageSize?: number;
  pageNo?: number;
}

GoalQueryParams Interface

interface GoalQueryParams {
  goal: string;
  categoryId: string;
  dateRange: { start: string; end: string };
  filters?: Partial<QueryParams['filters']>;
  pageSize?: number;
}

Research Goal Patterns

This section covers research goal patterns for the kalodata-product-research skill. Key operations include input validation, core processing, and output verification. Refer to the skill overview for detailed usage instructions.

Finding Emerging Products

Goal: "find emerging products", "new products", "rising stars", "just launched"
Filters Applied:
- sort: revenue_trend ASC
- launch_date: within last 30 days
- creator_num: 10-100 (some traction but not saturated)

Finding Stable Winners

Goal: "stable winners", "best sellers", "proven products", "market leaders"
Filters Applied:
- sort: revenue DESC
- creator_num: >100 (wide creator adoption)
- launch_date: >60 days ago

Finding Quick Wins

Goal: "quick wins", "fast growers", "trending now", "viral products"
Filters Applied:
- sort: gmv_B ASC (growth rate)
- revenue_trend: trending up
- dateRange: last 7-14 days

Finding Low Competition

Goal: "low competition", "niche products", "underserved markets", "easy to rank"
Filters Applied:
- creator_num: 1-10
- sort: revenue DESC
- exclude: saturated categories

Error Handling

try {
  const products = await researcher.queryByCategory(params);
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Invalid credentials - prompt for new session/cf_clearance
  } else if (error instanceof RateLimitError) {
    // Wait and retry with backoff
  } else {
    // Handle other errors
  }
}

Environment Variables

# Required
KALODATA_SESSION=your_session_cookie
KALODATA_CF_CFLEARANCE=your_cf_clearance_token

# Optional
KALODATA_COUNTRY=ID
KALODATA_CURRENCY=IDR
KALODATA_LANGUAGE=id-ID

Common Category IDs (TikTok Shop Indonesia)

Integration Example

// Complete research workflow
import { ProductResearcher } from '../../src/kalodata/product-research.js';

async function researchCategory(categoryId: string) {
  const researcher = new ProductResearcher({
    session: process.env.KALODATA_SESSION!,
    cfClearance: process.env.KALODATA_CF_CLEARANCE!,
  });

  // Get overview with emerging products
  const emerging = await researcher.queryByGoal({
    goal: 'find emerging products',
    categoryId,
    dateRange: { start: '2026-01-01', end: '2026-02-19' },
  });

  // Get stable winners
  const winners = await researcher.queryByGoal({
    goal: 'find stable winners',
    categoryId,
    dateRange: { start: '2026-01-01', end: '2026-02-19' },
  });

  // Generate report
  return {
    emerging: emerging.slice(0, 10),
    winners: winners.slice(0, 10),
    insights: {
      totalEmerging: emerging.length,
      totalWinners: winners.length,
    }
  };
}

Best Practices

1. Date Range: Use 30-90 day ranges for trend analysis
2. Pagination: Always paginate for comprehensive data
3. Caching: Don't cache video URLs (they expire)
4. Rate Limiting: Add delays between requests
5. Error Handling: Always handle auth errors gracefully

See Also

• Kalodata API Client - Core API client
• Kalodata Types - TypeScript definitions
• Video Research Skill - Video content analysis

Process

1. Analyze the task requirements
2. Apply domain expertise
3. Verify output quality

Anti-Rationalization Table