gwelle 0.1.0

Lightweight Rust client for the Google Trends API
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123

# 🌊 Gwelle: Native Google Trends Intelligence

[![Crates.io](https://img.shields.io/crates/v/gwelle.svg)](https://crates.io/crates/gwelle)
[![Documentation](https://docs.rs/gwelle/badge.svg)](https://docs.rs/gwelle)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

`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`:

```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.

```rust
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:

```json
{
  "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:

```markdown
## 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*