social-media-trends-research

What this skill does

# Social Media Trends Research

## Overview

Programmatic trend research using three free tools:
- **pytrends**: Google Trends data (velocity, volume, related queries)
- **yars**: Reddit scraping without API keys
- **Perplexity MCP**: Twitter/TikTok/Web trends (via Claude's built-in MCP)

This skill provides executable code for trend research. Use alongside `content-marketing-social-listening` for strategy and `perplexity-search` for deep queries.

## Quick Setup

```bash
# Install dependencies (one-time)
pip install pytrends requests --break-system-packages
```

No API keys required. Reddit scraping uses public .json endpoints.

---

## Tool 1: pytrends (Google Trends)

### What It Provides
- Real-time trending searches by country
- Interest over time for keywords
- Related queries (rising = velocity indicators)
- Interest by region
- Related topics

### Basic Usage

```python
from pytrends.request import TrendReq
import time

# Initialize (no API key needed)
pytrends = TrendReq(hl='en-US', tz=330)  # tz=330 for India (IST)

# Get real-time trending searches
trending = pytrends.trending_searches(pn='india')
print(trending.head(20))
```

### Research Your Niche Keywords

```python
from pytrends.request import TrendReq
import time

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

# Define your niche keywords (max 5 per request)
keywords = ['heart health', 'cardiology', 'cholesterol']

# Build payload
pytrends.build_payload(keywords, timeframe='now 7-d', geo='IN')

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

# CRITICAL: Wait between requests to avoid rate limiting
time.sleep(3)

# Get related queries (THIS IS GOLD - shows rising topics)
related = pytrends.related_queries()
for kw in keywords:
    print(f"\n=== Rising queries for '{kw}' ===")
    rising = related[kw]['rising']
    if rising is not None:
        print(rising.head(10))
```

### Find Viral/Breakout Topics

```python
from pytrends.request import TrendReq
import time

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

def find_breakout_topics(keyword, geo=''):
    """Find topics with explosive growth (potential viral content)"""
    pytrends.build_payload([keyword], timeframe='today 3-m', geo=geo)
    time.sleep(3)  # Rate limiting
    
    related = pytrends.related_queries()
    rising = related[keyword]['rising']
    
    if rising is not None:
        # Filter for breakout topics (marked as "Breakout" or very high %)
        breakouts = rising[rising['value'] >= 1000]  # 1000%+ growth
        return breakouts
    return None

# Example usage
breakouts = find_breakout_topics('heart health', geo='IN')
print(breakouts)
```

### Rate Limiting Rules for pytrends

```python
import time

# SAFE: 1 request per 3-5 seconds for casual use
time.sleep(5)

# BULK RESEARCH: 1 request per 60 seconds
time.sleep(60)

# If you get rate limited (429 error): Wait 60-120 seconds, then continue
# If persistent issues: Wait 4-6 hours before resuming
```

### Useful Timeframes

| Timeframe | Use Case |
|-----------|----------|
| `'now 1-H'` | Last hour (real-time spikes) |
| `'now 4-H'` | Last 4 hours |
| `'now 1-d'` | Last 24 hours |
| `'now 7-d'` | Last 7 days (best for trends) |
| `'today 1-m'` | Last 30 days |
| `'today 3-m'` | Last 90 days (velocity analysis) |
| `'today 12-m'` | Last year (seasonal patterns) |

---

## Tool 2: Reddit (No API Keys - Public JSON Endpoints)

### What It Provides
- Search Reddit for any keyword
- Get hot/top/rising posts from subreddits
- Post engagement data (upvotes, comments)
- No authentication required

### Basic Usage

```python
import requests
import time

headers = {'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36'}

# Search Reddit for your niche
url = "https://www.reddit.com/search.json?q=heart+health&limit=10&sort=relevance&t=week"
response = requests.get(url, headers=headers, timeout=10)
data = response.json()

# Display results
for child in data.get('data', {}).get('children', []):
    post = child.get('data', {})
    print(f"Title: {post.get('title')}")
    print(f"Subreddit: r/{post.get('subreddit')}")
    print(f"Score: {post.get('score')}")
    print("---")
```

### Get Hot Posts from Specific Subreddits

```python
import requests
import time

headers = {'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36'}

# Define subreddits relevant to your niche
subreddits = ['cardiology', 'health', 'medicine']

for sub in subreddits:
    print(f"\n=== Hot in r/{sub} ===")
    try:
        url = f"https://www.reddit.com/r/{sub}/hot.json?limit=10"
        response = requests.get(url, headers=headers, timeout=10)
        data = response.json()
        
        for child in data.get('data', {}).get('children', [])[:5]:
            post = child.get('data', {})
            print(f"- [{post.get('score')}] {post.get('title')[:60]}...")
    except Exception as e:
        print(f"Error: {e}")
    
    time.sleep(3)  # Rate limiting between requests
```

### Using the Bundled Reddit Scraper

A helper class is included in `scripts/reddit_scraper.py`:

```python
from scripts.reddit_scraper import SimpleRedditScraper

scraper = SimpleRedditScraper()

# Search
results = scraper.search("heart health tips", limit=20)
for post in results['posts']:
    print(f"[{post['score']}] r/{post['subreddit']}: {post['title']}")

# Get subreddit hot posts
results = scraper.get_subreddit("health", sort="hot", limit=10)
for post in results['posts']:
    print(f"[{post['score']}] {post['title']}")
```

### Rate Limiting Rules for Reddit

```python
import time

# SAFE: 1 request per 2-3 seconds
time.sleep(3)

# If you get 429 errors: Wait 5-10 minutes
# Never do more than 60 requests per hour
```

---

## Tool 3: Perplexity MCP (Twitter/TikTok/Web)

Use Claude's built-in Perplexity MCP for platforms you can't scrape directly.

### Query Templates for Trend Research

**Twitter/X Trends:**
```
"What are the most discussed [YOUR NICHE] topics on Twitter/X this week? 
Include specific examples of viral tweets and their engagement."
```

**TikTok Trends (works from India):**
```
"What [YOUR NICHE] content is trending on TikTok right now? 
Include hashtags, view counts, and content formats that are working."
```

**YouTube Trends:**
```
"What [YOUR NICHE] videos are getting the most views on YouTube this week? 
Include channel names, view counts, and video topics."
```

**LinkedIn Professional:**
```
"What [YOUR NICHE] topics are professionals discussing on LinkedIn this week? 
Include examples of high-engagement posts."
```

**General Viral Content:**
```
"What [YOUR NICHE] content has gone viral across social media in the past 7 days? 
Include platform, format, and why it resonated."
```

### Using Perplexity with perplexity-search Skill

If you have the perplexity-search skill installed:

```bash
python scripts/perplexity_search.py \
  "What cardiology topics are trending on Twitter and TikTok this week? Include specific viral posts and hashtags." \
  --model sonar-pro
```

---

## Combined Research Workflow

### Complete Trend Research Function

```python
from pytrends.request import TrendReq
import requests
import time
import json
from datetime import datetime

class TrendResearcher:
    def __init__(self):
        self.pytrends = TrendReq(hl='en-US', tz=330)
        self.reddit_headers = {
            'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36'
        }
    
    def _reddit_request(self, url):
        """Make a Reddit API request."""
        try:
            response = requests.get(url, headers=self.reddit_headers, timeout=10)
            response.raise_for_status()
            return response.json()
        except Exception as e:
            return {'error': str(e)}
    
    def research_niche(self, keywords, subreddits=None, geo='IN'):
        """
        Complete trend research for a niche.
        
        Args:
            keywords: List of keywords (max 5)
            subreddits: List of su