Google Search Console

Query Google Search Console API for search performance data, URL inspection, sitemap management, and comprehensive SEO analysis.

Quick Start

Prerequisites

• Google Cloud project with Search Console API enabled
• OAuth credentials or Service Account JSON
• Site verified in Google Search Console

First Query

# Using the wrapper library (recommended)
import searchconsole

account = searchconsole.authenticate(
    client_config='client_secrets.json',
    serialize='credentials.json'  # Saves tokens for reuse
)

# List available properties
for site in account:
    print(site.url)

# Query last 7 days of data
site = account['https://example.com/']
report = site.query.range('today', days=-7).dimension('query').get()
df = report.to_dataframe()

Authentication Setup

See references/setup_guide.md for step-by-step credential creation.

API Capabilities Overview

This skill provides full access to all Google Search Console API endpoints:

Search Types Supported

• web - Standard web search results
• image - Google Images results
• video - Video search results
• news - Google News results
• discover - Google Discover feed
• googleNews - Google News app/website

Dimensions Available

• query - Search keywords
• page - URL of the page
• country - Country code (ISO 3166-1 alpha-3)
• device - Device type (DESKTOP, MOBILE, TABLET)
• date - Date of the search
• searchAppearance - How the result appeared in search

Search Appearance Types

• AMP_ARTICLE - AMP articles
• AMP_STORY - AMP stories
• INSTANT_APP - Android Instant Apps
• JOB_LISTING - Job posting rich results
• JOB_DETAILS - Job details rich results
• MERCHANT_LISTINGS - Product listings
• ORGANIC_SHOPPING - Organic shopping results
• PRODUCT_SNIPPETS - Product rich snippets
• RECIPE_FEATURE - Recipe rich results
• REVIEW_SNIPPET - Review stars
• SPECIAL_ANNOUNCEMENT - COVID-19 announcements
• SUBSCRIBED_CONTENT - Reader Revenue Manager content
• VIDEO - Video rich results
• WEB_LIGHT - Web Light results
• WEBLINKING - Regular web results

Core Workflows

1. Content Optimization (Low CTR / High Impressions)

Find pages with traffic potential but poor click-through rates:

# Run scripts/analyze_opportunities.py or use this pattern:
df = site.query \
    .range('today', days=-28) \
    .dimension('query', 'page') \
    .get().to_dataframe()

# Filter: high impressions, low CTR, decent position
opportunities = df[
    (df['impressions'] > 100) &
    (df['ctr'] < 0.03) &  # Below 3% CTR
    (df['position'] < 20)  # Within striking distance
].sort_values('impressions', ascending=False)

Action items from this data:

• Improve title tags and meta descriptions for low-CTR pages
• Check if search intent matches content
• Add rich snippets/structured data

2. Best Performing Pages Analysis

Comprehensive analysis of top pages with scoring and categorization:

# Full top pages report with performance scores
uv run python scripts/top_pages.py \
    --site "https://example.com/" \
    --key-file service_account.json \
    --sort-by performance_score

# With device breakdown
uv run python scripts/top_pages.py \
    --site "https://example.com/" \
    --key-file service_account.json \
    --breakdown device

# Compare to previous period
uv run python scripts/top_pages.py \
    --site "https://example.com/" \
    --key-file service_account.json \
    --compare-period

Features:

• Performance scoring (0-100) based on clicks, impressions, CTR, position
• Tier categorization (Star Performers, Solid Performers, Developing, Low Traffic)
• Period-over-period comparison with change tracking
• Device, country, query, and search appearance breakdowns

3. Keyword Discovery

Find queries you're ranking for but haven't optimized:

df = site.query \
    .range('today', days=-90) \
    .dimension('query') \
    .get().to_dataframe()

# High impressions but not in top 10
discoveries = df[
    (df['impressions'] > 500) &
    (df['position'] > 10) &
    (df['position'] < 30)
].sort_values('impressions', ascending=False)

4. Performance Tracking

Monitor ranking trends over time:

# Daily breakdown for trend analysis
df = site.query \
    .range('today', days=-90) \
    .dimension('date', 'query') \
    .filter('query', 'your keyword', 'contains') \
    .get().to_dataframe()

# Group by date to see trends
trends = df.groupby('date').agg({
    'clicks': 'sum',
    'impressions': 'sum',
    'position': 'mean'
})

5. Technical SEO (URL Inspection)

Check index status for specific URLs:

# Using scripts/url_inspection.py or directly:
from googleapiclient.discovery import build
from google.oauth2 import service_account

credentials = service_account.Credentials.from_service_account_file(
    'service_account.json',
    scopes=['https://www.googleapis.com/auth/webmasters.readonly']
)

service = build('searchconsole', 'v1', credentials=credentials)

result = service.urlInspection().index().inspect(body={
    'inspectionUrl': 'https://example.com/page',
    'siteUrl': 'https://example.com/'
}).execute()

# Check index status
index_status = result['inspectionResult']['indexStatusResult']
print(f"Verdict: {index_status['verdict']}")
print(f"Coverage: {index_status['coverageState']}")
print(f"Last crawl: {index_status.get('lastCrawlTime', 'Never')}")

# Check mobile usability
mobile = result['inspectionResult'].get('mobileUsabilityResult', {})
print(f"Mobile: {mobile.get('verdict', 'N/A')}")

# Check rich results
rich = result['inspectionResult'].get('richResultsResult', {})
if rich.get('detectedItems'):
    for item in rich['detectedItems']:
        print(f"Rich Result: {item['richResultType']}")

6. Sitemap Management

Full sitemap lifecycle management:

# List all sitemaps
uv run python scripts/sitemaps.py \
    --site "https://example.com/" --key-file service_account.json list

# Submit a new sitemap
uv run python scripts/sitemaps.py \
    --site "https://example.com/" --key-file service_account.json \
    submit https://example.com/sitemap.xml

# Check sitemap health
uv run python scripts/sitemaps.py \
    --site "https://example.com/" --key-file service_account.json health

# Delete a sitemap
uv run python scripts/sitemaps.py \
    --site "https://example.com/" --key-file service_account.json \
    delete https://example.com/old-sitemap.xml

Health check provides:

• Total sitemaps count
• URLs submitted vs indexed
• Index rate percentage
• Errors and warnings per sitemap

7. Comprehensive Performance Report

Generate all-in-one SEO report using every API endpoint:

# Full comprehensive report
uv run python scripts/comprehensive_report.py \
    --site "https://example.com/" --key-file service_account.json

# With URL inspection for top 10 pages
uv run python scripts/comprehensive_report.py \
    --site "https://example.com/" --key-file service_account.json \
    --inspect-top-pages 10

# Export to directory
uv run python scripts/comprehensive_report.py \
    --site "https://example.com/" --key-file service_account.json \
    --output-dir ./gsc_report/

Report includes:

• Performance by all search types (web, image, video, news, discover, googleNews)
• Device breakdown (desktop, mobile, tablet)
• Country breakdown
• Search appearance analysis
• Daily trends with best/worst days
• Top pages and queries
• Sitemap health status
• Optimization opportunities
• URL inspection results (optional)

API Endpoints Reference

See references/api_endpoints.md for complete API documentation.

Bundled Scripts

scripts/auth.py

Authentication utilities supporting both OAuth and Service Account:

uv run --with google-api-python-client,google-auth-oauthlib python scripts/auth.py

scripts/search_analytics.py

Query search performance data with common filters:

uv run python scripts/search_analytics.py --site "https://example.com/" --days 28

scripts/top_pages.py

Comprehensive top pages analysis with scoring:

uv run python scripts/top_pages.py --site "https://example.com/" --key-file service_account.json

scripts/url_inspection.py

Batch check URL index status:

uv run python scripts/url_inspection.py --site "https://example.com/" --urls urls.txt

scripts/analyze_opportunities.py

Generate content optimization report:

uv run python scripts/analyze_opportunities.py --site "https://example.com/" --output report.csv

scripts/sitemaps.py

Full sitemap management (list, submit, delete, health):

uv run python scripts/sitemaps.py --site "https://example.com/" --key-file service_account.json list

scripts/comprehensive_report.py

All-in-one SEO report using every endpoint:

uv run python scripts/comprehensive_report.py --site "https://example.com/" --key-file service_account.json

Rate Limits & Best Practices

Quotas:

• 20 queries/second, 200 queries/minute per user
• Queries with page + query dimensions are expensive
• URL Inspection: 2,000 URLs/day per property
• Data has 2-3 day delay (not real-time)

Optimization tips:

• Cache API responses (data updates daily, not real-time)
• Use shorter date ranges for expensive queries
• Batch URL inspections across properties if hitting limits
• Paginate large result sets (max 25,000 rows per request)

See references/analysis_patterns.md for advanced analysis formulas.

Multiple Properties

Query across multiple sites:

account = searchconsole.authenticate(client_config='client_secrets.json')

all_data = []
for site in account:
    df = site.query.range('today', days=-7).dimension('query').get().to_dataframe()
    df['site'] = site.url
    all_data.append(df)

combined = pd.concat(all_data, ignore_index=True)

Filter Operators

When filtering data, these operators are available:

Data Aggregation Types

Common Issues

"You do not own this site": Ensure service account email is added as user in Search Console Settings > Users and permissions with Full access.

Empty results: Data has 2-3 day delay. Query older dates.

Quota exceeded: Wait 15 minutes (short-term) or spread queries throughout day (long-term).

"Invalid site URL": Use exact format from Search Console (include trailing slash for URL-prefix properties, use sc-domain: prefix for domain properties).