from __future__ import annotations
import csv
import html
import tempfile
import time
from datetime import datetime, timezone
from typing import Any, Dict, List, Optional, Tuple
import gradio as gr
from tool import (
COUNTRIES,
MAX_COMPARE,
SCRAPE_DO_SIGNUP_URL,
TRENDING_CATEGORIES,
ScrapeDoGoogleTrendsTool,
)
# ZeroGPU hardware refuses to keep a Space alive unless it finds at least one
# @spaces.GPU function at startup. This app is pure HTTP and never touches a GPU,
# so the probe below exists only to satisfy that check. It is never called.
try:
import spaces
@spaces.GPU(duration=1)
def _zerogpu_probe() -> str:
return "ok"
except ImportError:
pass
COUNTRY_CHOICES = [(label, code) for label, code in COUNTRIES]
TRENDING_COUNTRY_CHOICES = [(label, code) for label, code in COUNTRIES if code]
DATE_CHOICES = [
("Past 7 days", "now 7-d"),
("Past 30 days", "today 1-m"),
("Past 90 days", "today 3-m"),
("Past 12 months", "today 12-m"),
("Past 5 years", "today 5-y"),
("2004 – present", "all"),
]
SEARCH_TYPE_CHOICES = [
("Web search", "web"),
("YouTube search", "youtube"),
("News search", "news"),
("Image search", "images"),
("Google Shopping", "shopping"),
]
RESOLUTION_CHOICES = [
("Automatic", ""),
("Countries", "country"),
("States / regions", "region"),
("Metro areas (US)", "metro"),
("Cities", "city"),
]
HOURS_CHOICES = [("Past 4 hours", 4), ("Past 24 hours", 24), ("Past 48 hours", 48), ("Past 7 days", 168)]
CATEGORY_CHOICES = [(name, cid) for cid, name in TRENDING_CATEGORIES.items()]
SORT_CHOICES = [("Relevance", "relevance"), ("Search volume", "search_volume"), ("Most recent", "recency"), ("Title", "title")]
SERIES_COLORS = ["#4285f4", "#db4437", "#f4b400", "#0f9d58", "#ab47bc"]
NO_TOKEN_MD = (
"### Paste your Scrape.do API token above\n\n"
f"No token yet? [Create a free account]({SCRAPE_DO_SIGNUP_URL}) — "
"1,000 free credits a month, no credit card. Each Google Trends call costs 10 credits."
)
# --------------------------------------------------------------------- helpers
def _esc(value: Any) -> str:
return html.escape("" if value is None else str(value), quote=True)
def _safe_link(url: Any) -> str:
url = str(url or "")
return url if url.startswith(("http://", "https://")) else ""
def _num(value: Any) -> Optional[float]:
if isinstance(value, bool):
return None
try:
return float(str(value).replace(",", ""))
except (TypeError, ValueError):
return None
def _tool_or_none(token: str) -> Optional[ScrapeDoGoogleTrendsTool]:
if not token or not token.strip():
return None
return ScrapeDoGoogleTrendsTool(api_token=token.strip())
def _write_csv(rows: List[Dict[str, Any]], prefix: str) -> Optional[str]:
if not rows:
return None
fieldnames: List[str] = []
for row in rows:
for key in row:
if key not in fieldnames:
fieldnames.append(key)
handle = tempfile.NamedTemporaryFile(
mode="w", suffix=".csv", prefix=f"{prefix}-", delete=False, newline="", encoding="utf-8-sig",
)
writer = csv.DictWriter(handle, fieldnames=fieldnames)
writer.writeheader()
for row in rows:
writer.writerow({key: row.get(key, "") for key in fieldnames})
handle.close()
return handle.name
def _error_md(data: Dict[str, Any]) -> str:
out = f"**That didn't go through.**\n\n{data.get('errorMessage') or 'Unknown error'}"
if data.get("hint"):
out += f"\n\n{data['hint']}"
return out
def _place_name(geo: str) -> str:
for label, code in COUNTRIES:
if code == geo:
if not code:
return "worldwide"
return f"the {label}" if label in ("United States", "United Kingdom", "Netherlands") else label
return "worldwide" if geo in ("", "worldwide") else geo
def _period_name(date: str) -> str:
for label, value in DATE_CHOICES:
if value == date:
return label.lower()
return date
def _fmt_compact(value: Any) -> str:
number = _num(value)
if number is None:
return ""
if number >= 1_000_000:
return f"{number / 1_000_000:.0f}M+" if number % 1_000_000 == 0 else f"{number / 1_000_000:.1f}M+"
if number >= 1_000:
return f"{number / 1_000:.0f}K+"
return f"{int(number)}+"
def _ago(stamp: Any) -> str:
seconds = _num(stamp)
if not seconds:
return ""
diff = time.time() - seconds
if diff < 0:
return "just now"
if diff < 3600:
return f"{int(diff // 60)} min ago"
if diff < 86400:
hours = int(diff // 3600)
return f"{hours} hour{'s' if hours != 1 else ''} ago"
days = int(diff // 86400)
return f"{days} day{'s' if days != 1 else ''} ago"
def _iso(stamp: Any) -> str:
seconds = _num(stamp)
if not seconds:
return ""
return datetime.fromtimestamp(seconds, tz=timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
# ------------------------------------------------------------------- chart
def _axis_label(stamp: int, span_days: float, fallback: Any) -> str:
if not stamp:
return str(fallback or "")
moment = datetime.fromtimestamp(stamp, tz=timezone.utc)
if span_days > 400:
return moment.strftime("%b %Y")
if span_days > 3:
return moment.strftime("%b %d").replace(" 0", " ")
return moment.strftime("%H:%M")
def render_chart(timeline: List[Dict[str, Any]], series: List[str], note: str = "") -> str:
"""A Google Trends-style line chart as inline SVG, with hover details per point."""
if not timeline or not series:
return '
Not enough data to draw a chart.
'
width, height = 960, 300
left, right, top, bottom = 40, 16, 14, 36
plot_w, plot_h = width - left - right, height - top - bottom
count = len(timeline)
step = plot_w / max(1, count - 1)
def x_at(index: int) -> float:
return left + (index * step if count > 1 else plot_w / 2)
def y_at(value: float) -> float:
return top + (100 - max(0.0, min(100.0, value))) / 100 * plot_h
parts: List[str] = [f'")
legend = "".join(
f'{_esc(name)}'
for i, name in enumerate(series)
)
note_html = f'
{_esc(note)}
' if note else ""
return (
'
'
'
Interest over time
'
f'
{legend}
'
f'{"".join(parts)}{note_html}'
'
100 is the busiest point in this period and place. Hover the chart for exact values.
'
"
"
)
# ------------------------------------------------------------ explore view
def _region_bars(regions: List[Dict[str, Any]], series: List[str], limit: int = 15) -> str:
rows = []
for item in regions:
if not isinstance(item, dict):
continue
values = item.get("values")
if isinstance(values, list) and values:
numbers = [(_num(v.get("extracted_value", v.get("value"))) or 0) for v in values if isinstance(v, dict)]
score = max(numbers) if numbers else 0
index = numbers.index(score) if numbers else 0
else:
score = _num(item.get("extracted_value", item.get("value"))) or 0
index = item.get("max_value_index") or 0
rows.append((item, score, int(index) if str(index).isdigit() else 0))
rows.sort(key=lambda r: r[1], reverse=True)
rows = [r for r in rows if r[1] > 0][:limit]
if not rows:
return ""
lines = []
for item, score, index in rows:
color = SERIES_COLORS[index % len(SERIES_COLORS)] if len(series) > 1 else SERIES_COLORS[0]
leader = (
f'{_esc(series[index])}'
if len(series) > 1 and index < len(series) else ""
)
lines.append(
f'
{_esc(item.get("location") or item.get("geo"))}'
f''
f'{score:.0f}{leader}
'
)
title = "Where each keyword leads" if len(series) > 1 else "Interest by region"
return f'
{title}
{"".join(lines)}
'
def _related_list(items: List[Dict[str, Any]], rising: bool, kind: str) -> str:
if not items:
return '
Not enough data.
'
rows = []
for position, item in enumerate(items[:15], start=1):
if kind == "topics":
topic = item.get("topic") or {}
label = _esc(topic.get("title") or item.get("title"))
sub = topic.get("type")
label += f' {_esc(sub)}' if sub else ""
else:
label = _esc(item.get("query"))
value = str(item.get("value") or "")
if rising and value.replace(",", "").isdigit():
value = f"+{value}%"
cls = "gt-breakout" if value.lower() == "breakout" else ("gt-rise" if rising else "gt-top")
link = _safe_link(item.get("link"))
label_html = f'{label}' if link else label
rows.append(
f'
{position}'
f'{label_html}{_esc(value)}
'
)
return "".join(rows)
def _related_card(block: Any, kind: str) -> str:
if not isinstance(block, dict):
return ""
title = "Related searches" if kind == "queries" else "Related topics"
return (
f'
{title}
'
f'
Top
{_related_list(block.get("top") or [], False, kind)}
'
f'
Rising
{_related_list(block.get("rising") or [], True, kind)}
'
"
"
)
def _series_names(timeline: List[Dict[str, Any]], preferred: List[str]) -> List[str]:
found: List[str] = []
for row in timeline:
for name in row["values"]:
if name not in found:
found.append(name)
ordered = [p for p in preferred if p in found]
return ordered + [f for f in found if f not in ordered]
def _timeline_rows(timeline: List[Dict[str, Any]], series: List[str]) -> List[Dict[str, Any]]:
rows = []
for row in timeline:
entry: Dict[str, Any] = {"date": row.get("date"), "timestamp": row.get("timestamp")}
for name in series:
value = row["values"].get(name)
entry[name] = int(value) if isinstance(value, float) and value.is_integer() else value
rows.append(entry)
return rows
def _extras_rows(data: Dict[str, Any]) -> List[Dict[str, Any]]:
rows: List[Dict[str, Any]] = []
for item in data.get("interest_by_region") or []:
if isinstance(item, dict):
rows.append({"section": "region", "name": item.get("location"), "code": item.get("geo"),
"value": item.get("extracted_value", item.get("value")), "link": ""})
for key, kind in (("related_queries", "query"), ("related_topics", "topic")):
block = data.get(key) or {}
for bucket in ("top", "rising"):
for item in block.get(bucket) or []:
if not isinstance(item, dict):
continue
topic = item.get("topic") or {}
rows.append({
"section": f"{bucket}_{kind}",
"name": item.get("query") or topic.get("title"),
"code": topic.get("type", ""),
"value": item.get("value"),
"link": item.get("link"),
})
return rows
# ---------------------------------------------------------------- handlers
def run_explore(
token: str, keyword: str, geo: str, date: str, search_type: str, resolution: str,
want_queries: bool, want_topics: bool,
) -> Tuple[str, str, str, Dict[str, Any], Optional[str], Optional[str]]:
tool = _tool_or_none(token)
if tool is None:
return NO_TOKEN_MD, "", "", {}, None, None
if not keyword or not keyword.strip():
return "Type a keyword to explore, e.g. `bitcoin`.", "", "", {}, None, None
data = tool.explore(keyword, geo, date, search_type, bool(want_queries), bool(want_topics), resolution or None)
if data.get("status") != "success":
return _error_md(data), "", "", data, None, None
timeline = data.get("timeline") or []
series = _series_names(timeline, [data.get("query", "")])
stats = data.get("stats") or {}
place, period = _place_name(geo or ""), _period_name(data.get("date", ""))
lines = []
if stats:
line = (
f"Interest in **{data['query']}** {('in ' + place) if place != 'worldwide' else 'worldwide'}, "
f"{period}: peaked at **{stats.get('peak'):.0f}** around {stats.get('peak_date')}, now at **{stats.get('latest'):.0f}**, "
f"average **{stats.get('average'):.0f}**."
)
change = stats.get("change_percent")
if change is not None:
direction = "up" if change > 5 else ("down" if change < -5 else "about flat")
line += f" Compared with the start of the period it's **{direction}**" + (
f" ({change:+.0f}%)." if direction != "about flat" else "."
)
lines.append(line)
regions = [r for r in data.get("interest_by_region") or [] if isinstance(r, dict)]
leaders = [r.get("location") for r in sorted(regions, key=lambda r: _num(r.get("extracted_value")) or 0, reverse=True)[:3]]
if leaders:
lines.append("Most popular in " + ", ".join(f"**{n}**" for n in leaders if n) + ".")
lines.append(f"{data.get('credits_used')} credits used.")
if data.get("warnings"):
lines.append("\n".join(f"- {w}" for w in data["warnings"]))
chart = render_chart(timeline, series)
extras = (
'
"
)
timeline_csv = _write_csv(_timeline_rows(timeline, series), "google-trends-timeline")
extras_csv = _write_csv(_extras_rows(data), "google-trends-regions-related")
return "\n\n".join(lines), chart, extras, data, timeline_csv, extras_csv
def run_compare(
token: str, keywords: str, geo: str, date: str, search_type: str
) -> Tuple[str, str, str, List[List[Any]], Dict[str, Any], Optional[str]]:
tool = _tool_or_none(token)
if tool is None:
return NO_TOKEN_MD, "", "", [], {}, None
if not keywords or not keywords.strip():
return "Enter two to five keywords separated by commas, e.g. `chatgpt, claude, gemini`.", "", "", [], {}, None
data = tool.compare(keywords, geo, date, search_type)
if data.get("status") != "success":
return _error_md(data), "", "", [], data, None
timeline = data.get("timeline") or []
series = _series_names(timeline, data.get("keywords") or [])
stats = data.get("stats") or {}
lines = []
if data.get("leader") and not data.get("scaled_separately"):
ranked = sorted(series, key=lambda s: (stats.get(s) or {}).get("average") or 0, reverse=True)
line = (
f"**{ranked[0]}** gets the most searches {('in ' + _place_name(geo or '')) if geo else 'worldwide'}, "
f"{_period_name(data.get('date', ''))}."
)
if len(ranked) > 1:
first = (stats.get(ranked[0]) or {}).get("average") or 0
second = (stats.get(ranked[1]) or {}).get("average") or 0
if second >= 1:
line += f" On average it's searched **{first / second:.1f}×** as much as **{ranked[1]}**."
lines.append(line)
lines.append(f"{data.get('credits_used')} credits used.")
if data.get("warnings"):
lines.append("\n".join(f"- {w}" for w in data["warnings"]))
table = []
for name in series:
s = stats.get(name) or {}
change = s.get("change_percent")
table.append([
name, s.get("average"), s.get("latest"), s.get("peak_date"),
f"{change:+.0f}%" if isinstance(change, (int, float)) else "",
])
table.sort(key=lambda r: r[1] or 0, reverse=True)
regions = [r for r in data.get("interest_by_region") or [] if isinstance(r, dict)]
extras = f'
{_region_bars(regions, series, limit=20)}
' if regions else ""
csv_path = _write_csv(_timeline_rows(timeline, series), "google-trends-compare")
return "\n\n".join(lines), render_chart(timeline, series), extras, table, data, csv_path
def render_trending(data: Dict[str, Any]) -> str:
cards = []
for position, trend in enumerate(data.get("trends") or [], start=1):
link = _safe_link(trend.get("trend_url"))
title = _esc(trend.get("title"))
title_html = (
f'{title}'
if link else f'{title}'
)
active = str(trend.get("status") or "").lower() == "active"
status = (
'● Active' if active
else 'Ended'
)
growth = _num(trend.get("growth_percentage"))
growth_html = f'↑ {growth:,.0f}%' if growth else ""
chips = "".join(f'{_esc(q)}' for q in (trend.get("related_queries") or [])[:6])
cats = " · ".join(_esc(c) for c in trend.get("categories") or [])
cards.append(
'
'
def run_trending(
token: str, geo: str, hours: int, category: int, sort: str, active_only: bool
) -> Tuple[str, str, Dict[str, Any], Optional[str]]:
tool = _tool_or_none(token)
if tool is None:
return NO_TOKEN_MD, "", {}, None
data = tool.trending(geo or "US", int(hours or 24), int(category or 0), sort or "relevance", bool(active_only))
if data.get("status") != "success":
return _error_md(data), "", data, None
trends = data.get("trends") or []
active = sum(1 for t in trends if str(t.get("status") or "").lower() == "active")
window = dict((v, k) for k, v in HOURS_CHOICES).get(data.get("hours"), f"past {data.get('hours')} hours").lower()
summary = (
f"**{len(trends)}** searches trending in **{_place_name(data.get('geo', ''))}**, {window}"
+ (f", in {data.get('category')}" if data.get("category") != "All categories" else "")
+ f" · **{active}** still active · {data.get('credits_used')} credits used"
)
rows = [
{
"rank": i,
"title": t.get("title"),
"search_volume": t.get("search_volume"),
"growth_percentage": t.get("growth_percentage"),
"status": t.get("status"),
"started_at": _iso(t.get("started_at")),
"ended_at": _iso(t.get("ended_at")),
"categories": ", ".join(t.get("categories") or []),
"related_queries": " | ".join(t.get("related_queries") or []),
"trend_url": t.get("trend_url"),
}
for i, t in enumerate(trends, start=1)
]
return summary, render_trending(data), data, _write_csv(rows, "google-trending-now")
# ----------------------------------------------------------------------- UI
STYLE = """
"""
HERO_ART = """
"""
TREND_ICON = (
''
)
HERO = f"""
{HERO_ART}
{TREND_ICON} Google Trends Scraper
Google Trends data as clean JSON and CSV: interest over time, interest by country or city,
rising and top related searches, keyword comparisons, and what's trending right now in any country.
The unofficial pytrends library is no longer maintained and Google's own Trends API is still invite-only.
This Space runs on the Scrape.do Google Trends API,
which handles Google's rate limits for you.
Every call costs 10 credits. Exploring a keyword is one call, plus one more each for related searches and
related topics. A comparison is one call, and trending searches are one call. The free 1,000 credits cover
about 100 calls.
"""
FOOTER_MD = f"""
---
### Use it as a smolagents Tool
```python
from smolagents import CodeAgent, InferenceClientModel
from tool import ScrapeDoGoogleTrendsTool
agent = CodeAgent(
tools=[ScrapeDoGoogleTrendsTool(api_token="YOUR_SCRAPEDO_TOKEN")],
model=InferenceClientModel(),
)
agent.run("Compare interest in ChatGPT, Claude and Gemini in the US over the past 12 months, then list what's trending in Technology right now.")
```
Or set `SCRAPE_DO_API_TOKEN` in the environment and instantiate with no arguments.
[Scrape.do](https://scrape.do/) · [Google Trends API docs](https://scrape.do/documentation/google-scraper-api/trends/) · [Sign up free]({SCRAPE_DO_SIGNUP_URL})
"""
def build_demo() -> gr.Blocks:
with gr.Blocks(title="Google Trends Scraper — Scrape.do") as demo:
gr.HTML(STYLE)
gr.HTML(HERO)
api_token = gr.Textbox(
label="Scrape.do API token",
placeholder="Paste your token here",
type="password",
info="Free tier: 1,000 credits a month, about 100 calls.",
)
gr.HTML(CREDIT_NOTE)
with gr.Tabs():
with gr.Tab("Explore a keyword"):
keyword = gr.Textbox(label="Keyword", placeholder="bitcoin")
with gr.Row():
ex_geo = gr.Dropdown(
label="Where", choices=COUNTRY_CHOICES, value="", allow_custom_value=True,
info="Or type a region code such as US-CA.",
)
ex_date = gr.Dropdown(
label="When", choices=DATE_CHOICES, value="today 12-m", allow_custom_value=True,
info="Or type a range: 2024-01-01 2024-12-31",
)
ex_type = gr.Dropdown(label="Search type", choices=SEARCH_TYPE_CHOICES, value="web")
with gr.Row():
ex_resolution = gr.Dropdown(label="Break down by", choices=RESOLUTION_CHOICES, value="")
want_queries = gr.Checkbox(label="Related searches (+10 credits)", value=True)
want_topics = gr.Checkbox(label="Related topics (+10 credits)", value=False)
explore_btn = gr.Button("Explore", variant="primary")
explore_summary = gr.Markdown()
explore_chart = gr.HTML()
explore_extras = gr.HTML()
with gr.Row():
explore_csv = gr.File(label="Interest over time (CSV)")
explore_extras_csv = gr.File(label="Regions and related searches (CSV)")
with gr.Accordion("Raw JSON response", open=False):
explore_json = gr.JSON()
with gr.Tab("Compare keywords"):
compare_terms = gr.Textbox(
label=f"Keywords to compare (2–{MAX_COMPARE}, separated by commas)",
placeholder="chatgpt, claude, gemini",
)
with gr.Row():
cmp_geo = gr.Dropdown(label="Where", choices=COUNTRY_CHOICES, value="", allow_custom_value=True)
cmp_date = gr.Dropdown(label="When", choices=DATE_CHOICES, value="today 12-m", allow_custom_value=True)
cmp_type = gr.Dropdown(label="Search type", choices=SEARCH_TYPE_CHOICES, value="web")
compare_btn = gr.Button("Compare", variant="primary")
compare_summary = gr.Markdown()
compare_chart = gr.HTML()
compare_table = gr.Dataframe(
headers=["Keyword", "Average", "Latest", "Peak", "Change"], wrap=True, label="Side by side"
)
compare_extras = gr.HTML()
compare_csv = gr.File(label="Download as CSV")
with gr.Accordion("Raw JSON response", open=False):
compare_json = gr.JSON()
with gr.Tab("Trending now"):
with gr.Row():
tr_geo = gr.Dropdown(label="Country", choices=TRENDING_COUNTRY_CHOICES, value="US", allow_custom_value=True)
tr_hours = gr.Dropdown(label="Time window", choices=HOURS_CHOICES, value=24)
tr_cat = gr.Dropdown(label="Category", choices=CATEGORY_CHOICES, value=0)
with gr.Row():
tr_sort = gr.Dropdown(label="Sort by", choices=SORT_CHOICES, value="relevance")
tr_active = gr.Checkbox(label="Only trends that are still active", value=False)
trending_btn = gr.Button("Show trending searches", variant="primary")
trending_summary = gr.Markdown()
trending_view = gr.HTML()
trending_csv = gr.File(label="Download as CSV")
with gr.Accordion("Raw JSON response", open=False):
trending_json = gr.JSON()
explore_inputs = [api_token, keyword, ex_geo, ex_date, ex_type, ex_resolution, want_queries, want_topics]
explore_outputs = [explore_summary, explore_chart, explore_extras, explore_json, explore_csv, explore_extras_csv]
explore_btn.click(fn=run_explore, inputs=explore_inputs, outputs=explore_outputs)
keyword.submit(fn=run_explore, inputs=explore_inputs, outputs=explore_outputs)
compare_inputs = [api_token, compare_terms, cmp_geo, cmp_date, cmp_type]
compare_outputs = [compare_summary, compare_chart, compare_extras, compare_table, compare_json, compare_csv]
compare_btn.click(fn=run_compare, inputs=compare_inputs, outputs=compare_outputs)
compare_terms.submit(fn=run_compare, inputs=compare_inputs, outputs=compare_outputs)
trending_inputs = [api_token, tr_geo, tr_hours, tr_cat, tr_sort, tr_active]
trending_outputs = [trending_summary, trending_view, trending_json, trending_csv]
trending_btn.click(fn=run_trending, inputs=trending_inputs, outputs=trending_outputs)
gr.Markdown(FOOTER_MD)
return demo
# Hugging Face Spaces launches the module-level `demo` object rather than
# calling launch() itself, so build it at import time.
demo = build_demo()
if __name__ == "__main__":
demo.launch()