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''] for level in (0, 25, 50, 75, 100): y = y_at(level) parts.append(f'') parts.append(f'{level}') stamps = [row.get("timestamp") or 0 for row in timeline] span_days = ((max(stamps) - min(stamps)) / 86400) if any(stamps) else 0 ticks = sorted({round(i * (count - 1) / 5) for i in range(6)}) if count > 1 else [0] for index in ticks: label = _axis_label(stamps[index], span_days, timeline[index].get("date")) anchor = "start" if index == 0 else ("end" if index == count - 1 else "middle") parts.append(f'{_esc(label)}') for position, name in enumerate(series): color = SERIES_COLORS[position % len(SERIES_COLORS)] points = [ (x_at(i), y_at(row["values"][name])) for i, row in enumerate(timeline) if row["values"].get(name) is not None ] if not points: continue path = " ".join(f"{x:.1f},{y:.1f}" for x, y in points) if len(series) == 1: area = f"{points[0][0]:.1f},{y_at(0):.1f} {path} {points[-1][0]:.1f},{y_at(0):.1f}" parts.append(f'') parts.append( f'' ) # Invisible hover strips: one per point, each with a native tooltip. for index, row in enumerate(timeline): x0 = max(left, x_at(index) - step / 2) w = min(step, width - right - x0) if count > 1 else plot_w detail = "; ".join( f"{name}: {row['values'][name]:.0f}" for name in series if row["values"].get(name) is not None ) parts.append( f'' f"{_esc(row.get('date'))} — {_esc(detail)}" ) parts.append("") 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 = ( '
' + _region_bars(regions, series) + _related_card(data.get("related_queries"), "queries") + "
" + _related_card(data.get("related_topics"), "topics") + "
" ) 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( '
' f'
{position}
' '
' f"{title_html}" f'
{_esc(_fmt_compact(trend.get("search_volume")))} searches' f"{growth_html}{status}" f'Started {_esc(_ago(trend.get("started_at")))}
' + (f'
{cats}
' if cats else "") + (f'
{chips}
' if chips else "") + "
" ) if not cards: cards.append('
Nothing is trending for these filters right now.
') return f'
{"".join(cards)}
' 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.

Get a free API token →
""" CREDIT_NOTE = """
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()