google-search-console

Google Search Console Skill

Created by Return Zero Inc.

Comprehensive Google Search Console API skill for Claude Code providing search analytics, URL inspection, sitemap management, and site verification capabilities.

When to Use

• User mentions "Google Search Console", "GSC", "search console"
• User asks about search performance, clicks, impressions, CTR
• User needs URL indexing status or inspection
• User wants to manage sitemaps
• User asks about search rankings or index status
• User needs SEO analytics data from Google

Features

1. Search Analytics ⭐

• Query search performance data (clicks, impressions, CTR, position)
• Filter by date range, page, query, country, device
• Group by dimensions (query, page, country, device, date)
• Compare time periods
• Export to CSV/JSON

2. URL Inspection

• Check indexing status of specific URLs
• View crawl information
• Check mobile usability
• Identify indexing issues
• Request indexing for URLs

3. Sitemap Management

• List all sitemaps for a site
• Submit new sitemaps
• Delete sitemaps
• Check sitemap status and errors

4. Site Management

• List all verified sites
• Add new sites
• Remove sites
• Check verification status

Environment Variables

This skill uses environment variables managed by jelly-dotenv. See skills/jelly-dotenv/SKILL.md for configuration details.

Option 1: Service Account (Recommended)

# Service account JSON key file path
GOOGLE_SERVICE_ACCOUNT_KEY_FILE=/path/to/service-account.json

# Or inline JSON (for CI/CD environments)
GOOGLE_SERVICE_ACCOUNT_KEY_JSON='{"type":"service_account","project_id":"...","private_key":"..."}'

Option 2: OAuth 2.0 Client Credentials

GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_REFRESH_TOKEN=your-refresh-token

Common Settings

# Default site URL (optional, can be specified per request)
GOOGLE_SEARCH_CONSOLE_SITE_URL=https://your-site.com

# Alternative naming patterns (auto-detected)
GSC_SITE_URL=https://your-site.com
SEARCH_CONSOLE_SITE=sc-domain:your-site.com

Variables can be configured in either:

• skills/jelly-dotenv/.env (skill-common, highest priority)
• Project root /.env (project-specific, fallback)

Configuration

Setting Up Service Account

1. Go to Google Cloud Console
2. Create a new project or select existing one
3. Enable "Google Search Console API"
4. Create a Service Account:
   • Go to IAM & Admin → Service Accounts
   • Create service account
   • Download JSON key file
5. Add service account email to Search Console:
   • Go to Search Console
   • Settings → Users and permissions
   • Add user with service account email
   • Grant "Full" or "Restricted" access

Setting Up OAuth 2.0

1. Go to Google Cloud Console
2. Create OAuth 2.0 credentials (Web application)
3. Set authorized redirect URI
4. Use OAuth playground or your app to get refresh token
5. Required scope: https://www.googleapis.com/auth/webmasters.readonly

Usage Scenarios

Scenario 1: Search Performance Overview

User Request: "Show me search performance for the last 7 days"

Skill Actions:

1. Load credentials from environment
2. Query Search Analytics API with date range
3. Aggregate clicks, impressions, CTR, position
4. Format as Markdown table with trends

Output:

## Search Performance (Last 7 Days)

| Metric | Value | Change |
|--------|-------|--------|
| Clicks | 1,234 | +12% |
| Impressions | 45,678 | +8% |
| CTR | 2.7% | +0.3% |
| Avg Position | 15.2 | -2.1 |

### Top Queries
| Query | Clicks | Impressions | CTR | Position |
|-------|--------|-------------|-----|----------|
| keyword 1 | 234 | 5,678 | 4.1% | 8.5 |
| keyword 2 | 189 | 4,321 | 4.4% | 12.3 |

Scenario 2: URL Inspection

User Request: "Check indexing status for https://example.com/page"

Skill Actions:

1. Call URL Inspection API
2. Parse indexing result
3. Check coverage status
4. Display mobile usability

Output:

## URL Inspection: https://example.com/page

| Property | Status |
|----------|--------|
| Index Status | ✅ Indexed |
| Crawled | 2024-01-15 |
| Canonical | https://example.com/page |
| Mobile Usability | ✅ Mobile friendly |
| Rich Results | ⚠️ 2 warnings |

Scenario 3: Sitemap Management

User Request: "Show all sitemaps and submit a new one"

Skill Actions:

1. List existing sitemaps
2. Show status and last submitted date
3. Submit new sitemap URL
4. Confirm submission

Scenario 4: Top Pages Analysis

User Request: "What are my top performing pages?"

Skill Actions:

1. Query Search Analytics grouped by page
2. Sort by clicks
3. Include impressions, CTR, position
4. Highlight pages with high impressions but low CTR

API Reference

Search Analytics Query

interface SearchAnalyticsRequest {
  startDate: string;      // YYYY-MM-DD
  endDate: string;        // YYYY-MM-DD
  dimensions?: ('query' | 'page' | 'country' | 'device' | 'date')[];
  searchType?: 'web' | 'image' | 'video' | 'news';
  dimensionFilterGroups?: FilterGroup[];
  aggregationType?: 'auto' | 'byPage' | 'byProperty';
  rowLimit?: number;      // Max 25000
  startRow?: number;
}

URL Inspection

interface UrlInspectionRequest {
  inspectionUrl: string;
  siteUrl: string;
  languageCode?: string;
}

Sitemap Operations

Operation	Method	Endpoint
List	GET	/webmasters/v3/sites/{siteUrl}/sitemaps
Get	GET	/webmasters/v3/sites/{siteUrl}/sitemaps/{feedpath}
Submit	PUT	/webmasters/v3/sites/{siteUrl}/sitemaps/{feedpath}
Delete	DELETE	/webmasters/v3/sites/{siteUrl}/sitemaps/{feedpath}

Output Formats

Markdown (Default)

• Formatted tables with metrics
• Trend indicators (↑↓)
• Status icons (✅⚠️❌)
• Summary insights

JSON

• Raw API response
• Full data structure
• Programmatic access

CSV

• Spreadsheet-compatible export
• All data rows
• For further analysis

Error Handling

Authentication Errors

Error	Cause	Solution
401 Unauthorized	Invalid credentials	Check service account key or OAuth tokens
403 Forbidden	No access to site	Add service account to Search Console
Invalid scope	Wrong OAuth scope	Use webmasters.readonly scope

API Errors

Error	Cause	Solution
404 Not Found	Site not in Search Console	Add site to Search Console first
400 Bad Request	Invalid parameters	Check date format (YYYY-MM-DD)
429 Rate Limit	Too many requests	Wait and retry with backoff

Common Issues

"Configuration error: No Google credentials found"

# Solution: Add credentials to .env
GOOGLE_SERVICE_ACCOUNT_KEY_FILE=/path/to/key.json

"Site not found or no access"

# Solution: Add service account email to Search Console
# Go to: Search Console → Settings → Users and permissions

"Invalid date range"

# Solution: Use YYYY-MM-DD format, max 16 months historical data

Security Policy

Authentication

• Service Account: Recommended for server-side usage
• OAuth 2.0: For user-authenticated requests
• Credentials: Loaded from environment variables only
• Logging: Private keys and tokens automatically redacted

Data Access

• Read-Only by Default: Uses webmasters.readonly scope
• Write Operations: Sitemap submit/delete requires full scope
• Site-Scoped: Access limited to authorized sites only

Rate Limiting

• Automatic: Respects Google API quotas
• Retry: Exponential backoff on 429 errors
• Daily Quota: 1,200 queries per day (default)

Limitations

• Historical Data: Maximum 16 months of search data
• Data Freshness: 2-3 day delay for search analytics
• URL Inspection: 2,000 requests per day per site
• Row Limit: Maximum 25,000 rows per query
• Dimensions: Maximum 3 dimensions per query

Integration with Claude Code

This skill activates automatically when users mention:

• "google search console", "gsc", "search console"
• "search performance", "search analytics"
• "url inspection", "index status"
• "sitemap", "sitemap management"
• "seo analytics", "seo data"

The skill will:

1. Load Google credentials from .env
2. Execute the requested query/operation
3. Format results as Markdown tables
4. Provide actionable insights and recommendations

References

• Google Search Console API Documentation
• Search Analytics API Reference
• URL Inspection API Reference
• OAuth 2.0 Setup
• API Quotas and Limits