Python library for Google Trends data — real-time trending topics and keyword analysis over time: interest over time, related queries, interest by region, 2–5-keyword comparison on one shared scale, and YouTube / News / Images / Shopping search interest (gprop). Ships a CLI, an MCP server for Claude and other AI agents, and an opt-in local history archive. A modern, actively-maintained alternative to the archived pytrends. Docs: flack0x.github.io/trendspyg.
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]
# With the MCP server (use trendspyg from Claude & other AI agents; Python 3.10+)
pip install trendspyg[mcp]
# 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). Measured budget: roughly 8–10 fresh browser sessions in a short burst (~15 min) is enough for Google to serve its hard 429 block page to that IP; trendspyg raises
RateLimitErrorat once when it does (1.5.1+), and recovery took anywhere from ~35 minutes to much longer in our measurements — a rate-limit error means stop for a long while, not retry. Since 1.5.2 every session first visits the Trends home page to pick up Google's session cookie (without it, an IP Google has seen before is refused outright). Space sessions out, reuse results withcache="disk"(no browser run), and use the RSS path for fast, frequent real-time checks — never poll Explore. Fewer refusals (1.6.0): passcookies="disk"(CLI--cookies disk) and each session reuses Google's cookies from a small local file, so your machine looks like one returning visitor — measured live: while brand-new sessions were refused with the 429 page, sessions carrying the saved jar were served. Opt-in (it keeps a Google cookie on disk);clear_explore_cookies()deletes it.
from trendspyg import download_google_trends_comparison
# 2-5 keywords, directly comparable (single-keyword series are each scaled
# independently by Google — only a comparison returns comparable numbers)
env = download_google_trends_comparison(["bitcoin", "ethereum", "solana"], geo="US")
print(env["averages"]) # {'bitcoin': 39, 'ethereum': 7, 'solana': 5}
print(env["interest_over_time"][-1]["values"]) # {'bitcoin': 41, 'ethereum': 6, 'solana': 4}
print(env["interest_by_region"][0]) # {'geo_code': 'US-WY', ..., 'top_keyword': 'bitcoin'}
# pytrends-style table: one column per keyword
df = download_google_trends_comparison(["bitcoin", "ethereum"], output_format="dataframe")from trendspyg import watch_google_trends_rss
# Stream changes between RSS snapshots (safe for continuous polling — RSS only)
for change in watch_google_trends_rss(geo="US", interval=60, events=["new", "volume_up"]):
print(change["event"], change["keyword"], change["volume_min"])
# {'event': 'new', 'keyword': '...', 'rank': 3, 'prev_rank': None, 'volume_min': 50000, ...}Monitoring is built on the fast RSS path, so it is safe to poll continuously (the CSV and Explore paths are not). The pure
diff_trends(old, new)helper is also exported if you manage snapshots yourself.
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 explore -k bitcoin -k ethereum --quiet # comparison (repeat -k 2-5 times)
trendspyg explore -k bitcoin --gprop youtube # YouTube search interest (1.5.0)
trendspyg watch --geo US --interval 60 --events new,volume_up
trendspyg list --type countriesGive any MCP client (Claude Desktop, Claude Code, Cursor, ...) live Google Trends tools — free, local, no API key. Requires Python 3.10+; runs on the MCP SDK v2 stable line or v1 (auto-detected).
pip install trendspyg[mcp]
# Claude Code — one command:
claude mcp add trendspyg -- trendspyg-mcpClaude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"trendspyg": { "command": "trendspyg-mcp" }
}
}Eight tools: get_trending_now, compare_trending, get_trend_changes (what changed
since the last check), list_supported_options, get_trending_history (what WAS
trending, from the local archive — instant) — all fast and browser-free — plus
get_interest_over_time, compare_interest_over_time (2-5 keywords, one shared scale)
and get_trending_full (drive Chrome; slower, described honestly to the agent —
though since 1.4.0 identical repeat interest/compare questions answer instantly
from a local disk cache).
| RSS | CSV | Explore | |
|---|---|---|---|
| Answers | "what's trending now?" | "what's trending now?" | "how is interest in X moving?" |
| Speed | sub-second* | ~10s | ~10–90s (rate-limit sensitive) |
| Output | 10–20 current trends | 480+ current trends | interest over time, related queries, regions; 2–5-keyword comparison; web / YouTube / News / Images / Shopping |
| 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 |
* Network-dominated: ~0.2s on low-latency links, ~1.4s measured on a high-RTT connection; cache hits are instant. Honest measured numbers per path live in benchmarks/.
Monitoring:
trendspyg watch/watch_google_trends_rss(...)polls the RSS path and streams changes (new / dropped / volume / rank) as they happen — built on RSS, so it is safe for continuous polling.
Trending data is ephemeral — once the feed updates, "what was trending last Tuesday" is gone, and nobody sells it. Opt in to archiving and every fetch records a snapshot to a single local SQLite file (stdlib only — no server, no keys, no new dependencies):
trendspyg rss --geo US --archive # record a snapshot while fetching
trendspyg history -k bitcoin --timeline # when did it first trend? how did it move?
trendspyg history --stats # size, date range, geosfrom trendspyg import download_google_trends_rss, get_keyword_history, read_archive
download_google_trends_rss(geo="US", archive=True) # archive while you fetch
download_google_trends_rss(geo="US", cache="disk") # cache that survives restarts
read_archive(geo="US", start="2026-08-01") # what WAS trending
get_keyword_history("bitcoin") # first seen, rank over timeThe Explore path joins in 1.4.0 — and its disk cache is the bigger win there, because every fresh Explore fetch is a 10-40s rate-limited browser run:
from trendspyg import download_google_trends_interest_over_time
# First call drives Chrome; identical calls within 24h answer instantly from disk.
download_google_trends_interest_over_time("bitcoin", cache="disk", archive=True)trendspyg explore -k bitcoin --cache disk --archive
trendspyg explore -k bitcoin --cookies disk # be a returning visitor (1.6.0)
trendspyg history --source explore -k bitcoin # your keyword-research historyCached Explore results stay fresh for 1 hour on "now *" timeframes and 24 hours
otherwise (override with cache_ttl= / --cache-ttl), and a cache hit keeps the
original fetch time, so the data's age is never hidden. Archive writes never
break a download (they warn instead), and prune_archive /
trendspyg history --prune-before reclaim space when you want it back
(~15 KB per RSS snapshot, ~4-26 KB per Explore snapshot; ~130-260 MB/year at
hourly RSS cadence).
- Real-time trending topics (RSS + CSV paths) and keyword analysis over time (Explore path)
- Real-time monitoring —
watchstreams trend changes as NDJSON (RSS-only, poll-safe) - Interest over time, related queries, and interest by region for any keyword — the core pytrends use case
- Multi-keyword comparison (2-5 terms) on one shared 0-100 scale — the pytrends
kw_listuse case - Google property selection — analyze YouTube, News, Images, or Shopping search interest, not just web (
gprop=, 1.5.0) - 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) + opt-in disk cache that survives restarts (1.3.0) — Explore too, with hours-scale freshness, so repeat analyses skip the 10-40s browser run (1.4.0); a cached full Explore answer also serves the plain interest-over-time question (1.6.0)
- Returning-visitor sessions — opt-in
cookies="disk"reuses Google's session cookies across Explore calls, so a busy IP keeps getting served (1.6.0) - Historical archiving — opt-in local SQLite archive of every fetch (all three data paths) +
trendspyg history(1.3.0/1.4.0) - Agent-ready: typed shapes,
normalize=True, and a JSON-native Explore schema - MCP server —
trendspyg-mcpexposes 8 tools to Claude and any MCP client (no API key; MCP SDK v1 & v2 both supported) - CLI for terminal access
- Stable API — semantic versioning with a written contract: STABILITY.md
- Documentation site — flack0x.github.io/trendspyg (1.5.0)
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()- Documentation site — everything below, rendered and searchable
- API Reference
- CLI Documentation
- Coding-agent quick reference
- API stability policy
- Benchmarks
- Changelog
- Examples
trendspyg is 1.0 — the public API follows semantic versioning under a written contract: what's covered (every exported name, the exception types, CLI commands and flags, MCP tools, the versioned data schemas), what a breaking change is, and how deprecations work. The honest boundary: Google's side of the wire is not ours to guarantee — upstream changes are fixed in patch releases. Details in STABILITY.md.
- Python 3.8+
- Chrome browser (for the CSV and Explore paths; the RSS path needs no browser)
MIT License - see LICENSE for details.