gtrends-cli 0.1.1

CLI tool for Google Trends data analysis and content suggestions

Google Trends CLI Tool

A powerful command-line tool for fetching and analyzing Google Trends data, with special features for content creators looking to identify what topics are worthy of writing about right now.

---

✨ Features

• 📈 Real-time Trends: Access trending searches with a simple command
• 🔍 Deep Analysis: Explore related topics and queries for any search term
• 📊 Comparative Insights: Compare interest across different topics and timeframes
• ✍️ Writer Suggestions: Get data-driven content ideas specifically for writers
• 📱 Geographic Analysis: See how trends vary by region, country, or city
• 📉 Independent Normalization: Track hundreds of topics with individual trend lines
• 📰 News Integration: Find trending topics with associated news articles
• 📁 Multiple Export Formats: Save data as CSV, JSON, or Excel files
• 🖼️ Visual Reporting: Generate trend visualizations (with matplotlib)

🚀 Installation

# From PyPI
pip install gtrends

# From source
git clone https://github.com/kitabtune/google-trends-cli
cd google-trends-cli
pip install -e .

💻 Quick Start

# Show trending searches
gtrends trending

# Get content suggestions for creators
gtrends suggest-topics

# Find writing opportunities
gtrends writing-opportunities

📖 Usage Examples

Basic Commands

# Show trending searches
gtrends trending

# Show trending searches with news articles
gtrends trending --with-news

# Show topics and queries related to a term
gtrends related "book publishing"

# Compare interest in multiple topics
gtrends compare "fiction books" "non-fiction books" "poetry"

# Get content suggestions for writers
gtrends suggest-topics --category=books

# Find writing opportunities
gtrends writing-opportunities "science fiction" "fantasy"

# Analyze growth patterns for topics (up to 500+ topics)
gtrends topic-growth "science fiction" "fantasy" "romance" "mystery" --period=24h

# Show geographic interest distribution
gtrends geo-interest "literature" --resolution=COUNTRY

# Search for category IDs
gtrends categories --find=book

# Search for location codes
gtrends geo "middle east"

# Show supported timeframe formats
gtrends help-timeframe

For Content Creators

Commands specially designed for content creators looking to identify trending topics:

# Get topic suggestions in the books category
gtrends suggest-topics --category=books --region=US

# Find specific writing opportunities based on rising trends
gtrends writing-opportunities "book publishing" "fiction" --count=10

# Compare interest in publishing trends over time with visualization
gtrends compare "self-publishing" "traditional publishing" --visualize

# Monitor rapid growth patterns for genres (independently normalized)
gtrends topic-growth "mystery" "thriller" "romance" "sci-fi" "fantasy" --period=7d 

Export Options

# Export trending searches to CSV (default)
gtrends trending --export

# Export to a specific location and format
gtrends suggest-topics --export --export-path="~/my-projects" --format=json

# Generate visualization (requires matplotlib)
gtrends compare "poetry" "prose" "fiction" --export --visualize

📋 Available Commands

Command	Description
trending	Show current trending searches
related	Find related topics and queries
suggest-topics	Get content creation suggestions
compare	Compare interest across topics
writing-opportunities	Find specific writing opportunities
topic-growth	Track growth for multiple topics
geo-interest	Analyze geographic distribution
categories	List available content categories
geo	Search for location codes
help-timeframe	Show timeframe format help

⚙️ Common Options

Option	Description
--region, -r	Region code (e.g., US, GB, AE)
--count, -n	Number of results to display
--timeframe, -t	Time range (e.g., 'now 1-d', 'today 3-m')
--export, -e	Export results to file
--export-path	Directory to save exported data
--format, -f	Export format (csv, json, xlsx)
--visualize, -v	Generate visualization

🕒 Timeframe Formats

Standard formats:    'now 1-H', 'today 3-m', 'today 12-m'
Custom intervals:    'now 123-H', 'today 45-d', 'today 18-m'
Date-based:          '2024-02-01 10-d', '2024-01-01 2024-12-31'
Hourly precision:    '2024-03-25T12 2024-03-25T15'
All available data:  'all'

📊 Example Outputs

📑 Full Documentation

For complete documentation on all commands and options:

# General help
gtrends --help

# Command-specific help
gtrends [COMMAND] --help

🛠️ Requirements

• Python 3.8+
• trendspy
• click
• pandas
• rich
• python-dateutil
• matplotlib (optional, for visualizations)
• pytest (for testing)
• pytest-cov (for test coverage)

🧪 Development

To set up the development environment:

# Clone the repository
git clone https://github.com/Nao-30/google-trends-cli
cd google-trends-cli

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Check test coverage
pytest --cov=gtrends tests/

Our test suite covers CLI commands, API functionality, content suggestions, formatting utilities, and helper functions. We welcome contributions to expand test coverage.

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

⚖️ License

This project is licensed under the MIT License - see the LICENSE file for details.

💖 Acknowledgements

• TrendsPy for Google Trends data access
• Click for the command-line interface
• Rich for beautiful terminal output
• KitabTune for project sponsorship