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:

# 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:

# 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:

# 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
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
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:

# 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:

# 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:

# 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:

./seo keywords gsc_export.csv --limit 50

Action: Optimize content for these specific keywords

Workflow Examples

Weekly Performance Check

# 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

# 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

# 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 - Main documentation
• META_DESCRIPTION_GUIDE.md - Meta description guide
• ANALYTICS_SETUP.md - API setup guide (if exists)

---

Made with ❤️ for better SEO automation