mirror of
https://github.com/hanzoskill/gsc.git
synced 2026-10-30 21:11:46 +00:00
345 lines
12 KiB
Python
345 lines
12 KiB
Python
#!/usr/bin/env python3
|
|
"""
|
|
Google Search Console API Query Tool
|
|
|
|
Queries GSC for search analytics, URL inspection, sitemaps, and more.
|
|
|
|
Usage:
|
|
python gsc_query.py search-analytics --site https://example.com --days 28
|
|
python gsc_query.py top-queries --site https://example.com --limit 20
|
|
python gsc_query.py top-pages --site https://example.com --limit 20
|
|
python gsc_query.py inspect-url --site https://example.com --url /some/page
|
|
python gsc_query.py sitemaps --site https://example.com
|
|
python gsc_query.py sites
|
|
"""
|
|
|
|
import argparse
|
|
import json
|
|
import os
|
|
import sys
|
|
from datetime import datetime, timedelta
|
|
from typing import Optional
|
|
|
|
try:
|
|
from google.oauth2.credentials import Credentials
|
|
from googleapiclient.discovery import build
|
|
from googleapiclient.errors import HttpError
|
|
except ImportError:
|
|
print("ERROR: Required packages not installed. Run:")
|
|
print(" pip install google-auth google-auth-oauthlib google-api-python-client")
|
|
sys.exit(1)
|
|
|
|
|
|
def get_credentials() -> Credentials:
|
|
"""Get credentials from environment variables."""
|
|
client_id = os.environ.get("GOOGLE_CLIENT_ID")
|
|
client_secret = os.environ.get("GOOGLE_CLIENT_SECRET")
|
|
refresh_token = os.environ.get("GOOGLE_REFRESH_TOKEN")
|
|
|
|
if not all([client_id, client_secret, refresh_token]):
|
|
print("ERROR: Missing credentials. Set these environment variables:")
|
|
print(" GOOGLE_CLIENT_ID")
|
|
print(" GOOGLE_CLIENT_SECRET")
|
|
print(" GOOGLE_REFRESH_TOKEN")
|
|
sys.exit(1)
|
|
|
|
return Credentials(
|
|
token=None,
|
|
refresh_token=refresh_token,
|
|
token_uri="https://oauth2.googleapis.com/token",
|
|
client_id=client_id,
|
|
client_secret=client_secret,
|
|
scopes=["https://www.googleapis.com/auth/webmasters.readonly"]
|
|
)
|
|
|
|
|
|
def get_service():
|
|
"""Build the Search Console service."""
|
|
creds = get_credentials()
|
|
return build("searchconsole", "v1", credentials=creds)
|
|
|
|
|
|
def list_sites():
|
|
"""List all sites available in Search Console."""
|
|
service = get_service()
|
|
response = service.sites().list().execute()
|
|
sites = response.get("siteEntry", [])
|
|
|
|
if not sites:
|
|
print("No sites found in Search Console.")
|
|
return
|
|
|
|
print(f"Found {len(sites)} site(s):\n")
|
|
for site in sites:
|
|
print(f" {site['siteUrl']}")
|
|
print(f" Permission: {site['permissionLevel']}")
|
|
print()
|
|
|
|
|
|
def search_analytics(site_url: str, days: int = 28, dimensions: list = None,
|
|
row_limit: int = 1000, start_date: str = None, end_date: str = None):
|
|
"""Query search analytics data."""
|
|
service = get_service()
|
|
|
|
if not end_date:
|
|
end_date = (datetime.now() - timedelta(days=3)).strftime("%Y-%m-%d")
|
|
if not start_date:
|
|
start_date = (datetime.now() - timedelta(days=days+3)).strftime("%Y-%m-%d")
|
|
|
|
if not dimensions:
|
|
dimensions = ["query", "page"]
|
|
|
|
request = {
|
|
"startDate": start_date,
|
|
"endDate": end_date,
|
|
"dimensions": dimensions,
|
|
"rowLimit": row_limit,
|
|
"dataState": "final"
|
|
}
|
|
|
|
try:
|
|
response = service.searchanalytics().query(siteUrl=site_url, body=request).execute()
|
|
return response
|
|
except HttpError as e:
|
|
print(f"ERROR: API request failed: {e}")
|
|
sys.exit(1)
|
|
|
|
|
|
def top_queries(site_url: str, days: int = 28, limit: int = 20):
|
|
"""Get top search queries."""
|
|
response = search_analytics(site_url, days=days, dimensions=["query"], row_limit=limit)
|
|
rows = response.get("rows", [])
|
|
|
|
if not rows:
|
|
print("No query data found.")
|
|
return
|
|
|
|
print(f"Top {len(rows)} queries (last {days} days):\n")
|
|
print(f"{'Query':<50} {'Clicks':>8} {'Impressions':>12} {'CTR':>8} {'Position':>10}")
|
|
print("-" * 92)
|
|
|
|
for row in rows:
|
|
query = row["keys"][0][:48]
|
|
clicks = row.get("clicks", 0)
|
|
impressions = row.get("impressions", 0)
|
|
ctr = row.get("ctr", 0) * 100
|
|
position = row.get("position", 0)
|
|
print(f"{query:<50} {clicks:>8} {impressions:>12} {ctr:>7.1f}% {position:>10.1f}")
|
|
|
|
|
|
def top_pages(site_url: str, days: int = 28, limit: int = 20):
|
|
"""Get top pages by clicks."""
|
|
response = search_analytics(site_url, days=days, dimensions=["page"], row_limit=limit)
|
|
rows = response.get("rows", [])
|
|
|
|
if not rows:
|
|
print("No page data found.")
|
|
return
|
|
|
|
print(f"Top {len(rows)} pages (last {days} days):\n")
|
|
print(f"{'Page':<70} {'Clicks':>8} {'Impressions':>12} {'CTR':>8} {'Position':>10}")
|
|
print("-" * 112)
|
|
|
|
for row in rows:
|
|
page = row["keys"][0]
|
|
# Truncate long URLs
|
|
if len(page) > 68:
|
|
page = page[:65] + "..."
|
|
clicks = row.get("clicks", 0)
|
|
impressions = row.get("impressions", 0)
|
|
ctr = row.get("ctr", 0) * 100
|
|
position = row.get("position", 0)
|
|
print(f"{page:<70} {clicks:>8} {impressions:>12} {ctr:>7.1f}% {position:>10.1f}")
|
|
|
|
|
|
def query_page_analysis(site_url: str, days: int = 28, limit: int = 50):
|
|
"""Get query-page combinations for deeper analysis."""
|
|
response = search_analytics(site_url, days=days, dimensions=["query", "page"], row_limit=limit)
|
|
rows = response.get("rows", [])
|
|
|
|
if not rows:
|
|
print("No data found.")
|
|
return
|
|
|
|
# Output as JSON for easier parsing
|
|
print(json.dumps(rows, indent=2))
|
|
|
|
|
|
def low_ctr_opportunities(site_url: str, days: int = 28, min_impressions: int = 100):
|
|
"""Find high-impression, low-CTR opportunities."""
|
|
response = search_analytics(site_url, days=days, dimensions=["query", "page"], row_limit=500)
|
|
rows = response.get("rows", [])
|
|
|
|
if not rows:
|
|
print("No data found.")
|
|
return
|
|
|
|
# Filter for high impressions, low CTR
|
|
opportunities = [
|
|
row for row in rows
|
|
if row.get("impressions", 0) >= min_impressions and row.get("ctr", 0) < 0.03
|
|
]
|
|
|
|
# Sort by impressions descending
|
|
opportunities.sort(key=lambda x: x.get("impressions", 0), reverse=True)
|
|
|
|
print(f"Low CTR Opportunities (impressions >= {min_impressions}, CTR < 3%):\n")
|
|
print(f"{'Query':<40} {'Page':<50} {'Impr':>8} {'CTR':>7} {'Pos':>6}")
|
|
print("-" * 115)
|
|
|
|
for row in opportunities[:20]:
|
|
query = row["keys"][0][:38]
|
|
page = row["keys"][1]
|
|
if len(page) > 48:
|
|
page = "..." + page[-45:]
|
|
impressions = row.get("impressions", 0)
|
|
ctr = row.get("ctr", 0) * 100
|
|
position = row.get("position", 0)
|
|
print(f"{query:<40} {page:<50} {impressions:>8} {ctr:>6.1f}% {position:>6.1f}")
|
|
|
|
|
|
def inspect_url(site_url: str, url: str):
|
|
"""Inspect a specific URL's indexing status."""
|
|
service = get_service()
|
|
|
|
# URL inspection requires the full URL
|
|
if not url.startswith("http"):
|
|
url = site_url.rstrip("/") + "/" + url.lstrip("/")
|
|
|
|
request = {
|
|
"inspectionUrl": url,
|
|
"siteUrl": site_url
|
|
}
|
|
|
|
try:
|
|
response = service.urlInspection().index().inspect(body=request).execute()
|
|
result = response.get("inspectionResult", {})
|
|
|
|
print(f"URL Inspection: {url}\n")
|
|
|
|
# Index status
|
|
index_status = result.get("indexStatusResult", {})
|
|
print("Index Status:")
|
|
print(f" Verdict: {index_status.get('verdict', 'Unknown')}")
|
|
print(f" Coverage State: {index_status.get('coverageState', 'Unknown')}")
|
|
print(f" Crawled As: {index_status.get('crawledAs', 'Unknown')}")
|
|
print(f" Last Crawl Time: {index_status.get('lastCrawlTime', 'Unknown')}")
|
|
|
|
# Mobile usability
|
|
mobile = result.get("mobileUsabilityResult", {})
|
|
if mobile:
|
|
print(f"\nMobile Usability:")
|
|
print(f" Verdict: {mobile.get('verdict', 'Unknown')}")
|
|
|
|
# Rich results
|
|
rich = result.get("richResultsResult", {})
|
|
if rich:
|
|
print(f"\nRich Results:")
|
|
print(f" Verdict: {rich.get('verdict', 'Unknown')}")
|
|
|
|
except HttpError as e:
|
|
print(f"ERROR: URL inspection failed: {e}")
|
|
|
|
|
|
def list_sitemaps(site_url: str):
|
|
"""List all sitemaps for a site."""
|
|
service = get_service()
|
|
|
|
try:
|
|
response = service.sitemaps().list(siteUrl=site_url).execute()
|
|
sitemaps = response.get("sitemap", [])
|
|
|
|
if not sitemaps:
|
|
print("No sitemaps found.")
|
|
return
|
|
|
|
print(f"Sitemaps for {site_url}:\n")
|
|
for sm in sitemaps:
|
|
print(f" {sm.get('path')}")
|
|
print(f" Type: {sm.get('type', 'Unknown')}")
|
|
print(f" Last Submitted: {sm.get('lastSubmitted', 'Unknown')}")
|
|
print(f" Last Downloaded: {sm.get('lastDownloaded', 'Unknown')}")
|
|
print(f" Warnings: {sm.get('warnings', 0)}")
|
|
print(f" Errors: {sm.get('errors', 0)}")
|
|
print()
|
|
|
|
except HttpError as e:
|
|
print(f"ERROR: Failed to list sitemaps: {e}")
|
|
|
|
|
|
def main():
|
|
parser = argparse.ArgumentParser(description="Google Search Console Query Tool")
|
|
subparsers = parser.add_subparsers(dest="command", help="Command to run")
|
|
|
|
# sites command
|
|
subparsers.add_parser("sites", help="List all sites in Search Console")
|
|
|
|
# search-analytics command
|
|
sa_parser = subparsers.add_parser("search-analytics", help="Raw search analytics query")
|
|
sa_parser.add_argument("--site", required=True, help="Site URL (e.g., https://example.com)")
|
|
sa_parser.add_argument("--days", type=int, default=28, help="Number of days (default: 28)")
|
|
sa_parser.add_argument("--dimensions", nargs="+", default=["query", "page"],
|
|
help="Dimensions: query, page, country, device, date")
|
|
sa_parser.add_argument("--limit", type=int, default=100, help="Row limit")
|
|
|
|
# top-queries command
|
|
tq_parser = subparsers.add_parser("top-queries", help="Get top search queries")
|
|
tq_parser.add_argument("--site", required=True, help="Site URL")
|
|
tq_parser.add_argument("--days", type=int, default=28, help="Number of days")
|
|
tq_parser.add_argument("--limit", type=int, default=20, help="Number of results")
|
|
|
|
# top-pages command
|
|
tp_parser = subparsers.add_parser("top-pages", help="Get top pages")
|
|
tp_parser.add_argument("--site", required=True, help="Site URL")
|
|
tp_parser.add_argument("--days", type=int, default=28, help="Number of days")
|
|
tp_parser.add_argument("--limit", type=int, default=20, help="Number of results")
|
|
|
|
# opportunities command
|
|
opp_parser = subparsers.add_parser("opportunities", help="Find low-CTR optimization opportunities")
|
|
opp_parser.add_argument("--site", required=True, help="Site URL")
|
|
opp_parser.add_argument("--days", type=int, default=28, help="Number of days")
|
|
opp_parser.add_argument("--min-impressions", type=int, default=100, help="Minimum impressions")
|
|
|
|
# inspect-url command
|
|
iu_parser = subparsers.add_parser("inspect-url", help="Inspect URL indexing status")
|
|
iu_parser.add_argument("--site", required=True, help="Site URL")
|
|
iu_parser.add_argument("--url", required=True, help="URL to inspect")
|
|
|
|
# sitemaps command
|
|
sm_parser = subparsers.add_parser("sitemaps", help="List sitemaps")
|
|
sm_parser.add_argument("--site", required=True, help="Site URL")
|
|
|
|
# query-page command (JSON output)
|
|
qp_parser = subparsers.add_parser("query-page", help="Query-page combinations (JSON)")
|
|
qp_parser.add_argument("--site", required=True, help="Site URL")
|
|
qp_parser.add_argument("--days", type=int, default=28, help="Number of days")
|
|
qp_parser.add_argument("--limit", type=int, default=50, help="Row limit")
|
|
|
|
args = parser.parse_args()
|
|
|
|
if not args.command:
|
|
parser.print_help()
|
|
sys.exit(1)
|
|
|
|
if args.command == "sites":
|
|
list_sites()
|
|
elif args.command == "search-analytics":
|
|
response = search_analytics(args.site, args.days, args.dimensions, args.limit)
|
|
print(json.dumps(response, indent=2))
|
|
elif args.command == "top-queries":
|
|
top_queries(args.site, args.days, args.limit)
|
|
elif args.command == "top-pages":
|
|
top_pages(args.site, args.days, args.limit)
|
|
elif args.command == "opportunities":
|
|
low_ctr_opportunities(args.site, args.days, args.min_impressions)
|
|
elif args.command == "inspect-url":
|
|
inspect_url(args.site, args.url)
|
|
elif args.command == "sitemaps":
|
|
list_sitemaps(args.site)
|
|
elif args.command == "query-page":
|
|
query_page_analysis(args.site, args.days, args.limit)
|
|
|
|
|
|
if __name__ == "__main__":
|
|
main()
|