# FAQ Featured Snippets - Automated Setup Guide

**Last Updated:** 2026-01-13

Complete guide for setting up automated Featured Snippets monitoring using the Search Console API.

## Quick Start

1. **Test the script:**

   ```bash
   php v2/scripts/blog/fetch-faq-featured-snippets.php
   ```

2. **Set up monthly cron job:**

   ```bash
   # Edit crontab
   crontab -e

   # Add this line (runs 1st of each month at 9 AM)
   0 9 1 * * cd /path/to/landingpage && php v2/scripts/blog/fetch-faq-featured-snippets.php --email
   ```

3. **Verify data collection:**
   ```bash
   # Check output files
   ls -lh v2/data/blog/gsc-featured-snippets/
   ```

## Prerequisites

- ✅ Google Search Console API access configured
- ✅ Service account credentials at `v2/config/google-api-credentials.json`
- ✅ Composer dependencies installed (`composer install`)
- ✅ PHP 8.0+ with required extensions

## Script Usage

### Basic Usage

```bash
# Fetch last 28 days (default)
php v2/scripts/blog/fetch-faq-featured-snippets.php
```

### Custom Date Range

```bash
# Fetch specific date range
php v2/scripts/blog/fetch-faq-featured-snippets.php \
  --start-date=2025-12-01 \
  --end-date=2026-01-13
```

### With Email Report

```bash
# Fetch and email results
php v2/scripts/blog/fetch-faq-featured-snippets.php --email
```

### Help

```bash
php v2/scripts/blog/fetch-faq-featured-snippets.php --help
```

## Output Files

All files are saved to `v2/data/blog/gsc-featured-snippets/`:

### 1. `faq-featured-snippets.json`

Current Featured Snippets data for FAQ pages, sorted by clicks (descending).

**Structure:**

```json
[
  {
    "page": "/insights/lexikon/minijob/",
    "query": "minijob 2025",
    "search_appearance": "FEATURED_SNIPPET",
    "clicks": 45,
    "impressions": 1200,
    "ctr": 3.75,
    "position": 1.0
  }
]
```

### 2. `summary.json`

Summary statistics for the date range.

**Structure:**

```json
{
  "date_range": {
    "start": "2025-12-01",
    "end": "2026-01-13"
  },
  "total_featured_snippets": 150,
  "faq_featured_snippets": 45,
  "faq_pages_with_snippets": 12,
  "unique_queries": 38,
  "total_clicks": 1250,
  "total_impressions": 35000,
  "average_ctr": 3.57,
  "average_position": 1.2,
  "generated_at": "2026-01-13 10:30:00"
}
```

### 3. `snapshot-YYYY-MM.json`

Monthly snapshot for historical tracking.

**Structure:**

```json
{
  "month": "2026-01",
  "data": [...],
  "summary": {...}
}
```

## Cron Job Setup

### Automated Setup (Recommended)

Use the setup script to automatically add the cron job:

```bash
bash v2/scripts/blog/setup-faq-monitoring-cron.sh
```

This script will:

- Verify the script exists and is executable
- Check for existing cron entries
- Add the cron job with proper paths
- Provide verification instructions

### Manual Setup

Alternatively, add manually to crontab:

```bash
# Edit crontab
crontab -e

# Add this line (adjust path to your project)
0 9 1 * * cd /Users/hadyelhady/Documents/GitHub/landingpage && php v2/scripts/blog/fetch-faq-featured-snippets.php --email
```

### Test Before Adding

Test the cron command before adding it:

```bash
bash v2/scripts/blog/test-faq-monitoring-cron.sh
```

This will verify:

- Script exists and is executable
- PHP is available
- Script syntax is valid
- Script can initialize properly

### Weekly Automation (Optional)

For more frequent monitoring:

```bash
# Run every Monday at 9 AM
0 9 * * 1 cd /path/to/landingpage && php v2/scripts/blog/fetch-faq-featured-snippets.php --start-date=$(date -d '7 days ago' +\%Y-\%m-\%d) --end-date=$(date +\%Y-\%m-\%d)
```

## Email Reports

The script can send email reports when using `--email` flag.

**Recipient:** `hady@ordio.com` (configured in `v2/helpers/performance-email.php`)

**Email includes:**

- Summary statistics
- Top 10 Featured Snippets
- Date range
- Total metrics

## Data Analysis

### View Current Data

```bash
# Pretty print JSON
cat v2/data/blog/gsc-featured-snippets/faq-featured-snippets.json | jq '.[0:5]'

# Count records
cat v2/data/blog/gsc-featured-snippets/faq-featured-snippets.json | jq 'length'

# View summary
cat v2/data/blog/gsc-featured-snippets/summary.json | jq
```

### Compare Monthly Snapshots

```bash
# Compare two months
diff v2/data/blog/gsc-featured-snippets/snapshot-2025-12.json \
     v2/data/blog/gsc-featured-snippets/snapshot-2026-01.json
```

### Generate CSV Export

```bash
# Convert JSON to CSV (requires jq)
cat v2/data/blog/gsc-featured-snippets/faq-featured-snippets.json | \
  jq -r '.[] | [.query, .page, .clicks, .impressions, .ctr, .position] | @csv' > \
  faq-featured-snippets.csv
```

## Troubleshooting

### API Authentication Errors

**Error:** `Failed to initialize Google API client`

**Solutions:**

1. Verify credentials file exists: `v2/config/google-api-credentials.json`
2. Check file permissions
3. Verify service account has Search Console access

### Rate Limiting

**Error:** `Rate limit exceeded`

**Solutions:**

1. Script automatically retries with exponential backoff
2. Wait a few minutes and retry
3. Reduce date range if needed

### No Data Returned

**Possible causes:**

1. No Featured Snippets in date range
2. FAQ pages not matching filter (`/insights/*/`)
3. Date range too small

**Solutions:**

1. Try larger date range (e.g., 3 months)
2. Verify FAQ pages exist in Search Console
3. Check Search Console manually for Featured Snippets

### Email Not Sending

**Error:** `Email helper not found`

**Solutions:**

1. Verify `v2/helpers/performance-email.php` exists
2. Check email configuration
3. Run without `--email` flag if email not needed

## Integration with Other Tools

### Google Sheets Integration

1. Export JSON to CSV (see above)
2. Import CSV to Google Sheets
3. Set up automatic refresh (if using Google Apps Script)

### Dashboard Integration

Use the JSON files to populate dashboards:

- Load `summary.json` for overview metrics
- Load `faq-featured-snippets.json` for detailed data
- Use monthly snapshots for trend analysis

## Best Practices

1. **Run Monthly:** Set up cron job for 1st of each month
2. **Review Data:** Check summary.json monthly for trends
3. **Track Changes:** Compare monthly snapshots
4. **Act on Data:** Use insights to optimize FAQs
5. **Monitor Growth:** Track `faq_featured_snippets` count over time

## Related Documentation

- `FAQ_GSC_ALERTS_SETUP.md` - Manual setup guide
- `FAQ_MONITORING_QUICK_START.md` - Quick start guide
- `FAQ_QUARTERLY_REVIEW_PROCESS.md` - Quarterly review process