gsc-portfolio-audit

GSC Portfolio Audit

Answers "how is everything doing?" across every property on a Search Console account, which is the question the per-site tooling can't answer without dozens of manual exports.

Setup

Requires an OAuth refresh token with https://www.googleapis.com/auth/webmasters.readonly:

export GOOGLE_GSC_CLIENT_ID=...      # or GOOGLE_CLIENT_ID
export GOOGLE_GSC_CLIENT_SECRET=...  # or GOOGLE_CLIENT_SECRET
export GOOGLE_REFRESH_TOKEN=...
export GSC_EXCLUDE="olddomain.com"   # optional, comma-separated
pip install requests

The most common setup failure is unauthorized_client on token refresh. It means the refresh token was issued for a different OAuth client than the id/secret you paired with it. Accounts that have added Google integrations over time usually have several clients; match the pair that minted the token.

Run it

python3 scripts/audit_gsc.py            # full: ranking + keyword diff for the top 12
python3 scripts/audit_gsc.py portfolio  # just the ranked table
python3 scripts/audit_gsc.py queries --site sc-domain:example.com
python3 scripts/audit_gsc.py --days 90  # quarter over quarter

Flags: --days (window, compared against the window immediately before it), --site (repeatable), --top, --limit, --min-clicks.

Sections and what they mean

Section	Read it as
NEW	queries with zero clicks last period. Where growth is actually coming from.
RISING	up ≥50%. Check whether position moved too — if it didn't, demand rose, not your ranking.
DROPPING	down ≥40% off a real base. Position tells you which kind: rank fell = ranking loss; rank held but clicks collapsed = something took the clicks above you (AI Overview, a new SERP feature, or the query changed shape).
LOST	ranked before, no data now.
CTR GAP	≥1,500 impressions, top 10, under 2% CTR. Title and description rewrites, the cheapest wins available.

Interpreting

• Report clicks first, impressions second. One large property can swing portfolio impressions enough to mask that everything else grew.
• Separate brand from non-brand. A site whose entire keyword set is its own name (or misspellings of a competitor's) has no acquisition engine, however good the click count looks. Say so plainly in the report.
• A whole-site collapse on its own head term is usually not SEO. Check ownership before diagnosing rankings: whois <domain> | grep -i "registrar\|updated date" plus whether it still resolves. Expired, transferred, or disputed domains produce a textbook ranking cliff that no amount of SEO work will fix.
• "new" in the portfolio table means zero clicks in the prior window, which for a recently launched site is a launch, not a data gap.
• Don't skip queries in languages you can't read. On multi-market sites the growth is usually in non-English long tail; translate the interesting ones rather than filtering them out.
• A property returning 403 is verified for listing but not for search analytics. The script reports it instead of hiding it.