Google Search Console API Setup

This guide walks you through setting up automated GSC data fetching.

Step 1: Enable the API

1. Go to Google Cloud Console
2. Create a new project or select existing one
3. Go to APIs & Services → Library
4. Search for “Google Search Console API”
5. Click Enable

Step 2: Create Service Account (Recommended for Automation)

1. Go to APIs & Services → Credentials
2. Click Create Credentials → Service Account
3. Name it gsc-reader or similar
4. Click Create and Continue
5. Skip role assignment (not needed for GSC)
6. Click Done
7. Click on the new service account
8. Go to Keys tab → Add Key → Create new key
9. Choose JSON and download
10. Rename to service_account.json and place in scripts/gsc/

Step 3: Grant Access in Search Console

1. Go to Google Search Console
2. Select your property (360tft.co.uk)
3. Go to Settings → Users and permissions
4. Click Add user
5. Enter the service account email (from the JSON file, looks like xxx@project.iam.gserviceaccount.com)
6. Set permission to Restricted (read-only)
7. Click Add

Step 4: Add Secret to GitHub

1. Go to your GitHub repo → Settings → Secrets and variables → Actions
2. Click New repository secret
3. Name: GSC_SERVICE_ACCOUNT
4. Value: Paste the entire contents of service_account.json
5. Click Add secret

Step 5: Test Locally

cd scripts/gsc
pip install google-auth google-auth-oauthlib google-api-python-client
python fetch_gsc_data.py --days 7

How It Works

Automated (GitHub Actions)

• Runs every Monday at 8am UTC
• Fetches last 28 days of data
• Saves report to scripts/gsc/data/gsc_latest.json
• Creates GitHub issue with action items

Manual

# Last 28 days (default)
python fetch_gsc_data.py

# Last 90 days
python fetch_gsc_data.py --days 90

# Specific date range
python fetch_gsc_data.py --start 2025-01-01 --end 2025-01-31

Output

The script generates a JSON report with:

• action_items: Prioritized list of SEO tasks
• opportunities: Categorized findings
  • high_impression_low_ctr: Need better titles/descriptions
  • quick_wins: Position 11-20, can push to page 1
  • ranking_opportunities: Position 5-20 worth optimizing
  • top_performers: Best performing queries
• raw_data: Top 100 query/page combinations

Claude Code Integration

When Claude Code reads scripts/gsc/data/gsc_latest.json, it will:

1. Identify high-priority opportunities
2. Suggest specific blog posts or page updates
3. Recommend meta description improvements
4. Track progress over time

Troubleshooting

“Permission denied” error

• Verify service account email is added to Search Console
• Check the property URL matches (sc-domain vs URL prefix)

“API not enabled” error

• Enable Search Console API in Google Cloud Console

No data returned

• GSC has a 3-day delay on data
• Verify you have data in Search Console web interface
• Check date range isn’t too recent

File Structure

scripts/gsc/
├── fetch_gsc_data.py      # Main script
├── service_account.json   # Credentials (DO NOT COMMIT)
├── SETUP.md               # This file
└── data/
    ├── gsc_latest.json    # Most recent report
    └── gsc_report_*.json  # Historical reports

Security Notes

• service_account.json is in .gitignore - never commit credentials
• GitHub secret stores credentials securely for Actions
• Service account has read-only access to GSC