Python library for Google Trends data — real-time trending topics and keyword analysis over time (interest over time, related queries, interest by region). A modern, actively-maintained alternative to the archived pytrends.
Using this library from a coding agent? See AGENTS.md for a concise, agent-ready reference.
pip install trendspyg
# With async support
pip install trendspyg[async]
# With CLI
pip install trendspyg[cli]
# All features
pip install trendspyg[all]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']}")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'
)from trendspyg import download_google_trends_interest_over_time
# Google's 0-100 relative-interest time series for a keyword (requires Chrome)
series = download_google_trends_interest_over_time("bitcoin", geo="US", timeframe="today 12-m")
for point in series[-3:]:
print(point["date"], point["value"]) # {'date': '2026-05-31T00:00:00+00:00', 'value': 57, 'is_partial': True}from trendspyg import download_google_trends_explore
# Full picture in one call: interest over time + related queries + interest by region
env = download_google_trends_explore("bitcoin", geo="US")
print(env["interest_over_time"][-1])
print(env["related_queries"]["rising"][0]) # {'query': '...', 'formatted_value': 'Breakout', ...}
print(env["interest_by_region"][0]) # {'geo_code': 'US-..', 'geo_name': '..', 'value': 100}The Explore path drives a real browser against Google's Explore page and is rate-limit sensitive (~10–90s per call, with retries). Use it for analysis, not high-frequency polling — use the RSS path for fast, frequent real-time checks.
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())trendspyg rss --geo US
trendspyg csv --geo US-CA --category sports --hours 168
trendspyg explore --keyword bitcoin --output csv
trendspyg list --type countries| RSS | CSV | Explore | |
|---|---|---|---|
| Answers | "what's trending now?" | "what's trending now?" | "how is interest in X moving?" |
| Speed | 0.2s | ~10s | ~10–90s (rate-limit sensitive) |
| Output | 5–25 current trends | 480+ current trends | interest over time, related queries, regions |
| News articles | Yes | No | No |
| Time filtering | No | Yes (4h/24h/48h/7d) | Yes (any timeframe) |
| Category filter | No | Yes (20 categories) | Yes |
| Requires Chrome | No | Yes | Yes |
- Real-time trending topics (RSS + CSV paths) and keyword analysis over time (Explore path)
- Interest over time, related queries, and interest by region for any keyword — the core pytrends use case
- 125 countries + 51 US states, 20 categories, 4 trending time periods (4h, 24h, 48h, 7 days)
- Output formats: dict, DataFrame, JSON, CSV (+ Parquet on the CSV path)
- Async support for parallel fetching
- Built-in caching (5-min TTL)
- Agent-ready: typed shapes,
normalize=True, and a JSON-native Explore schema - CLI for terminal access
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 intEvery 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.
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()- Python 3.8+
- Chrome browser (for the CSV and Explore paths; the RSS path needs no browser)
MIT License - see LICENSE for details.