pytrends-modern

https://github.com/yiromo/pytrends-modern
Admin
A modern Google Trends API library combining classic pytrends features with RSS feed support,...
Tokens:13,781
Snippets:114
Trust Score:5.1
License:MIT
Update:8 months ago
Show doc for...
Tokens:
Raw
### Install pytrends-modern

Source: https://github.com/yiromo/pytrends-modern/blob/main/examples/README.md

Installs the pytrends-modern library using pip. The '[all]' option installs optional dependencies.

```bash
pip install pytrends-modern

# Or with all optional dependencies
pip install pytrends-modern[all]
```

--------------------------------

### Clone Repository and Setup Development Environment

Source: https://github.com/yiromo/pytrends-modern/blob/main/CONTRIBUTING.md

Steps to clone the pytrends-modern repository, create and activate a virtual environment, and install development dependencies. This is the initial setup for contributing to the project.

```bash
git clone https://github.com/yiromo/pytrends-modern.git
cd pytrends-modern
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e ".[dev,all]"
```

--------------------------------

### Run Basic Usage Example

Source: https://github.com/yiromo/pytrends-modern/blob/main/examples/README.md

Executes the basic_usage.py script, demonstrating fundamental pytrends-modern functionalities.

```bash
python examples/basic_usage.py
```

--------------------------------

### Get Interest Over Time (CLI)

Source: https://github.com/yiromo/pytrends-modern/blob/main/examples/README.md

Command-line interface command to fetch interest over time data for specified keywords and timeframe using pytrends-modern.

```bash
pytrends-modern interest -k "Python,JavaScript" -t "today 12-m"
```

--------------------------------

### Run Advanced Usage Example

Source: https://github.com/yiromo/pytrends-modern/blob/main/examples/README.md

Executes the advanced_usage.py script, showcasing more complex features of pytrends-modern.

```bash
python examples/advanced_usage.py
```

--------------------------------

### Command-Line Interface (CLI) Examples

Source: https://github.com/yiromo/pytrends-modern/blob/main/README.md

This section provides examples of using the pytrends-modern command-line interface for various tasks. It covers fetching interest over time, trending searches, RSS feeds, and exporting data to CSV.

```bash
# Get interest over time
pytrends-modern interest --keywords "Python,JavaScript" --timeframe "today 12-m"

# Get trending searches
pytrends-modern trending --geo US

# Get RSS feed
pytrends-modern rss --geo US --format json

# Export to CSV
pytrends-modern interest --keywords "AI" --output trends.csv
```

--------------------------------

### Get Interest by Region (CLI)

Source: https://github.com/yiromo/pytrends-modern/blob/main/examples/README.md

Command-line interface command to retrieve interest by region data for a given keyword and geographic location using pytrends-modern.

```bash
pytrends-modern region -k "AI" -g "US" -r "REGION"
```

--------------------------------

### Get Interest Over Time (Python)

Source: https://github.com/yiromo/pytrends-modern/blob/main/examples/README.md

Fetches historical search interest for specified keywords over a given timeframe using pytrends-modern. Requires the pytrends_modern library.

```python
from pytrends_modern import TrendReq

pytrends = TrendReq()
pytrends.build_payload(['Python', 'JavaScript'], timeframe='today 12-m')
df = pytrends.interest_over_time()
print(df.head())
```

--------------------------------

### Batch Process Keywords (Python)

Source: https://github.com/yiromo/pytrends-modern/blob/main/examples/README.md

Iterates through a list of keywords, fetches interest over time for each, and calculates the average interest for each keyword. Stores the results in a dictionary.

```python
keywords = ['Python', 'JavaScript', 'Java']
results = {}

for kw in keywords:
    pytrends.build_payload([kw], timeframe='today 12-m')
    df = pytrends.interest_over_time()
    results[kw] = df[kw].mean()
```

--------------------------------

### Python Function with Google-Style Docstring Example

Source: https://github.com/yiromo/pytrends-modern/blob/main/CONTRIBUTING.md

Illustrates a Python function with a comprehensive Google-style docstring, including descriptions for parameters, return values, potential exceptions, and an example usage. This serves as a template for documenting functions.

```python
def my_function(param1: str, param2: int = 10) -> bool:
    """
    Short description of function
    
    Longer description if needed, explaining behavior,
    edge cases, etc. 
    
    Args:
        param1: Description of param1
        param2: Description of param2 with default
        
    Returns:
        Description of return value
        
    Raises:
        ValueError: When param1 is invalid
        
    Example:
        >>> result = my_function("test", param2=20)
        >>> print(result)
        True
    """
    pass
```

--------------------------------

### Get RSS Trends (CLI)

Source: https://github.com/yiromo/pytrends-modern/blob/main/examples/README.md

Command-line interface command to fetch real-time trending searches via RSS feed for a specified country using pytrends-modern. Supports different output formats.

```bash
pytrends-modern rss -g US --format table
```

--------------------------------

### Install pytrends-modern Packages

Source: https://github.com/yiromo/pytrends-modern/blob/main/README.md

Installs the pytrends-modern library with different sets of features. Use '[browser]' for Camoufox integration, '[selenium]' for Selenium support, '[cli]' for command-line interface, and '[all]' for all features.

```bash
pip install pytrends-modern

pip install pytrends-modern[browser]

pip install pytrends-modern[selenium]

pip install pytrends-modern[cli]

pip install pytrends-modern[all]
```

--------------------------------

### Configure Proxy and Retries (Python)

Source: https://github.com/yiromo/pytrends-modern/blob/main/examples/README.md

Initializes TrendReq with custom proxy settings and retry configurations for handling network issues. Specifies a list of proxies, number of retries, and backoff factor.

```python
pytrends = TrendReq(
    proxies=['https://proxy1.com:8080'],
    retries=3,
    backoff_factor=0.5
)
```

--------------------------------

### Get Interest by Region (Python)

Source: https://github.com/yiromo/pytrends-modern/blob/main/examples/README.md

Retrieves the geographic distribution of search interest for a keyword using pytrends-modern. Allows specifying the resolution (e.g., 'REGION').

```python
pytrends.build_payload(['Python'], geo='US')
df = pytrends.interest_by_region(resolution='REGION')
print(df.head())
```

--------------------------------

### Get Real-time Trending Searches (RSS) (Python)

Source: https://github.com/yiromo/pytrends-modern/blob/main/examples/README.md

Fetches real-time trending search topics quickly using the TrendsRSS class from pytrends-modern. Outputs a list of trends with titles and traffic information.

```python
from pytrends_modern import TrendsRSS

rss = TrendsRSS()
trends = rss.get_trends(geo='US')
for trend in trends[:5]:
    print(f"{trend['title']}: {trend['traffic']}")
```

--------------------------------

### Python Function with Type Hints and Docstring

Source: https://github.com/yiromo/pytrends-modern/blob/main/CONTRIBUTING.md

An example of a Python function demonstrating the use of type hints for parameters and return values, along with a Google-style docstring. This adheres to the project's development guidelines for code clarity and documentation.

```python
from typing import List
import pandas as pd

def get_trends(
    keywords: List[str],
    timeframe: str = 'today 12-m',
    geo: str = ''
) -> pd.DataFrame:
    """
    Get trend data for keywords
    
    Args:
        keywords: List of keywords to query
        timeframe: Time range for data
        geo: Geographic location
        
    Returns:
        DataFrame with trend data
    """
    pass
```

--------------------------------

### Pytest Example Test Function

Source: https://github.com/yiromo/pytrends-modern/blob/main/CONTRIBUTING.md

A basic example of a test function using pytest. It follows the Arrange-Act-Assert pattern for clarity and demonstrates how to write tests for new functionality.

```python
def test_my_feature():
    """Test description"""
    # Arrange
    input_data = "test"
    
    # Act
    result = my_function(input_data)
    
    # Assert
    assert result is True
```

--------------------------------

### Add Delay Between Requests (Python)

Source: https://github.com/yiromo/pytrends-modern/blob/main/examples/README.md

Demonstrates adding a delay between API requests using Python's time module to avoid rate limiting issues with services like Google Trends.

```python
import time
time.sleep(1)  # Wait 1 second between requests
```

--------------------------------

### Implement Error Handling (Python)

Source: https://github.com/yiromo/pytrends-modern/blob/main/examples/README.md

Shows how to wrap API calls in a try-except block to gracefully handle potential exceptions and errors during data fetching with pytrends-modern.

```python
try:
    df = pytrends.interest_over_time()
except Exception as e:
    print(f"Error: {e}")
```

--------------------------------

### Export Data via CLI (CLI)

Source: https://github.com/yiromo/pytrends-modern/blob/main/examples/README.md

Command-line interface commands to export trend data to files in various formats like CSV or JSON using pytrends-modern.

```bash
pytrends-modern interest -k "Python" -o trends.csv
pytrends-modern rss -g GB -o trends.json --format json
```

--------------------------------

### Check for Empty DataFrame (Python)

Source: https://github.com/yiromo/pytrends-modern/blob/main/examples/README.md

Illustrates how to check if a pandas DataFrame is empty before processing its data, preventing potential errors when no data is returned by an API call.

```python
if not df.empty:
    # Process data
    pass
```

--------------------------------

### Analyze Trend Momentum and Spikes (Python)

Source: https://github.com/yiromo/pytrends-modern/blob/main/examples/README.md

Utilizes utility functions from pytrends_modern.utils to calculate trend momentum and detect significant spikes in search interest for a given keyword. Requires a DataFrame containing interest over time data.

```python
from pytrends_modern.utils import calculate_trend_momentum, detect_trend_spikes

pytrends.build_payload(['ChatGPT'], timeframe='today 12-m')
df = pytrends.interest_over_time()

# Calculate momentum
momentum = calculate_trend_momentum(df, 'ChatGPT', window=7)

# Detect spikes
spikes = detect_trend_spikes(df, 'ChatGPT', threshold=2.0)
```

--------------------------------

### Manage Camoufox Profile via Command Line

Source: https://github.com/yiromo/pytrends-modern/blob/main/README.md

Provides command-line interface commands for managing the Camoufox browser profile used by pytrends-modern. This includes checking the profile status, running the initial setup, exporting the profile for use on other machines, and importing a profile.

```bash
# Check profile status
python -m pytrends_modern.camoufox_setup status

# Run setup (opens browser for Google login)
python -m pytrends_modern.camoufox_setup

# Export profile for Docker/other machines
python -m pytrends_modern.camoufox_setup export camoufox-profile.tar.gz

# Import profile on another machine
python -m pytrends_modern.camoufox_setup import camoufox-profile.tar.gz
```

--------------------------------

### Retrieve and Analyze Interest Over Time Data

Source: https://context7.com/yiromo/pytrends-modern/llms.txt

Fetches historical search interest data for keywords over a specified period and exports it to a CSV file. Provides examples of different timeframe options.

```python
from pytrends_modern import TrendReq

pytrends = TrendReq(hl='en-US', tz=360)

# Compare multiple keywords over the past year
pytrends.build_payload(
    kw_list=['Python', 'JavaScript', 'Rust'],
    timeframe='today 12-m',
    geo='US'
)

df = pytrends.interest_over_time()

# Analyze the data
print(f"Data points: {len(df)}")
print(f"Date range: {df.index.min()} to {df.index.max()}")
print(f"\nAverage interest:")
for col in df.columns:
    if col != 'isPartial':
        print(f"  {col}: {df[col].mean():.2f}")

# Export to CSV
df.to_csv('trends_comparison.csv')

# Timeframe options:
# 'now 1-H'    - Last hour
# 'now 4-H'    - Last 4 hours
# 'now 1-d'    - Last day
# 'now 7-d'    - Last 7 days
# 'today 1-m'  - Past 30 days
# 'today 3-m'  - Past 90 days
# 'today 12-m' - Past 12 months
# 'today 5-y'  - Past 5 years
# 'all'        - Since 2004
# '2023-01-01 2023-12-31' - Custom date range
```

--------------------------------

### Export Data to Multiple Formats (Python)

Source: https://github.com/yiromo/pytrends-modern/blob/main/examples/README.md

Exports a pandas DataFrame to CSV, JSON, and Parquet formats using the export_to_multiple_formats utility function from pytrends_modern.utils. Returns a list of file paths for the exported files.

```python
from pytrends_modern.utils import export_to_multiple_formats

paths = export_to_multiple_formats(
    df,
    'my_trends',
    formats=['csv', 'json', 'parquet']
)
```

--------------------------------

### Export Data to Various Formats

Source: https://github.com/yiromo/pytrends-modern/blob/main/README.md

This Python code illustrates how to export Google Trends data obtained through the library into different file formats. It shows examples for CSV, JSON, Parquet, and Excel, highlighting the flexibility in data storage and sharing.

```python
# Export to various formats
df = pytrends.interest_over_time()

# CSV
df.to_csv('trends.csv')

# JSON
pytrends.to_json('trends.json')

# Parquet (requires pyarrow)
pytrends.to_parquet('trends.parquet')

# Excel (requires openpyxl)
df.to_excel('trends.xlsx')
```

--------------------------------

### Browser Mode with Camoufox for Bypassing Rate Limits

Source: https://context7.com/yiromo/pytrends-modern/llms.txt

Utilizes Camoufox for advanced browser automation, bypassing Google rate limits by mimicking human behavior and using fingerprinting. Requires a one-time Google account login setup. Note limitations: only 1 keyword, 'today 1-m' timeframe, and worldwide geo.

```python
from pytrends_modern import TrendReq, BrowserConfig
from pytrends_modern.camoufox_setup import setup_profile, is_profile_configured

# First-time setup (run once) - opens browser for Google login
if not is_profile_configured():
    setup_profile()  # Interactive browser login

# Configure browser mode
config = BrowserConfig(
    headless=False,          # Show browser (or True/'virtual' for Docker)
    humanize=True,           # Human-like cursor movements
    os='windows',            # Fingerprint OS: 'windows', 'macos', 'linux'
    geoip=True,              # Auto-detect location from IP
    min_delay=2.0,           # Min delay between requests (seconds)
    max_delay=5.0,           # Max delay between requests
    persistent_context=True  # Keep login session
)

# With proxy support
config_proxy = BrowserConfig(
    headless=True,
    proxy_server='http://proxy.com:8080',
    proxy_username='user',
    proxy_password='pass',
    geoip=True
)

# Initialize with browser mode
pytrends = TrendReq(browser_config=config)

# LIMITATIONS in browser mode:
# - Only 1 keyword at a time (no comparisons)
# - Only 'today 1-m' timeframe
# - Only WORLDWIDE geo

# Set keyword directly (browser mode)
pytrends.kw_list = ['ChatGPT']

# Get data (uses your Google account - no rate limits!)
df_time = pytrends.interest_over_time()
df_region = pytrends.interest_by_region()
topics = pytrends.related_topics()
queries = pytrends.related_queries()

print(df_time.head())
```

--------------------------------

### Fetch Real-Time Trending Searches via RSS Feed

Source: https://github.com/yiromo/pytrends-modern/blob/main/README.md

This Python snippet demonstrates how to use the TrendsRSS class to fetch real-time trending search data. It retrieves trending topics for a specified region (US in this example) and prints details like title, traffic, number of articles, and associated image.

```python
from pytrends_modern import TrendsRSS

# Get trending searches with rich media
rss = TrendsRSS()
trends = rss.get_trends(geo='US')

for trend in trends:
    print(f"Title: {trend['title']}")
    print(f"Traffic: {trend['traffic']}")
    print(f"Articles: {len(trend['articles'])}")
    print(f"Image: {trend['picture']}")
    print("---")
```

--------------------------------

### Use Custom Date Ranges (Python)

Source: https://github.com/yiromo/pytrends-modern/blob/main/examples/README.md

Constructs a custom timeframe string for pytrends-modern requests using Python's datetime module and the convert_dates_to_timeframe utility function. This allows for precise control over the date range of the trend data.

```python
from datetime import date, timedelta
from pytrends_modern.utils import convert_dates_to_timeframe

end_date = date.today()
start_date = end_date - timedelta(days=180)
timeframe = convert_dates_to_timeframe(start_date, end_date)

pytrends.build_payload(['AI'], timeframe=timeframe)
df = pytrends.interest_over_time()
```

--------------------------------

### Get Trending Searches with pytrends-modern

Source: https://context7.com/yiromo/pytrends-modern/llms.txt

Fetches current trending searches for a specified country, including daily and real-time trends. This function requires the pytrends_modern library and returns a pandas DataFrame.

```python
from pytrends_modern import TrendReq

pytrends = TrendReq()

# Get trending searches for a country
df = pytrends.trending_searches(pn='united_states')
print("Current trending searches in the US:")
print(df.head(20))

# Available countries include:
# 'united_states', 'united_kingdom', 'canada', 'australia',
# 'germany', 'france', 'japan', 'brazil', 'india', etc.

# Get today's daily trends
df_today = pytrends.today_searches(pn='US')
print("\nToday's trending searches:")
print(df_today.head())

# Get real-time trending searches
df_realtime = pytrends.realtime_trending_searches(pn='US', count=50)
print("\nReal-time trends:")
print(df_realtime)
```

--------------------------------

### Python Browser Mode with Camoufox for Rate Limit Bypassing

Source: https://github.com/yiromo/pytrends-modern/blob/main/README.md

Utilizes pytrends-modern's browser mode with Camoufox to bypass Google's rate limits by using a persistent Google account login. It requires an initial setup to configure the profile and then allows for normal API usage without rate restrictions.

```python
from pytrends_modern import TrendReq, BrowserConfig
from pytrends_modern.camoufox_setup import setup_profile

# First-time setup: Configure Google account login
setup_profile()  # Opens browser - log in to Google once

# Use browser mode (persistent login, no rate limits!)
config = BrowserConfig(headless=False)
pytrends = TrendReq(browser_config=config)

# Works like normal API
pytrends.kw_list = ['Python']
df = pytrends.interest_over_time()
print(df.head())
```

--------------------------------

### Run Tests with Pytest

Source: https://github.com/yiromo/pytrends-modern/blob/main/README.md

Provides command-line instructions for running tests using the pytest framework. It covers basic test execution, running tests with code coverage, and targeting specific test files or functions.

```bash
# Run tests
pytest

# With coverage
pytest --cov=pytrends_modern

# Specific test
pytest tests/test_request.py::test_interest_over_time
```

--------------------------------

### Run Tests and Linting

Source: https://github.com/yiromo/pytrends-modern/blob/main/CONTRIBUTING.md

Commands to execute the test suite using pytest, including running tests with code coverage. Also includes commands for linting and type checking the codebase using Black, Ruff, and Mypy.

```bash
pytest
pytest --cov=pytrends_modern
black pytrends_modern/
ruff check pytrends_modern/
mypy pytrends_modern/
```

--------------------------------

### CLI Usage for Google Trends Data (Bash)

Source: https://context7.com/yiromo/pytrends-modern/llms.txt

Demonstrates various command-line interface commands for fetching Google Trends data, including interest over time, regional data, trending searches, and keyword suggestions. Supports different output formats.

```bash
# Get interest over time for multiple keywords
pytrends-modern interest --keywords "Python,JavaScript" --timeframe "today 12-m" --geo US

# Export interest over time data to a CSV file
pytrends-modern interest -k "AI" -t "today 12-m" -o trends.csv

# Get interest by region
pytrends-modern region -k "Python" -g "US" -r "REGION" -f table

# Get trending searches from RSS feed in JSON format and export to file
pytrends-modern rss --geo US --format json -o trends.json

# Get worldwide trending searches
pytrends-modern trending --country united_states

# Get keyword suggestions
pytrends-modern suggest -k "machine learning"

# Available output formats: csv, json, table
```

--------------------------------

### Configure Browser for Virtual Display (Docker)

Source: https://github.com/yiromo/pytrends-modern/blob/main/README.md

This configuration sets up the browser to run in a virtual display mode, suitable for Docker containers. It utilizes Xvfb for headless rendering, which is essential when a physical display is not available.

```python
config = BrowserConfig(headless="virtual")  # Use Xvfb for Docker
```

--------------------------------

### Initialize Trends Scraper

Source: https://context7.com/yiromo/pytrends-modern/llms.txt

Initializes the TrendsScraper to fetch trending searches. It can run headlessly and allows for an optional custom download directory. The scraper should be closed after use, or preferably used within a context manager.

```python
from pytrends_modern import TrendsScraper

# Initialize scraper (downloads Chrome driver automatically)
scraper = TrendsScraper(
    headless=True,          # Run browser headlessly
    download_dir=None       # Optional custom download directory
)

try:
    # Get trending searches with filtering options
    df = scraper.trending_searches(
        geo='US',                  # Country code
        hours=24,                  # Time period: 4, 24, 48, 168
        category='all',            # all, business, entertainment, health, science, sports
        return_df=True             # Return DataFrame (False returns CSV path)
    )

    print(f"Found {len(df)} trending searches")
    print(df.head())

    # Shortcut methods
    df_today = scraper.today_searches(geo='US')
    df_realtime = scraper.realtime_trending_searches(geo='US', hours=4)

finally:
    scraper.close()

# Or use context manager
with TrendsScraper(headless=True) as scraper:
    df = scraper.trending_searches(geo='GB', hours=24)
    print(df)
```

--------------------------------

### Initialize TrendReq Client and Build Payload

Source: https://context7.com/yiromo/pytrends-modern/llms.txt

Demonstrates initializing the TrendReq client with custom settings and building a payload for Google Trends API requests. Includes error handling for rate limiting.

```python
from pytrends_modern import TrendReq
from pytrends_modern.exceptions import TooManyRequestsError

# Initialize with custom settings
pytrends = TrendReq(
    hl='en-US',          # Language
    tz=360,              # Timezone offset in minutes
    geo='',              # Default geographic location
    timeout=(10, 25),    # (connect, read) timeouts
    retries=3,           # Retry attempts on failure
    backoff_factor=0.5,  # Exponential backoff multiplier
    rotate_user_agent=True  # Rotate user agents
)

# Build payload for search queries
pytrends.build_payload(
    kw_list=['Python', 'JavaScript'],  # Max 5 keywords
    cat=0,                              # Category (0 = all)
    timeframe='today 12-m',             # Time range
    geo='US',                           # Geographic filter
    gprop=''
)

# Get interest over time
try:
    df = pytrends.interest_over_time()
    print(df.head())
except TooManyRequestsError:
    print("Rate limited - try again later or use proxies")
```

--------------------------------

### Configure Proxies for TrendReq

Source: https://github.com/yiromo/pytrends-modern/blob/main/README.md

Demonstrates how to configure proxy servers for the TrendReq object, either as a list of URLs or a dictionary mapping protocols to proxy addresses. This is useful for managing requests from different IP addresses.

```python
from pytrends_modern import TrendReq

# List of proxies
pytrends = TrendReq(
    proxies=['https://proxy1.com:8080', 'https://proxy2.com:8080'],
    retries=3
)

# Dict format
pytrends = TrendReq(
    proxies={
        'http': 'http://proxy.com:8080',
        'https': 'https://proxy.com:8080'
    }
)
```

--------------------------------

### Batch Process Keywords for Google Trends

Source: https://github.com/yiromo/pytrends-modern/blob/main/README.md

Demonstrates how to process multiple keywords in batches to retrieve their interest over time data. It includes a `time.sleep(2)` call within the loop to prevent hitting rate limits, ensuring stable data collection for a list of keywords.

```python
from pytrends_modern import TrendReq
import time

keywords = ['Python', 'JavaScript', 'Rust', 'Go', 'Java']
pytrends = TrendReq()

results = {}
for kw in keywords:
    pytrends.build_payload([kw], timeframe='today 12-m')
    results[kw] = pytrends.interest_over_time()
    time.sleep(2)  # Avoid rate limits
```

--------------------------------

### Utility Functions for Date Conversion, Trend Analysis, and Export

Source: https://context7.com/yiromo/pytrends-modern/llms.txt

Includes helper functions for converting date ranges to the required timeframe format, calculating trend momentum, detecting significant spikes in trends, merging trend data, and exporting data to multiple file formats.

```python
from datetime import date, timedelta
from pytrends_modern import TrendReq
from pytrends_modern.utils import (
    convert_dates_to_timeframe,
    calculate_trend_momentum,
    detect_trend_spikes,
    export_to_multiple_formats,
    merge_trends_data
)

pytrends = TrendReq()

# Convert dates to timeframe string
end_date = date.today()
start_date = end_date - timedelta(days=180)
timeframe = convert_dates_to_timeframe(start_date, end_date)
# Result: '2024-01-15 2024-07-15'

# Build payload with custom dates
pytrends.build_payload(['ChatGPT'], timeframe=timeframe)
df = pytrends.interest_over_time()

# Calculate trend momentum (rate of change)
momentum = calculate_trend_momentum(df, 'ChatGPT', window=7)
print(f"Recent momentum:\n{momentum.tail()}")
print(f"Average momentum: {momentum.mean():.2f}%")

# Detect significant spikes (>2 std dev above mean)
spikes = detect_trend_spikes(df, 'ChatGPT', threshold=2.0)
print(f"\nFound {len(spikes)} spike periods:")
print(spikes)

# Export to multiple formats at once
paths = export_to_multiple_formats(
    df,
    base_path='chatgpt_trends',
    formats=['csv', 'json', 'parquet', 'xlsx']
)
print(f"\nExported files: {paths}")
```

--------------------------------

### Retrieve Interest by Region Data

Source: https://context7.com/yiromo/pytrends-modern/llms.txt

Fetches geographic distribution of search interest for given keywords. Demonstrates retrieving data at country and US state level, with options for resolution and including low volume regions or geo codes.

```python
from pytrends_modern import TrendReq

pytrends = TrendReq()

# Get US state-level interest
pytrends.build_payload(['AI'], geo='US', timeframe='today 12-m')
df_states = pytrends.interest_by_region(
    resolution='REGION',     # COUNTRY, REGION, CITY, DMA
    inc_low_vol=False,       # Include low search volume regions
    inc_geo_code=True        # Include geo codes in output
)

print("Top 10 US states for 'AI' searches:")
print(df_states.sort_values(by='AI', ascending=False).head(10))

# Get worldwide country-level interest
pytrends.build_payload(['Machine Learning'], geo='', timeframe='today 12-m')
df_countries = pytrends.interest_by_region(resolution='COUNTRY')

print("\nTop countries for 'Machine Learning':")
print(df_countries.sort_values(by='Machine Learning', ascending=False).head(10))
```

--------------------------------

### Create Feature Branch and Commit Changes

Source: https://github.com/yiromo/pytrends-modern/blob/main/CONTRIBUTING.md

Instructions for creating a new branch for feature development, making code changes, staging, and committing them with a descriptive message. This is part of the pull request workflow.

```bash
git checkout -b feature/my-new-feature
# Make your changes
git add .
git commit -m "Add feature: description"
```

--------------------------------

### Docker Usage: Export and Import Camoufox Profile

Source: https://github.com/yiromo/pytrends-modern/blob/main/README.md

Details the process of using pytrends-modern's Camoufox browser profile within a Docker container. It involves exporting the profile locally and then copying and extracting it into the appropriate directory within the Dockerfile to maintain persistent login across container instances.

```bash
# 1. Export profile locally
python -m pytrends_modern.camoufox_setup export profile.tar.gz

# 2. Use in Dockerfile
COPY profile.tar.gz /tmp/
RUN mkdir -p /root/.config && \
    cd /root/.config && \
    tar -xzf /tmp/profile.tar.gz
```

--------------------------------

### Fetch Comprehensive Trending Searches via Selenium

Source: https://github.com/yiromo/pytrends-modern/blob/main/README.md

Shows how to use the TrendsScraper class with Selenium to retrieve a complete list of trending searches, including support for categories and filters. This method is slower but provides more extensive data compared to the RSS feed option.

```python
from pytrends_modern import TrendsScraper

scraper = TrendsScraper(headless=True)
df = scraper.trending_searches(geo='US', hours=24)  # ~15s, returns 400+ trends
scraper.close()
```

--------------------------------

### Initialize TrendReq Class

Source: https://github.com/yiromo/pytrends-modern/blob/main/README.md

This code snippet shows the initialization of the TrendReq class, which is the primary interface for accessing Google Trends data. It outlines key parameters such as language, timezone, geographic location, timeouts, proxies, and retry settings.

```python
TrendReq(
    hl='en-US',          # Language
    tz=360,              # Timezone offset
    geo='',              # Geographic location
    timeout=(2, 5),      # (connect, read) timeouts
    proxies=None,        # Proxy list or dict
    retries=3,           # Number of retries
    backoff_factor=0.3,  # Backoff multiplier
    verify_ssl=True      # SSL verification
)
```

--------------------------------

### Release Process Commands

Source: https://github.com/yiromo/pytrends-modern/blob/main/CONTRIBUTING.md

Commands for releasing a new version of the pytrends-modern package. This includes updating version numbers, generating a git tag, building the package, and uploading it to PyPI.

```bash
# Update version in pyproject.toml and __init__.py
# Update CHANGELOG.md
# Run full test suite
git tag v1.0.0
git push origin v1.0.0
python -m build
python -m twine upload dist/*
```

--------------------------------

### Basic pytrends-modern Usage in Python

Source: https://github.com/yiromo/pytrends-modern/blob/main/README.md

Demonstrates the basic usage of pytrends-modern to fetch Google Trends data. It initializes the TrendReq object, builds a payload with keywords, timeframe, and region, and then retrieves interest over time, interest by region, and related queries.

```python
from pytrends_modern import TrendReq

# Initialize
pytrends = TrendReq(hl='en-US', tz=360)

# Build payload
pytrends.build_payload(
    kw_list=['Python', 'JavaScript'],
    timeframe='today 12-m',
    geo='US'
)

# Get interest over time
interest_df = pytrends.interest_over_time()
print(interest_df.head())

# Get interest by region
region_df = pytrends.interest_by_region()
print(region_df.head())

# Get related queries
related = pytrends.related_queries()
print(related['Python']['top'])
```

--------------------------------

### AsyncTrendReq - Async API Client for Concurrent Requests

Source: https://context7.com/yiromo/pytrends-modern/llms.txt

Provides asynchronous support using Camoufox's async API for concurrent Google Trends data fetching. Ideal for high-performance applications. Note that async mode also only supports 1 keyword.

```python
import asyncio
from pytrends_modern import AsyncTrendReq, BrowserConfig

async def get_trends():
    config = BrowserConfig(headless=True)

    async with AsyncTrendReq(browser_config=config) as pytrends:
        # Set keyword (async mode only supports 1 keyword)
        pytrends.kw_list = ['Python']

        # Get data asynchronously
        df_time = await pytrends.interest_over_time()
        df_region = await pytrends.interest_by_region()
        topics = await pytrends.related_topics()
        queries = await pytrends.related_queries()

        return df_time, df_region, topics, queries

# Run async function
df_time, df_region, topics, queries = asyncio.run(get_trends())
print(df_time.head())
```

--------------------------------

### Submit Pull Request

Source: https://github.com/yiromo/pytrends-modern/blob/main/CONTRIBUTING.md

Steps to push the feature branch to the remote repository and initiate a pull request on GitHub. This is the final step in submitting contributions.

```bash
git push origin feature/my-new-feature
```

--------------------------------

### Asynchronous Google Trends Data Fetching

Source: https://github.com/yiromo/pytrends-modern/blob/main/README.md

Shows how to fetch Google Trends data asynchronously using AsyncTrendReq. This allows for non-blocking operations, improving performance in applications that require concurrent data retrieval. It requires the asyncio library.

```python
import asyncio
from pytrends_modern import AsyncTrendReq

async def get_trends():
    pytrends = AsyncTrendReq(hl='en-US')
    await pytrends.build_payload(['Python', 'JavaScript'])
    df = await pytrends.interest_over_time()
    return df

df = asyncio.run(get_trends())
```

--------------------------------

### Scrape Comprehensive Trends with TrendsScraper

Source: https://context7.com/yiromo/pytrends-modern/llms.txt

Utilizes Selenium for browser automation to download extensive trending data (400+ trends), especially useful when API endpoints are unavailable. Supports category and filter options. Requires the TrendsScraper class from pytrends_modern.

```python
from pytrends_modern import TrendsScraper
```

--------------------------------

### Python Exception Handling with Custom Exception

Source: https://github.com/yiromo/pytrends-modern/blob/main/CONTRIBUTING.md

Demonstrates error handling in Python using a custom exception, `InvalidParameterError`, from the `exceptions.py` module. It shows how to raise and handle specific errors with informative messages.

```python
from pytrends_modern.exceptions import InvalidParameterError

def validate_input(value: str) -> str:
    if not value:
        raise InvalidParameterError(
            "Value cannot be empty. Please provide a valid string."
        )
    return value.upper()
```

--------------------------------

### Exception Handling in pytrends-modern (Python)

Source: https://context7.com/yiromo/pytrends-modern/llms.txt

Demonstrates how to catch specific exceptions raised by pytrends-modern, such as TooManyRequestsError, ResponseError, InvalidParameterError, BrowserError, and DownloadError, for robust error management.

```python
from pytrends_modern import TrendReq
from pytrends_modern.exceptions import (
    TooManyRequestsError,
    ResponseError,
    InvalidParameterError,
    BrowserError,
    DownloadError,
    ConfigurationError
)

pytrends = TrendReq()

# Example for InvalidParameterError (e.g., too many keywords)
try:
    pytrends.build_payload(['keyword1', 'keyword2', 'keyword3', 'keyword4',
                           'keyword5', 'keyword6'],  # Too many keywords!
                          timeframe='today 12-m')
except InvalidParameterError as e:
    print(f"Invalid parameter: {e}")

# Example for other common errors
try:
    pytrends.build_payload(['Python'], timeframe='today 12-m')
    df = pytrends.interest_over_time()
except TooManyRequestsError as e:
    print(f"Rate limited: {e}")
    print("Consider using proxies or browser mode")
except ResponseError as e:
    print(f"API error: {e}")
    if e.response:
        print(f"Status code: {e.response.status_code}")
except BrowserError as e:
    print(f"Browser automation failed: {e}")
except DownloadError as e:
    print(f"Download failed: {e}")
except ConfigurationError as e:
    print(f"Configuration error: {e}")
```

--------------------------------

### Proxy and Rate Limit Handling with pytrends-modern (Python)

Source: https://context7.com/yiromo/pytrends-modern/llms.txt

Configures pytrends-modern to use proxy servers for rotation or a static proxy, and sets the number of retries and backoff factor to handle rate limiting. Includes batch processing with error handling for TooManyRequestsError.

```python
from pytrends_modern import TrendReq
from pytrends_modern.exceptions import TooManyRequestsError
import time

# Option 1: Using a list of proxies for automatic rotation
pytrends_rotating = TrendReq(
    proxies=[
        'https://proxy1.com:8080',
        'https://proxy2.com:8080',
        'https://proxy3.com:8080'
    ],
    retries=5,
    backoff_factor=0.5
)

# Option 2: Using a dictionary for a static proxy configuration
pytrends_static = TrendReq(
    proxies={
        'http': 'http://user:pass@proxy.com:8080',
        'https': 'http://user:pass@proxy.com:8080'
    }
)

# Batch processing with rate limit handling
keywords = ['Python', 'JavaScript', 'Rust', 'Go', 'Java']
results = {}

pytrends = TrendReq(retries=3, backoff_factor=0.2) # Example with default settings

for kw in keywords:
    try:
        pytrends.build_payload([kw], timeframe='today 12-m')
        df = pytrends.interest_over_time()
        results[kw] = df[kw].mean() # Example: calculate mean interest
        time.sleep(2)  # Polite delay between requests
    except TooManyRequestsError:
        print(f"Rate limited on {kw}, waiting...")
        time.sleep(60)  # Wait before retry
    except Exception as e:
        print(f"Error for {kw}: {e}")
        results[kw] = 0 # Assign a default value on error

print("Results:", results)
```

--------------------------------

### Handle Google Trends Rate Limits

Source: https://github.com/yiromo/pytrends-modern/blob/main/README.md

Illustrates how to implement rate limit handling for Google Trends requests using the `retries` and `backoff_factor` parameters in TrendReq. It includes a try-except block to catch `TooManyRequestsError` and provide feedback.

```python
from pytrends_modern import TrendReq
from pytrends_modern.exceptions import TooManyRequestsError

pytrends = TrendReq(retries=5, backoff_factor=0.5)

try:
    pytrends.build_payload(['keyword'])
    df = pytrends.interest_over_time()
except TooManyRequestsError:
    print("Rate limited. Wait before retrying.")
```

--------------------------------

### Fetch Keyword Suggestions with pytrends-modern

Source: https://context7.com/yiromo/pytrends-modern/llms.txt

Retrieves keyword suggestions from Google Trends autocomplete based on an input keyword. This function requires the pytrends_modern library and returns a list of dictionaries, each containing suggestion details.

```python
from pytrends_modern import TrendReq

pytrends = TrendReq()

# Get suggestions for a keyword
suggestions = pytrends.suggestions('artificial intelligence')

print("Keyword suggestions:")
for suggestion in suggestions:
    print(f"  - {suggestion['title']}")
    print(f"    Type: {suggestion.get('type', 'N/A')}")
    print(f"    ID: {suggestion.get('mid', 'N/A')}")
    print()

# Use suggestion IDs for more precise searches
# These 'mid' values can be used in build_payload for entity-based queries
```

--------------------------------

### Access Real-Time Trends via TrendsRSS

Source: https://context7.com/yiromo/pytrends-modern/llms.txt

Provides fast access to real-time trending searches using Google's RSS feed, including rich media like images and news articles. Requires the TrendsRSS class from pytrends_modern and supports various output formats.

```python
from pytrends_modern import TrendsRSS

rss = TrendsRSS(timeout=10)

# Get trending searches with rich metadata
trends = rss.get_trends(
    geo='US',
    output_format='dict',
    include_images=True,
    include_articles=True,
    max_articles_per_trend=5
)

# Process results
for trend in trends[:5]:
    print(f"Title: {trend['title']}")
    print(f"Traffic: {trend['traffic']:,}+")
    print(f"Articles: {len(trend.get('articles', []))}")
    if trend.get('picture'):
        print(f"Image: {trend['picture']}")
    if trend.get('articles'):
        print(f"First headline: {trend['articles'][0]['title']}")
    print("---")

# Get trends as DataFrame
df = rss.get_trends(geo='US', output_format='dataframe')
print(df[['title', 'traffic', 'article_count']])

# Get trends for multiple countries
results = rss.get_trends_for_multiple_geos(
    geos=['US', 'GB', 'CA', 'AU'],
    output_format='dict',
    include_articles=False
)

for geo, trends in results.items():
    print(f"\n{geo}: {len(trends)} trending topics")
    for t in trends[:3]:
        print(f"  - {t['title']}")
```

--------------------------------

### Fetch Daily Trending Searches via RSS Feed

Source: https://github.com/yiromo/pytrends-modern/blob/main/README.md

Demonstrates fetching trending searches using the TrendsRSS class, which provides a fast alternative to the deprecated Google Trends API. This method returns a limited number of trends with associated media and is recommended for most use cases due to its speed.

```python
from pytrends_modern import TrendsRSS

rss = TrendsRSS()
trends = rss.get_trends(geo='US')  # ~0.7s, returns 10 trends with images/articles
```

--------------------------------

### Build Payload for Google Trends API

Source: https://github.com/yiromo/pytrends-modern/blob/main/README.md

This function call demonstrates how to construct the payload for the Google Trends API using the build_payload method. It specifies keywords, category, timeframe, geographic location, and the property for which data is requested.

```python
pytrends.build_payload(
    kw_list=['keyword1', 'keyword2'],  # Max 5 keywords
    cat=0,                              # Category (0 = all)
    timeframe='today 5-y',             # Time range
    geo='',                            # Geographic location
    gprop=''                           # Property ('', 'images', 'news', 'youtube', 'froogle')
)
```

--------------------------------

### Python Advanced Anti-Rate-Limit Configuration

Source: https://github.com/yiromo/pytrends-modern/blob/main/README.md

Configures pytrends-modern's browser mode with advanced anti-rate-limit features. This includes setting random delays between requests, rotating the OS fingerprint, and maintaining a persistent login context to mimic human behavior and avoid detection.

```python
import random
from pytrends_modern import TrendReq, BrowserConfig

# Add delays + rotate OS fingerprint
os_choice = random.choice(['windows', 'macos', 'linux'])
config = BrowserConfig(
    headless=False,
    min_delay=3.0,             # Min delay between requests (seconds)
    max_delay=7.0,             # Max delay between requests
    persistent_context=True,    # Keep Google login
    os=os_choice,              # Rotate OS fingerprint
    humanize=True
)

pytrends = TrendReq(browser_config=config)
# Delays are automatically added before each request
```

--------------------------------

### Retrieve Related Queries with pytrends-modern

Source: https://context7.com/yiromo/pytrends-modern/llms.txt

Fetches search queries related to a given keyword, distinguishing between top (most searched) and rising (trending) queries. Requires the pytrends_modern library and returns a dictionary containing 'top' and 'rising' DataFrames.

```python
from pytrends_modern import TrendReq

pytrends = TrendReq()
pytrends.build_payload(['Python'], timeframe='today 12-m')

related = pytrends.related_queries()

# Access results for 'Python' keyword
python_data = related['Python']

# Top related queries (most searched)
if python_data['top'] is not None:
    print("Top related queries:")
    print(python_data['top'])
    # Output example:
    #            query  value
    # 0  python download   100
    # 1     python 3        95
    # 2  python tutorial    87

# Rising queries (gaining popularity)
if python_data['rising'] is not None:
    print("\nRising queries:")
    print(python_data['rising'])
    # Output example:
    #                  query  value
    # 0  python ai projects   5400%
    # 1  chatgpt python       3200%
```

--------------------------------

### Merge Google Trends DataFrames (Python)

Source: https://context7.com/yiromo/pytrends-modern/llms.txt

Merges multiple pandas DataFrames containing Google Trends interest over time data. Supports different merge strategies like 'outer'.

```python
from pytrends_modern import TrendReq

# Initialize TrendReq
pytrends = TrendReq()

# Build payload for 'Python' and get interest over time
pytrends.build_payload(['Python'], timeframe='today 12-m')
df1 = pytrends.interest_over_time()

# Build payload for 'JavaScript' and get interest over time
pytrends.build_payload(['JavaScript'], timeframe='today 12-m')
df2 = pytrends.interest_over_time()

# Merge the DataFrames
# Assuming merge_trends_data is a custom function or from another library
# For demonstration, let's assume it's a pandas merge:
merged = df1.merge(df2, left_index=True, right_index=True, how='outer')

print(merged.head())
```

--------------------------------

### Fetch Related Topics with pytrends-modern

Source: https://context7.com/yiromo/pytrends-modern/llms.txt

Retrieves entities (topics) related to a search keyword, providing both top and rising topics with associated metadata. This function requires the pytrends_modern library and returns a dictionary of DataFrames.

```python
from pytrends_modern import TrendReq

pytrends = TrendReq()
pytrends.build_payload(['Machine Learning'], timeframe='today 12-m')

topics = pytrends.related_topics()

# Access results
ml_topics = topics['Machine Learning']

# Top related topics
if ml_topics['top'] is not None:
    print("Top related topics:")
    # Columns: topic_title, topic_mid, topic_type, value
    print(ml_topics['top'][['topic_title', 'topic_type', 'value']].head())

# Rising topics
if ml_topics['rising'] is not None:
    print("\nRising topics:")
    print(ml_topics['rising'][['topic_title', 'topic_type', 'value']].head())
```
Tokens:
Raw