seo/guides/ANALYZER_SUMMARY.md

# Multi-Site SEO Analyzer - Implementation Summary

## What Was Created

### New Script: `scripts/multi_site_seo_analyzer.py`

A Python script that automatically:

1. **Connects to 3 WordPress sites** (mistergeek.net, webscroll.fr, hellogeek.net)
2. **Fetches all published posts** using WordPress REST API
3. **Analyzes titles** for:
   - Length (optimal: 50-70 chars)
   - Power words (best, complete, guide, etc.)
   - Numbers (2025, top 10, etc.)
   - Readability and special characters
4. **Analyzes meta descriptions** for:
   - Presence (missing = 0 score)
   - Length (optimal: 120-160 chars)
   - Call-to-action language
5. **Scores each post** (0-100) based on SEO best practices
6. **Generates AI recommendations** (optional) for top priority posts using Claude via OpenRouter
7. **Exports results** to:
   - CSV file with detailed analysis
   - Markdown summary report

---

## Features

### Automatic Title Analysis
- Detects titles that are too short/long
- Identifies missing power words
- Checks for numbers/statistics
- Flags problematic special characters
- Scoring algorithm: 0-100

### Automatic Meta Description Analysis
- Detects missing meta descriptions (0 score)
- Validates length (120-160 chars optimal)
- Checks for call-to-action language
- Scoring algorithm: 0-100

### Combined SEO Scoring
```
Overall Score = (Title Score × 40%) + (Meta Description Score × 60%)
```
Meta descriptions weighted heavier because they directly impact CTR from search results.

### AI-Powered Recommendations (Optional)
- Uses Claude 3.5 Sonnet via OpenRouter
- Generates specific, actionable recommendations
- Cost-optimized: Only analyzes top priority posts (default 10, configurable)
- Estimated cost: $0.10 per 10 posts analyzed

### Multi-Site Support
- Fetches from all 3 sites simultaneously
- Per-site breakdown in reports
- Identifies top 5 posts to optimize per site
- Consolidates analysis across all sites

---

## Configuration Changes

### Updated `scripts/config.py`
Added multi-site configuration support:

```python
WORDPRESS_SITES = {
    'mistergeek.net': {'url': '...', 'username': '...', 'password': '...'},
    'webscroll.fr': {'url': '...', 'username': '...', 'password': '...'},
    'hellogeek.net': {'url': '...', 'username': '...', 'password': '...'}
}
```

New methods:
- `get_site_config(site_name)` - Get config for specific site
- `get_all_sites()` - Get all configured sites

### Updated `.env.example`
Added variables for each site:
```
WORDPRESS_MISTERGEEK_URL=...
WORDPRESS_MISTERGEEK_USERNAME=...
WORDPRESS_MISTERGEEK_PASSWORD=...

WORDPRESS_WEBSCROLL_URL=...
[etc for each site]
```

---

## Documentation Created

### 1. `guides/SEO_ANALYZER_GUIDE.md` (Comprehensive)
- Complete setup instructions
- Detailed usage examples
- How to interpret scores
- Understanding title and meta analysis
- Action plan for implementation
- Cost estimation
- Troubleshooting guide
- Advanced usage examples
- FAQ section

### 2. `guides/QUICKSTART_ANALYZER.md` (Fast Reference)
- 30-second setup
- One-liners for different scenarios
- Common commands
- Quick troubleshooting
- Cost comparison table

### 3. `guides/ANALYZER_SUMMARY.md` (This document)
- Overview of what was created
- Feature summary
- Usage instructions
- Output explanation

---

## Usage

### Basic Command

```bash
python scripts/multi_site_seo_analyzer.py
```

**What it does:**
- Fetches posts from all 3 sites
- Analyzes titles and meta descriptions
- Generates AI recommendations for top 10 worst-scoring posts
- Exports CSV and Markdown report

### Command Options

```bash
# Skip AI recommendations (free, faster)
python scripts/multi_site_seo_analyzer.py --no-ai

# AI recommendations for top 20 posts
python scripts/multi_site_seo_analyzer.py --top-n 20

# Custom output file
python scripts/multi_site_seo_analyzer.py --output my_report.csv
```

---

## Output Files

### Location: `output/reports/`

### 1. CSV File: `seo_analysis_YYYYMMDD_HHMMSS.csv`

Contains one row per post with columns:
- `site` - Website name
- `post_id` - WordPress post ID
- `title` - Post title
- `slug` - Post slug
- `url` - Full URL
- `meta_description` - Current meta description
- `title_score` - Title SEO score (0-100)
- `title_issues` - Title problems identified
- `title_recommendations` - How to improve title
- `meta_score` - Meta description SEO score (0-100)
- `meta_issues` - Meta description problems
- `meta_recommendations` - How to improve meta
- `overall_score` - Combined score (40% title + 60% meta)
- `ai_recommendations` - Claude-generated specific recommendations

**Use for:**
- Importing to Excel/Google Sheets
- Filtering and sorting
- Bulk editing preparations
- Tracking changes over time

### 2. Markdown Report: `seo_analysis_YYYYMMDD_HHMMSS_summary.md`

Contains:
- Summary statistics (total posts, average scores, cost)
- Priority issues breakdown (missing meta, weak titles, etc.)
- Per-site analysis and top 5 posts to optimize per site
- Human-readable explanations

**Use for:**
- Quick overview
- Sharing with team
- Understanding key metrics
- Decision-making

---

## Score Interpretation

### Score Ranges

| Range | Interpretation | Action |
|-------|-----------------|--------|
| 0-25 | Critical | Fix immediately - major SEO issues |
| 25-50 | Poor | Optimize soon - multiple issues |
| 50-75 | Fair | Improve when convenient - some issues |
| 75-90 | Good | Minor tweaks only - mostly optimized |
| 90-100 | Excellent | No changes needed - well optimized |

### Example Scores

**Poor Post (Score: 12)**
```
Title: "VPN"
- Issues: Too short (3 chars), no power words, no numbers
- Title Score: 5/100

Meta Description: [MISSING]
- Issues: Missing entirely
- Meta Score: 0/100

Overall: 12/100 (Critical - needs work)
```

**Good Post (Score: 88)**
```
Title: "Best VPN Services 2025: Complete Review"
- Issues: None
- Title Score: 95/100

Meta Description: "Compare 50+ VPN services with speed tests, security reviews, and pricing. Find the best VPN for your needs."
- Issues: None
- Meta Score: 85/100

Overall: 88/100 (Good - minimal changes)
```

---

## Cost Breakdown

### Using AI Recommendations

**Pricing:** Claude 3.5 Sonnet via OpenRouter = $3/$15 per 1M input/output tokens

**Per run examples:**

| Posts Analyzed | Tokens | Cost |
|---|---|---|
| 10 posts | ~30k input, 5k output | ~$0.10 |
| 20 posts | ~60k input, 10k output | ~$0.20 |
| 50 posts | ~150k input, 25k output | ~$0.50 |
| 100 posts | ~300k input, 50k output | ~$1.00 |

### Monthly Budget

- **Weekly no-AI:** $0/month
- **Weekly with AI (top 10):** ~$0.40/month
- **Monthly with AI (top 50):** ~$0.50/month
- **Fits easily in €50 budget ✓**

---

## Prerequisites

Before running, ensure:

1. **WordPress credentials** for all 3 sites (API/app passwords)
2. **OpenRouter API key** (for AI recommendations)
3. **REST API enabled** on all 3 WordPress sites
4. **Python 3.8+** installed
5. **Dependencies installed:** `pip install -r requirements.txt`

---

## Workflow Example

### Week 1: Initial Analysis

```bash
# Run analyzer with AI for top 10
python scripts/multi_site_seo_analyzer.py --top-n 10

# Review results
open output/reports/seo_analysis_*_summary.md

# See top 10 posts to optimize on each site
# Note: AI cost ~$0.10
```

### Week 1-4: Implementation

For each of top 10 posts per site:

1. Open WordPress editor
2. Review AI recommendation
3. Update title (if needed)
4. Update meta description (if needed)
5. Publish changes

Average time: 2-3 minutes per post = 30-45 minutes total

### Week 5: Re-analysis

```bash
# Run analyzer again to track progress
python scripts/multi_site_seo_analyzer.py --no-ai

# Compare with Week 1 results
# Identify next batch of 10 posts to optimize
```

Repeat as needed.

---

## Expected Improvements

### Short-term (Month 1)
- **Reduced posts with score < 50:** 30-50% fewer critical issues
- **Meta descriptions added:** Most missing descriptions now present
- **Title improvements:** Clearer, more compelling titles

### Medium-term (Month 3)
- **CTR improvement:** 10-20% increase in click-through rate from search results
- **Keyword rankings:** Some keywords move up 1-3 positions
- **Organic traffic:** 5-10% increase as improved titles/descriptions increase clicks

### Long-term (Months 3-6)
- **Compound effect:** Better CTR signals boost rankings
- **Authority:** Focused content with optimized SEO
- **Traffic:** 20-30% total increase from all factors

---

## Next Steps

1. **Update .env** with your 3 site credentials
2. **Run analyzer:** `python scripts/multi_site_seo_analyzer.py`
3. **Review report:** `open output/reports/seo_analysis_*_summary.md`
4. **Implement:** Start with top 5 posts per site
5. **Re-run:** Monthly to track progress and identify next batch

---

## Troubleshooting

### Connection Issues
- Verify site URLs (https, www)
- Check WordPress credentials
- Test: `curl https://yoursite.com/wp-json/wp/v2/posts?per_page=1`

### No Posts Found
- Check credentials have read permissions
- Verify posts are published (not draft)
- Try disabling SSL verification (last resort)

### AI Errors
- Verify OPENROUTER_API_KEY is set
- Check key has API credits
- Use --no-ai to skip AI (still analyzes)

See `guides/SEO_ANALYZER_GUIDE.md` for detailed troubleshooting.

---

## Files Summary

| File | Purpose |
|------|---------|
| `scripts/multi_site_seo_analyzer.py` | Main analyzer script |
| `scripts/config.py` | Updated with multi-site config |
| `.env` | Your site credentials (not in repo) |
| `.env.example` | Example config (with all fields) |
| `guides/SEO_ANALYZER_GUIDE.md` | Comprehensive guide |
| `guides/QUICKSTART_ANALYZER.md` | Quick reference |
| `guides/ANALYZER_SUMMARY.md` | This file |
| `output/reports/` | Where results are saved |

---

## Questions?

See the full guide: `guides/SEO_ANALYZER_GUIDE.md`

Ready to analyze? Run: `python scripts/multi_site_seo_analyzer.py`