Metadata-Version: 2.4
Name: trendspyg
Version: 0.5.1
Summary: Free, open-source Python library for real-time Google Trends data with CLI and API - pytrends alternative with 188K+ configurations
Author-email: flack0x <ali.marodis2@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/flack0x/trendspyg
Project-URL: Documentation, https://github.com/flack0x/trendspyg#readme
Project-URL: Repository, https://github.com/flack0x/trendspyg
Project-URL: Issues, https://github.com/flack0x/trendspyg/issues
Project-URL: Changelog, https://github.com/flack0x/trendspyg/blob/main/CHANGELOG.md
Project-URL: Agent Reference, https://github.com/flack0x/trendspyg/blob/main/AGENTS.md
Keywords: google-trends,trends,pytrends,data-analysis,seo,marketing,analytics
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: selenium>=4.15.0
Requires-Dist: requests>=2.31.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-mock>=3.11.1; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: black>=23.7.0; extra == "dev"
Requires-Dist: flake8>=6.1.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Provides-Extra: cli
Requires-Dist: click>=8.0.0; extra == "cli"
Requires-Dist: tqdm>=4.65.0; extra == "cli"
Provides-Extra: async
Requires-Dist: aiohttp>=3.9.0; extra == "async"
Provides-Extra: analysis
Requires-Dist: pandas>=2.0.0; extra == "analysis"
Requires-Dist: pyarrow>=10.0.0; extra == "analysis"
Provides-Extra: all
Requires-Dist: click>=8.0.0; extra == "all"
Requires-Dist: tqdm>=4.65.0; extra == "all"
Requires-Dist: aiohttp>=3.9.0; extra == "all"
Requires-Dist: pandas>=2.0.0; extra == "all"
Requires-Dist: pyarrow>=10.0.0; extra == "all"
Dynamic: license-file

# trendspyg

[![PyPI version](https://img.shields.io/pypi/v/trendspyg.svg)](https://pypi.org/project/trendspyg/)
[![PyPI Downloads](https://static.pepy.tech/personalized-badge/trendspyg?period=total&units=none&left_color=black&right_color=green&left_text=downloads)](https://pepy.tech/projects/trendspyg)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![Tests](https://github.com/flack0x/trendspyg/actions/workflows/tests.yml/badge.svg)](https://github.com/flack0x/trendspyg/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Python library for downloading real-time Google Trends data. A modern alternative to the archived pytrends.

> **Using this library from a coding agent?** See [AGENTS.md](https://github.com/flack0x/trendspyg/blob/main/AGENTS.md) for a concise, agent-ready reference.

## Installation

```bash
pip install trendspyg

# With async support
pip install trendspyg[async]

# With CLI
pip install trendspyg[cli]

# All features
pip install trendspyg[all]
```

## Quick Start

### RSS Feed (Fast - 0.2s)

```python
from trendspyg import download_google_trends_rss

# Get current trends with news articles
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 Export (Comprehensive - 10s)

```python
from trendspyg import download_google_trends_csv

# Get 480+ trends with filtering (requires Chrome)
df = download_google_trends_csv(
    geo='US',
    hours=168,            # Past 7 days
    category='sports',
    output_format='dataframe'
)
```

### Async (Parallel Fetching)

```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 list --type countries
```

## Data Sources

| Feature | RSS | CSV |
|---------|-----|-----|
| Speed | 0.2s | ~10s |
| Trends | 5–25 (varies by region/time) | 480+ |
| News articles | Yes | No |
| Time filtering | No | Yes (4h/24h/48h/7d) |
| Category filter | No | Yes (20 categories) |
| Requires Chrome | No | Yes |

## Features

- **125 countries** + 51 US states
- **20 categories** (sports, tech, health, etc.)
- **4 time periods** (4h, 24h, 48h, 7 days)
- **4 output formats** (dict, DataFrame, JSON, CSV)
- **Async support** for parallel fetching
- **Built-in caching** (5-min TTL)
- **CLI** for terminal access

## Normalized output (for agents & pipelines)

Pass `normalize=True` to get one **unified, JSON-native schema** that is identical
for both the RSS and CSV paths — no need to learn two different shapes.

```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 is a real int
```

Every trend has a fixed, JSON-safe shape: `keyword`, `rank`, `volume_text`,
`volume_min` (int), `started_at` / `ended_at` (ISO 8601 or `None`), `is_active`,
`related_queries` (list), `news` (list), `image`, `explore_url`. `normalize=True`
works on every entry point — RSS, CSV, async, and the batch functions (each geo
then maps to its own envelope) — and on the CLI (`trendspyg rss --geo US --normalize`).
It is opt-in — default output is unchanged.

## Caching

```python
from trendspyg import clear_rss_cache, get_rss_cache_stats

# Results are cached for 5 minutes by default
trends = download_google_trends_rss(geo='US')  # Network call
trends = download_google_trends_rss(geo='US')  # From cache

# Bypass cache
trends = download_google_trends_rss(geo='US', cache=False)

# Check cache stats
print(get_rss_cache_stats())

# Clear cache
clear_rss_cache()
```

## Documentation

- [API Reference](https://github.com/flack0x/trendspyg/blob/main/docs/API.md)
- [CLI Documentation](https://github.com/flack0x/trendspyg/blob/main/CLI.md)
- [Coding-agent quick reference](https://github.com/flack0x/trendspyg/blob/main/AGENTS.md)
- [Changelog](https://github.com/flack0x/trendspyg/blob/main/CHANGELOG.md)
- [Examples](https://github.com/flack0x/trendspyg/tree/main/examples)

## Requirements

- Python 3.8+
- Chrome browser (for CSV export only)

## License

MIT License - see [LICENSE](https://github.com/flack0x/trendspyg/blob/main/LICENSE) for details.

## Links

- [GitHub](https://github.com/flack0x/trendspyg)
- [PyPI](https://pypi.org/project/trendspyg/)
- [Issues](https://github.com/flack0x/trendspyg/issues)
