our-claude-skills/custom-skills/16-seo-search-console/code/CLAUDE.md

CLAUDE.md

Overview

Google Search Console data retriever: search analytics (rankings, CTR, impressions), sitemap status, and index coverage.

Quick Start

pip install -r scripts/requirements.txt

# Requires service account credentials
# ~/.credential/ourdigital-seo-agent.json

python scripts/gsc_client.py --site sc-domain:example.com --action summary

Scripts

Script	Purpose
gsc_client.py	Search Console API client
base_client.py	Shared utilities

Configuration

Service account setup:

# Credentials file location
~/.credential/ourdigital-seo-agent.json

# Add service account email to GSC property as user
ourdigital-seo-agent@ourdigital-insights.iam.gserviceaccount.com

Usage

# Performance summary (last 28 days)
python scripts/gsc_client.py --site sc-domain:example.com --action summary

# Query-level data
python scripts/gsc_client.py --site sc-domain:example.com --action queries --limit 100

# Page-level data
python scripts/gsc_client.py --site sc-domain:example.com --action pages

# Custom date range
python scripts/gsc_client.py --site sc-domain:example.com --action queries \
  --start 2024-01-01 --end 2024-01-31

# Sitemap status
python scripts/gsc_client.py --site sc-domain:example.com --action sitemaps

# JSON output
python scripts/gsc_client.py --site sc-domain:example.com --action summary --json

Actions

Action	Description
summary	Overview metrics (clicks, impressions, CTR, position)
queries	Top search queries
pages	Top pages by clicks
sitemaps	Sitemap submission status
coverage	Index coverage issues

Output: Summary

{
  "site": "sc-domain:example.com",
  "date_range": "2024-01-01 to 2024-01-28",
  "totals": {
    "clicks": 15000,
    "impressions": 500000,
    "ctr": 3.0,
    "position": 12.5
  }
}

Output: Queries

{
  "queries": [
    {
      "query": "keyword",
      "clicks": 500,
      "impressions": 10000,
      "ctr": 5.0,
      "position": 3.2
    }
  ]
}

Rate Limits

Limit	Value
Queries per minute	1,200
Rows per request	25,000

Site Property Formats

Format	Example
Domain property	sc-domain:example.com
URL prefix	https://www.example.com/

Dependencies

google-api-python-client>=2.100.0
google-auth>=2.23.0
python-dotenv>=1.0.0
rich>=13.7.0
pandas>=2.1.0