🌊 Gwelle: Native Google Trends Intelligence

gwelle is a lightweight Rust client for the Google Trends API.

Unlike tools that rely on browser automation, gwelle runs natively with reqwest, bootstraps session cookies, handles XSSI response wrappers, and deserializes payloads into typed Rust structs.

With sub-region mapping, real-time query support, and a built-in Model Context Protocol (MCP) sidecar, gwelle is suitable for ingestion pipelines and agent workflows.

⚡ Features

• Native Execution: No webdriver, Chrome, Puppeteer, or virtual-display requirement.
• Session + XSSI Handling: Uses native session bootstrapping and robust XSSI parsing for Trends API responses.
• MCP Support: Includes a stdio MCP server that summarizes Trends outputs for LLM tool use.
• Five-Dimensional Reporting: Cross-compare up to 5 keywords. Filter down by exact Geographic State (e.g. US-CA), Search Property (youtube, images), and Category ID targeting.

🦀 Installation (As a Rust Library)

Add this to your Cargo.toml:

[dependencies]
gwelle = "0.1.0"

🚀 Quick Start Example

Fetch the timeline curves for multiple keywords concurrently. gwelle maps exactly to the frontend Google Trends capabilities.

use gwelle::{TrendsClient, session};
use gwelle::models::{ExploreRequest, GeoResolution};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Bypass Bot Detection Invisibly
    let cookies = session::bootstrap_session().await?;
    let client = TrendsClient::new(&cookies, "en-US", -60)?;

    // 2. Configure Your Target Market
    let req = ExploreRequest {
        keywords: vec!["Rustlang".into(), "Python".into()],
        geo: "US-CA".into(),            // Target California specifically
        timeframe: "today 12-m".into(), // Last 12 Months
        category: 0,
        property: "".into(),            // "" = Web, "youtube" = YouTube
    };

    // 3. Fetch Unified Route Tokens
    let explore = client.explore(&req).await?;

    // 4. Download Regional Heatmaps & Timeline Series
    if let Some(token) = explore.interest_over_time {
        let curve_data = client.interest_over_time(&token).await?;
        println!("Received {} data points!", curve_data.timeline_data.len());
    }

    if let Some(token) = explore.related_queries {
        let trends = client.related_queries(&token).await?;
        for breakout in trends.rising {
            println!("Exploding Search: {} (+{})", breakout.query, breakout.value);
        }
    }

    Ok(())
}

🤖 Model Context Protocol (MCP) Mode

If you are orchestrating an Agentic AI platform (like Tectic, Claude Desktop, or OpenClaw), passing massive 54-week JSON structs into the LLM context window eats thousands of tokens and drastically slows down inference.

We ship gwelle-mcp, a native Rust sidecar that runs an analytical engine. It fetches data in the background, calculates the Peaks/Lows computationally, and exposes it over the Model Context Protocol seamlessly.

How to use

Add the binary path to your MCP Gateway registry:

{
  "mcpServers": {
    "gwelle-trends": {
      "command": "cargo",
      "args": ["run", "--bin", "gwelle-mcp"]
    }
  }
}

Your automated agents can call analyze_keyword_trend("Nvidia", "US") and receive compact, structured Markdown output:

## Google Trends Market Report

### Interest Over Time
**Keyword:** `Nvidia`
- Peak Volatility: 100/100 on Nov 16 – 22, 2025
- Lowest Point: 24/100 on Apr 5 – 11, 2026
- Macro Curve (Start -> Q1 -> Q2 -> Q3 -> End): 43 -> 36 -> 44 -> 54 -> 24

### Related Queries
**Rising / Breakout Topics:**
- crwv stock (Growth: +4,650%)
- coreweave stock (Growth: +2,600%)

🤝 Contributing

Found a payload schema change? Submit a PR! Make sure to keep strip_xssi implementations bracket-agnostic to handle arbitrary Google boundary shifts.

License

MIT License.

Made with ❤️ and 🤖 in Hamburg by NMA.vc