seo/PERFORMANCE_TRACKING_GUIDE.md

# SEO Performance Tracking Guide

Track and analyze your website's SEO performance using Google Analytics 4 and Google Search Console data.

## Overview

The SEO performance tracking features allow you to:

- **Analyze page performance** - Track pageviews, clicks, impressions, CTR, and rankings
- **Find keyword opportunities** - Discover keywords you can rank higher for
- **Generate SEO reports** - Create comprehensive performance reports
- **Import data** - Support for both CSV imports and API integration

## Commands

### 1. `seo performance` - Analyze Page Performance

Analyze traffic and search performance data.

**Usage:**

```bash
# Analyze with CSV exports
./seo performance --ga4 analytics.csv --gsc search.csv

# Analyze GA4 data only
./seo performance --ga4 analytics.csv

# Analyze GSC data only
./seo performance --gsc search.csv

# With custom output
./seo performance --ga4 analytics.csv --gsc search.csv --output custom_analysis.csv

# Preview
./seo performance --ga4 analytics.csv --dry-run
```

**Data Sources:**

- **Google Analytics 4**: Export from GA4 → Reports → Engagement → Pages and screens
- **Google Search Console**: Export from GSC → Performance → Search results → Export

**Metrics Analyzed:**

| Metric | Source | Description |
|--------|--------|-------------|
| Pageviews | GA4 | Number of page views |
| Sessions | GA4 | Number of sessions |
| Bounce Rate | GA4 | Percentage of single-page sessions |
| Engagement Rate | GA4 | Percentage of engaged sessions |
| Clicks | GSC | Number of search clicks |
| Impressions | GSC | Number of search impressions |
| CTR | GSC | Click-through rate |
| Position | GSC | Average search ranking |

### 2. `seo keywords` - Keyword Opportunities

Find keywords you can optimize for better rankings.

**Usage:**

```bash
# Analyze keyword opportunities
./seo keywords gsc_export.csv

# Limit results
./seo keywords gsc_export.csv --limit 20

# Custom output
./seo keywords gsc_export.csv --output keywords.csv
```

**What It Finds:**

- Keywords ranking positions 5-20 (easy to improve)
- High impression keywords with low CTR
- Keywords with good traffic potential

**Example Output:**

```
✅ Found 47 keyword opportunities!

Top opportunities:
  1. best vpn 2024 - Position: 8.5, Impressions: 1250
  2. torrent client - Position: 12.3, Impressions: 890
  3. vpn for gaming - Position: 9.1, Impressions: 650
```

### 3. `seo report` - Generate SEO Report

Create comprehensive SEO performance reports.

**Usage:**

```bash
# Generate report
./seo report

# Custom output
./seo report --output monthly_seo_report.md
```

**Report Includes:**

- Performance summary
- Traffic analysis
- Keyword opportunities
- SEO recommendations
- Action items

## Data Export Guides

### Export from Google Analytics 4

1. Go to **Google Analytics** → Your Property
2. Navigate to **Reports** → **Engagement** → **Pages and screens**
3. Set date range (e.g., last 30 days)
4. Click **Share** → **Download file** → **CSV**
5. Save as `ga4_export.csv`

**Required Columns:**
- Page path
- Page title
- Views (pageviews)
- Sessions
- Bounce rate
- Engagement rate

### Export from Google Search Console

1. Go to **Google Search Console** → Your Property
2. Click **Performance** → **Search results**
3. Set date range (e.g., last 30 days)
4. Check all metrics: Clicks, Impressions, CTR, Position
5. Click **Export** → **CSV**
6. Save as `gsc_export.csv`

**Required Columns:**
- Page (URL)
- Clicks
- Impressions
- CTR
- Position

## API Integration (Advanced)

For automated data fetching, configure API credentials:

### 1. Google Analytics 4 API

**Setup:**

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project or select existing
3. Enable **Google Analytics Data API**
4. Create service account credentials
5. Download JSON key file
6. Share GA4 property with service account email

**Configuration:**

Add to `.env`:
```
GA4_CREDENTIALS=/path/to/ga4-credentials.json
GA4_PROPERTY_ID=properties/123456789
```

### 2. Google Search Console API

**Setup:**

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Enable **Search Console API**
3. Create service account credentials
4. Download JSON key file
5. Share GSC property with service account email

**Configuration:**

Add to `.env`:
```
GSC_CREDENTIALS=/path/to/gsc-credentials.json
GSC_SITE_URL=https://www.mistergeek.net
```

### Using API Mode

Once configured, you can run without CSV files:

```bash
# Fetch data directly from APIs
./seo performance --start-date 2024-01-01 --end-date 2024-01-31
```

## Performance Insights

### Low CTR Pages

Pages with high impressions but low CTR need better titles/descriptions:

```bash
# Find pages with <2% CTR and 100+ impressions
./seo performance --gsc search.csv
# Check "low_ctr" section in output
```

**Action:** Optimize meta titles and descriptions

### Low Position Pages

Pages ranking beyond position 20 need content optimization:

```bash
# Find pages ranking >20 with 50+ impressions
./seo performance --gsc search.csv
# Check "low_position" section in output
```

**Action:** Improve content quality, add internal links

### Keyword Opportunities

Keywords ranking 5-20 are easy to improve:

```bash
./seo keywords gsc_export.csv --limit 50
```

**Action:** Optimize content for these specific keywords

## Workflow Examples

### Weekly Performance Check

```bash
# 1. Export fresh data from GA4 and GSC
# 2. Analyze performance
./seo performance --ga4 weekly_ga4.csv --gsc weekly_gsc.csv

# 3. Review keyword opportunities
./seo keywords weekly_gsc.csv --limit 20

# 4. Generate report
./seo report --output weekly_report.md
```

### Monthly SEO Audit

```bash
# 1. Export full month data
# 2. Comprehensive analysis
./seo performance --ga4 month_ga4.csv --gsc month_gsc.csv

# 3. Identify top issues
# Review output for:
# - Low CTR pages
# - Low position pages
# - High impression, low click pages

# 4. Generate action plan
./seo report --output monthly_audit.md
```

### Content Optimization Sprint

```bash
# 1. Find keyword opportunities
./seo keywords gsc.csv --limit 50 > opportunities.txt

# 2. For each opportunity:
# - Review current content
# - Optimize for target keyword
# - Update meta description

# 3. Track improvements
# Re-run analysis after 2 weeks
./seo performance --gsc new_gsc.csv
```

## Output Files

All analysis results are saved to `output/`:

| File | Description |
|------|-------------|
| `performance_data_*.csv` | Raw performance metrics |
| `performance_analysis_*.csv` | Analysis with insights |
| `seo_report_*.md` | Markdown report |

## Troubleshooting

### No Data Loaded

**Problem:** "No data loaded. Provide GA4 and/or GSC export files."

**Solution:**
- Ensure CSV files are properly exported
- Check file paths are correct
- Verify CSV has required columns

### Column Name Errors

**Problem:** "KeyError: 'pageviews'"

**Solution:**
- Ensure GA4 export includes pageviews column
- Column names are normalized automatically
- Check CSV encoding (UTF-8)

### API Authentication Errors

**Problem:** "Failed to initialize GA4 client"

**Solution:**
- Verify service account JSON is valid
- Check API is enabled in Google Cloud
- Ensure service account has access to property

## Best Practices

### Data Collection

1. **Export regularly** - Weekly or monthly exports
2. **Consistent date ranges** - Use same range for comparisons
3. **Keep historical data** - Archive old exports for trend analysis

### Analysis

1. **Focus on trends** - Look at changes over time
2. **Prioritize impact** - Fix high-traffic pages first
3. **Track improvements** - Re-analyze after optimizations

### Reporting

1. **Regular reports** - Weekly/monthly cadence
2. **Share insights** - Distribute to team/stakeholders
3. **Action-oriented** - Include specific recommendations

## Related Commands

- `seo export` - Export posts from WordPress
- `seo meta_description` - Generate meta descriptions
- `seo update_meta` - Update meta on WordPress

## See Also

- [README.md](README.md) - Main documentation
- [META_DESCRIPTION_GUIDE.md](META_DESCRIPTION_GUIDE.md) - Meta description guide
- [ANALYTICS_SETUP.md](ANALYTICS_SETUP.md) - API setup guide (if exists)

---

**Made with ❤️ for better SEO automation**