内容
# 趋势监视
[](https://pypi.org/project/trendspyg/)
[](https://pepy.tech/projects/trendspyg)
[](https://www.python.org/downloads/)
[](https://github.com/flack0x/trendspyg/actions)
[](https://opensource.org/licenses/MIT)
用于谷歌趋势数据的Python库 - 实时趋势话题 **和** 关键词时间分析（时间兴趣，相关查询，地区兴趣）。一个现代的，积极维护的替代pytrends。
> **从编码代理使用此库？** 请参阅 [AGENTS.md](https://github.com/flack0x/trendspyg/blob/main/AGENTS.md) 以获取简洁的代理就绪参考。
## 安装
```bash
pip install trendspyg
# 带有异步支持
pip install trendspyg[async]
# 带有CLI
pip install trendspyg[cli]
# 带有MCP服务器（使用Claude和其他AI代理；Python 3.10+）
pip install trendspyg[mcp]
# 所有功能
pip install trendspyg[all]
```
## 快速入门
### RSS 源（快速，无需浏览器）
```python
from trendspyg import download_google_trends_rss
# 获取当前趋势和新闻文章
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']}")
```
### CSV 导出（综合 - 10秒）
```python
from trendspyg import download_google_trends_csv
# 获取480+趋势并过滤（需要Chrome）
df = download_google_trends_csv(
geo='US',
hours=168, # 过去7天
category='sports',
output_format='dataframe'
)
```
### 探索 - 时间兴趣（pytrends用例）
```python
from trendspyg import download_google_trends_interest_over_time
# 谷歌的0-100相对兴趣时间序列关键词（需要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}
```
```python
from trendspyg import download_google_trends_explore
# 全景：时间兴趣 + 相关查询 + 地区兴趣
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}
```
> 探索路径驱动一个真正的浏览器对抗谷歌的探索页面，并且 **速率限制敏感** （〜10-90秒每次调用，并重试）。将其用于分析，而不是高频率轮询 - 使用RSS路径进行快速，频繁的实时检查。
### 监视 - 实时监控（新版0.7.0）
```python
from trendspyg import watch_google_trends_rss
# 流式传输RSS快照之间的更改（安全连续轮询 - 仅RSS）
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, ...}
```
> 监视构建在快速RSS路径上，因此它可以安全地连续轮询（CSV和探索路径则不能）。如果您自己管理快照，也会导出纯`diff_trends(old, new)`助手。
### 异步（并行获取）
```python
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())
```
### CLI
```bash
trendspyg rss --geo US
trendspyg csv --geo US-CA --category sports --hours 168
trendspyg explore --keyword bitcoin --output csv
trendspyg watch --geo US --interval 60 --events new,volume_up
trendspyg list --type countries
```
### MCP 服务器 - 从Claude和AI代理使用trendspyg（新版0.8.0）
为任何MCP客户端（Claude Desktop，Claude Code，Cursor，...）提供实时的谷歌趋势工具 - 免费，本地，无需API密钥。需要Python 3.10+。
```bash
pip install trendspyg[mcp]
# Claude Code - 一条命令：
claude mcp add trendspyg -- trendspyg-mcp
```
Claude Desktop（`claude_desktop_config.json`）：
```json
{
"mcpServers": {
"trendspyg": { "command": "trendspyg-mcp" }
}
}
```
六种工具：`get_trending_now`，`compare_trending`，`get_trend_changes`（自上次检查发生了什么变化），`list_supported_options` - 所有快速且无需浏览器 - 加上`get_interest_over_time`和`get_trending_full`（驱动Chrome；较慢，诚实地向代理描述）。
## 数据源
| | RSS | CSV | 探索 |
|---|-----|-----|---------|
| 答案 | "当前趋势是什么？" | "当前趋势是什么？" | "X的兴趣如何变化？" |
| 速度 | 亚秒级\* | ~10秒 | ~10-90秒（速率限制敏感） |
| 输出 | 10-20个当前趋势 | 480+个当前趋势 | 时间兴趣，相关查询，地区 |
| 新闻文章 | 是 | 否 | 否 |
| 时间过滤 | 否 | 是（4小时/24小时/48小时/7天） | 是（任意时间范围） |
| 类别过滤 | 否 | 是（20个类别） | 是 |
| 需要Chrome | 否 | 是 | 是 |
\* 网络主导：〜0.2秒在低延迟链接上，〜1.4秒在高RTT连接上测量；缓存命中是瞬间的。每个路径的诚实测量数字生活在[基准测试/](https://github.com/flack0x/trendspyg/tree/main/benchmarks)。
> **监控：** `trendspyg watch` / `watch_google_trends_rss(...)` 轮询RSS路径并流式传输更改（新/删除/容量/排名） - 构建在RSS上，因此可以安全地连续轮询。
## 功能
- **实时趋势** 话题（RSS + CSV路径）和 **关键词时间分析** （探索路径）
- **实时监控** - `watch` 流式传输趋势变化为NDJSON（仅RSS，安全轮询）
- **时间兴趣，相关查询和地区兴趣** 适用于任何关键词 - pytrends核心用例
- **125个国家** + 51个美国州，**20个类别**，**4个趋势时间段** （4小时，24小时，48小时，7天）
- **输出格式**：字典，DataFrame，JSON，CSV（+ CSV路径上的Parquet）
- **异步支持** 并行获取
- **内置缓存** （5分钟TTL）
- **代理就绪**：类型化形状，`normalize=True`和JSON原生探索模式
- **MCP服务器** - `trendspyg-mcp` 为Claude和任何MCP客户端公开6种工具（无需API密钥）
- **CLI** 用于终端访问
- **稳定API** - 语义版本控制，带有书面合同： [STABILITY.md](https://github.com/flack0x/trendspyg/blob/main/STABILITY.md)
## 规范化输出（适用于代理和管道）
传递`normalize=True`以获取一个 **统一的，JSON原生模式** ，该模式对于RSS和CSV路径完全相同 - 无需学习两种不同的形状。
```python
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是一个真正的整数
```
每个趋势都有一个固定的，JSON安全模式：`keyword`，`rank`，`volume_text`，`volume_min`（整数），`started_at` / `ended_at`（ISO 8601或`None`），`is_active`，`related_queries`（列表），`news`（列表），`image`，`explore_url`。`normalize=True`适用于每个入口点 - RSS，CSV，异步和批处理函数（每个地理区域映射到其自己的信封） - 以及CLI（`trendspyg rss --geo US --normalize`）。它是可选的 - 默认输出保持不变。
## 缓存
```python
from trendspyg import clear_rss_cache, get_rss_cache_stats
# 默认情况下，结果缓存5分钟
trends = download_google_trends_rss(geo='US') # 网络调用
trends = download_google_trends_rss(geo='US') # 从缓存
# 跳过缓存
trends = download_google_trends_rss(geo='US', cache=False)
# 检查缓存统计信息
print(get_rss_cache_stats())
# 清除缓存
clear_rss_cache()
```
## 文档
- [API 参考](https://github.com/flack0x/trendspyg/blob/main/docs/API.md)
- [CLI 文档](https://github.com/flack0x/trendspyg/blob/main/CLI.md)
- [编码代理快速参考](https://github.com/flack0x/trendspyg/blob/main/AGENTS.md)
- [API稳定性政策](https://github.com/flack0x/trendspyg/blob/main/STABILITY.md)
- [基准测试](https://github.com/flack0x/trendspyg/tree/main/benchmarks)
- [变更日志](https://github.com/flack0x/trendspyg/blob/main/CHANGELOG.md)
- [示例](https://github.com/flack0x/trendspyg/tree/main/examples)
## 稳定性
trendspyg 是 **1.0** - 公共API遵循 [语义版本控制](https://semver.org/spec/v2.0.0.html) 在书面合同下：涵盖的内容（每个导出的名称，异常类型，CLI命令和标志，MCP工具，版本化数据模式），什么是破坏性更改以及如何处理弃用。诚实的边界：谷歌方面的是我们无法保证的 - 上游更改在补丁版本中修复。详细信息在 [STABILITY.md](https://github.com/flack0x/trendspyg/blob/main/STABILITY.md)。
## 要求
- Python 3.8+
- Chrome浏览器（适用于CSV和探索路径；RSS路径不需要）
## 许可证
MIT 许可证 - 有关详细信息，请参见 [LICENSE](https://github.com/flack0x/trendspyg/blob/main/LICENSE)。
## 链接
- [GitHub](https://github.com/flack0x/trendspyg)
- [PyPI](https://pypi.org/project/trendspyg/)
- [问题](https://github.com/flack0x/trendspyg/issues)
