GSC Analytics Skill

An open, reusable Codex skill for Google Search Console analysis. It helps agents fetch search performance data, find SEO opportunities, inspect indexing status, manage sitemaps, and generate charts from real GSC data.

中文文档

Features

• Search analytics by query, page, country, device, date, and search appearance
• SEO opportunity detection: quick wins, low-hanging fruit, CTR gaps, keyword cannibalization
• Page-level query analysis for content optimization
• URL Inspection API checks for indexation, crawling, robots, canonical, mobile usability, and rich results
• Sitemap listing, detail checks, and submission
• JSON/CSV exports and chart generation
• Fully environment-driven configuration with no hard-coded site or credential paths

Requirements

• Python 3.9+
• A Google Cloud service account JSON key
• The service account email added to your Google Search Console property

Install dependencies:

python3 -m pip install -r requirements.txt

Setup

1. Create a Google Cloud service account and download its JSON key.
2. Add the service account email as a user in Google Search Console.
3. Copy .env.example and set your values:

cp .env.example .env

Example shell setup:

export GSC_SERVICE_ACCOUNT_JSON="/absolute/path/to/service-account.json"
export DEFAULT_SITE_URL="sc-domain:example.com"
export GSC_OUTPUT_DIR="./gsc-output"
export GSC_CHARTS_DIR="./gsc-output/charts"

GOOGLE_APPLICATION_CREDENTIALS is also supported as a fallback for the service account key path.

Quick Start

List properties available to the service account:

python3 scripts/list_properties.py

Get a 28-day performance overview:

python3 scripts/get_performance_overview.py --days 28

Fetch top queries:

python3 scripts/get_search_analytics.py \
  --dimensions query \
  --days 30 \
  --limit 50 \
  --output table

Export daily trend data:

python3 scripts/get_search_analytics.py \
  --dimensions date \
  --days 30 \
  --output json

Generate a chart:

python3 scripts/visualize.py \
  --input ./gsc-output/gsc_output.json \
  --chart_type trend \
  --metrics clicks,impressions \
  --title "30-Day Search Trend"

Inspect a URL:

python3 scripts/inspect_url.py \
  --url "https://www.example.com/blog/example-article"

Configuration

Variable	Required	Description
GSC_SERVICE_ACCOUNT_JSON	Yes	Absolute path to the service account JSON key
GOOGLE_APPLICATION_CREDENTIALS	Optional	Fallback service account JSON path
DEFAULT_SITE_URL	Recommended	Default GSC property, e.g. sc-domain:example.com
GSC_OUTPUT_DIR	Optional	JSON/CSV output directory, defaults to ./gsc-output
GSC_CHARTS_DIR	Optional	Chart output directory, defaults to ./gsc-output/charts
GSC_API_SCOPES	Optional	OAuth scopes, defaults to full Search Console scope

For read-only usage:

export GSC_API_SCOPES="https://www.googleapis.com/auth/webmasters.readonly"

Scripts

Script	Purpose
list_properties.py	List GSC properties accessible to the service account
get_performance_overview.py	Compare current and previous performance windows
get_search_analytics.py	Flexible Search Analytics query tool
get_advanced_search_analytics.py	Find quick wins, low-hanging fruit, CTR gaps, cannibalization
get_search_by_page_query.py	Analyze all queries driving a specific page
compare_search_periods.py	Compare two custom date ranges
inspect_url.py	Inspect one URL with URL Inspection API
batch_url_inspection.py	Inspect multiple URLs
check_indexing_issues.py	Prioritize indexing problems
list_sitemaps.py	List submitted sitemaps
get_sitemap_details.py	Inspect sitemap details
submit_sitemap.py	Submit a sitemap
visualize.py	Generate trend, bar, scatter, distribution, heatmap, and comparison charts

Public Repo Safety

Do not commit:

• Service account JSON files
• .env
• Raw GSC exports for private sites
• Client or company-specific reports

This repository includes .gitignore rules for common sensitive files, but you should still review commits before pushing.

License

Add your preferred license before publishing.