trendspyg 0.5.1

Free, open-source Python library for real-time Google Trends data with CLI and API - pytrends alternative with 188K+ configurations

trendspyg

Python library for downloading real-time Google Trends data. A modern alternative to the archived pytrends.

Using this library from a coding agent? See AGENTS.md for a concise, agent-ready reference.

Installation

pip install trendspyg

# With async support
pip install trendspyg[async]

# With CLI
pip install trendspyg[cli]

# All features
pip install trendspyg[all]

Quick Start

RSS Feed (Fast - 0.2s)

from trendspyg import download_google_trends_rss

# Get current trends with news articles
trends = download_google_trends_rss(geo='US')

for trend in trends[:3]:
    print(f"{trend['trend']} - {trend['traffic']}")
    if trend['news_articles']:
        print(f"  {trend['news_articles'][0]['headline']}")

CSV Export (Comprehensive - 10s)

from trendspyg import download_google_trends_csv

# Get 480+ trends with filtering (requires Chrome)
df = download_google_trends_csv(
    geo='US',
    hours=168,            # Past 7 days
    category='sports',
    output_format='dataframe'
)

Async (Parallel Fetching)

import asyncio
from trendspyg import download_google_trends_rss_batch_async

async def main():
    results = await download_google_trends_rss_batch_async(
        ['US', 'GB', 'CA', 'DE', 'JP'],
        max_concurrent=5
    )
    for country, trends in results.items():
        print(f"{country}: {len(trends)} trends")

asyncio.run(main())

CLI

trendspyg rss --geo US
trendspyg csv --geo US-CA --category sports --hours 168
trendspyg list --type countries

Data Sources

Feature	RSS	CSV
Speed	0.2s	~10s
Trends	5–25 (varies by region/time)	480+
News articles	Yes	No
Time filtering	No	Yes (4h/24h/48h/7d)
Category filter	No	Yes (20 categories)
Requires Chrome	No	Yes

Features

• 125 countries + 51 US states
• 20 categories (sports, tech, health, etc.)
• 4 time periods (4h, 24h, 48h, 7 days)
• 4 output formats (dict, DataFrame, JSON, CSV)
• Async support for parallel fetching
• Built-in caching (5-min TTL)
• CLI for terminal access

Normalized output (for agents & pipelines)

Pass normalize=True to get one unified, JSON-native schema that is identical for both the RSS and CSV paths — no need to learn two different shapes.

from trendspyg import download_google_trends_rss

env = download_google_trends_rss(geo='US', normalize=True)
# {'schema_version': '1.0', 'source': 'rss', 'geo': 'US',
#  'fetched_at': '2026-05-22T...Z', 'count': 10, 'trends': [...]}

for t in env['trends']:
    print(t['rank'], t['keyword'], t['volume_min'])  # volume_min is a real int

Every trend has a fixed, JSON-safe shape: keyword, rank, volume_text, volume_min (int), started_at / ended_at (ISO 8601 or None), is_active, related_queries (list), news (list), image, explore_url. normalize=True works on every entry point — RSS, CSV, async, and the batch functions (each geo then maps to its own envelope) — and on the CLI (trendspyg rss --geo US --normalize). It is opt-in — default output is unchanged.

Caching

from trendspyg import clear_rss_cache, get_rss_cache_stats

# Results are cached for 5 minutes by default
trends = download_google_trends_rss(geo='US')  # Network call
trends = download_google_trends_rss(geo='US')  # From cache

# Bypass cache
trends = download_google_trends_rss(geo='US', cache=False)

# Check cache stats
print(get_rss_cache_stats())

# Clear cache
clear_rss_cache()

Documentation

• API Reference
• CLI Documentation
• Coding-agent quick reference
• Changelog
• Examples

Requirements

• Python 3.8+
• Chrome browser (for CSV export only)

License

MIT License - see LICENSE for details.

Links

• GitHub
• PyPI
• Issues