trendkit 0.2.1

Google Trends aggregator optimized for LLM tool calls

trendkit

Token-Optimized Trends for AI

Google Trends aggregator designed for LLM tool calls with minimal token usage.

---

Why trendkit?

"Claude에게 트렌드를 물었더니 5,000 토큰을 썼다. 그래서 5토큰으로 줄였다."

Problem	Before	After (trendkit)
Token waste	~500 tokens/item	~5 tokens/item
Complex setup	API keys, auth	pip install and go
No MCP support	Build your own	Built-in MCP server
Limited bulk	~20 items max	100+ items

Comparison with Alternatives

Feature	trendkit	pytrends	SerpAPI	Tavily
Price	Free	Free	$50/mo	$20/mo
Token Optimized	Yes	No	No	No
MCP Native	Yes	No	No	Partial
Bulk Collection	100+	~20	100+	No
Setup Complexity	Easy	Easy	Medium	Easy

---

Features

• Token-optimized: Minimal output format for LLM function calling (~5 tokens/item)
• Multiple backends: RSS (fast), Playwright with stealth (bulk), pytrends (analysis)
• Anti-detection: playwright-stealth bypasses bot detection
• Enriched export: News, images, related queries with metadata
• Multiple interfaces: Python API, CLI, MCP server

---

Installation

# Basic
pip install trendkit

# With Playwright (bulk collection with anti-detection)
pip install trendkit[playwright]
playwright install chromium

# With CLI
pip install trendkit[cli]

# With MCP server
pip install trendkit[mcp]

# All features
pip install trendkit[all]
playwright install chromium

---

Quick Start

from trendkit import trending, trending_bulk, related, compare, interest

# Realtime trending (minimal tokens)
keywords = trending(limit=5)
# ['환율', '신한카드', '국민신문고', ...]

# Bulk collection (~100 items)
data = trending_bulk(limit=100, output="trends.csv")

# Enriched bulk export (with news, related queries, images)
data = trending_bulk(limit=10, enrich=True, output="trends.json")

# Related queries
related_kw = related("아이폰", limit=5)
# ['아이폰 17', '아이폰 디시', ...]

# Compare keywords
scores = compare(["삼성", "애플"])
# {"삼성": 45.6, "애플": 14.4}

# Interest over time
data = interest(["BTS"], days=7)
# {"dates": [...], "values": {"BTS": [42, 45, ...]}}

# YouTube search interest (via Google Trends)
data = interest(["BTS"], platform="youtube")

---

CLI Usage

# Trending keywords
trendkit trend --limit 5
trendkit trend --geo US --format standard

# Bulk collection
trendkit bulk --limit 100 --output trends.csv
trendkit bulk --limit 10 --enrich --output trends.json

# Related queries
trendkit rel 아이폰 --limit 5

# Compare keywords
trendkit cmp 삼성 애플 --days 90

# Interest history
trendkit hist BTS --days 7

---

MCP Server

Add to Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

From source (current)

{
  "mcpServers": {
    "trendkit": {
      "command": "uv",
      "args": ["--directory", "/ABSOLUTE/PATH/TO/trendkit", "run", "trendkit-mcp"]
    }
  }
}

After PyPI release

{
  "mcpServers": {
    "trendkit": {
      "command": "uvx",
      "args": ["--from", "trendkit[mcp]", "trendkit-mcp"]
    }
  }
}

Available Tools

Tool	Description
trends_trending	Get realtime trending keywords
trends_related	Get related search queries
trends_compare	Compare keywords by interest
trends_interest	Get interest over time

---

Token Optimization

The key design principle of trendkit is minimal token usage for LLM integrations.

Format	Tokens/Item	Example Output
minimal	~5	["키워드1", "키워드2"]
standard	~15	[{"keyword": "키워드1", "traffic": "10만+"}]
full	~100	Full data with news, images, related

Real-world Impact

# Traditional approach: ~5,000 tokens for 10 items
# trendkit minimal: ~50 tokens for 10 items
# = 99% token reduction

---

Use Cases

AI News Bot

from trendkit import trending, related

# Get trending topics
topics = trending(limit=5, format="minimal")

# Expand with related queries
for topic in topics:
    queries = related(topic, limit=3)
    # Generate news summary for each...

Content Recommendation

from trendkit import compare

# Find which topic is more popular
scores = compare(["React", "Vue", "Svelte"])
# {"React": 67.2, "Vue": 24.1, "Svelte": 8.7}

Marketing Trend Analysis

from trendkit import trending_bulk

# Collect comprehensive trend data
data = trending_bulk(
    limit=100,
    enrich=True,
    output="weekly_trends.json"
)

---

Bulk Export

Basic (CSV)

trending_bulk(limit=100, output="trends.csv")

keyword,rank,traffic
내일 날씨,2,20만+
이노스페이스,3,5천+

Enriched (JSON)

trending_bulk(limit=10, enrich=True, output="trends.json")

{
  "metadata": {
    "geo": "KR",
    "hours": 168,
    "collected_at": "2025-12-23T23:01:17",
    "total_items": 10,
    "source": "google_trends"
  },
  "trends": [
    {
      "keyword": "내일 날씨",
      "rank": 2,
      "traffic": "20만+",
      "image": {"url": "...", "source": "Daum"},
      "news": [
        {"headline": "...", "url": "...", "source": "..."}
      ],
      "related": ["내일 서울 날씨", "대구 내일 날씨"],
      "explore_link": "https://trends.google.com/..."
    }
  ]
}

---

API Reference

trending(geo="KR", limit=10, format="minimal")

Get realtime trending keywords (via RSS, fast).

Returns:

• minimal: ["keyword1", "keyword2", ...]
• standard: [{"keyword": "...", "traffic": "..."}]
• full: [{"keyword": "...", "traffic": "...", "news": [...]}]

trending_bulk(geo="KR", hours=168, limit=100, enrich=False, output=None, headless=True)

Get bulk trending data (via Playwright with stealth, ~100 items).

Parameters:

• hours: Time period (4, 24, 48, 168)
• enrich: Add news, images, related queries
• output: Save to file (.csv or .json)
• headless: Run browser in headless mode (default: True, set False for debugging)

related(keyword, geo="KR", limit=10)

Get related search queries for a keyword.

compare(keywords, geo="KR", days=90, platform="web")

Compare keywords by average search interest.

interest(keywords, geo="KR", days=7, platform="web")

Get interest over time for keywords.

Platform options: "web", "youtube", "images", "news"

---

Architecture

trendkit/
├── src/trendkit/
│   ├── core.py              # Main API functions
│   ├── types.py             # Type definitions
│   ├── cli.py               # CLI (trendkit command)
│   ├── mcp_server.py        # MCP server
│   └── backends/
│       ├── rss.py               # RSS backend (fast, ~20 items)
│       ├── pytrends_backend.py  # Analysis features
│       └── playwright_backend.py # Bulk collection with stealth (~100 items)
└── tests/                   # 206 tests (86% coverage)

---

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Development Setup

git clone https://github.com/seolcoding/trendkit.git
cd trendkit
uv sync --all-extras
uv run pytest

---

Roadmap

See ROADMAP.md for planned features.

Implemented:

• ✅ Cache layer for reduced API calls
• ✅ Playwright with stealth mode for anti-detection
• ✅ Comprehensive error handling with helpful suggestions

Coming Soon:

• LangChain Tool integration
• Multi-geo support expansion

---

License

MIT