GSC opportunity analysis tool

What the GSC opportunity analysis tool does

The GSC Opportunity Engine turns a Search Console Performance export into a short, inspectable queue of queries and pages worth reviewing. It is designed for the point where a property already has impressions but the Search Console table is too broad to answer the operational question: which existing search signal deserves the next hour of work? Upload the current Queries CSV, optionally add an equal prior period and the current Pages CSV, and the tool labels striking-distance rows, site-relative CTR gaps, rising demand, decay, and page-level opportunities.

This is not an automatic SEO audit and it does not claim that a title rewrite, content update, or internal link caused a movement. Each output row separates the observed evidence from the recommended verification step. That distinction matters because average position, CTR, and impressions can move with demand, device mix, SERP features, competitors, indexing, or a page edit. The engine helps you triage evidence; the person reviewing the live result still makes the decision.

All parsing and scoring happens in the browser. The CSV rows, search queries, URLs, and generated evidence ledger are not posted to SEO Report Kit. Anonymous analytics records only broad actions such as running the engine or choosing an export format, never the imported values. You can inspect the workflow with the synthetic example before using a client property.

Prepare the Search Console CSV exports

Open the Search results Performance report in Google Search Console and choose a complete date range. For recurring monthly work, compare equal windows and avoid a range that includes preliminary days. Export the Queries table for the current period as CSV. To detect momentum, repeat the export for the immediately preceding period with the same search type and filters. The optional Pages export must use the same current date range and filters as the current Queries file.

The engine accepts the ordinary English column labels used by Search Console: Top queries or Query, Clicks, Impressions, CTR, and Position; for a page file it expects Top pages or Page. A current query file is enough for striking-distance and CTR analysis. The prior file enables rising and decay rules. The page file creates a separate page queue, because a query-only export does not prove which URL earned that query. The tool deliberately does not guess that relationship.

Search Console exports are evidence samples, not a complete warehouse. The standard report export is limited to the rows available in the table, anonymized queries are omitted, and chart totals can differ from grouped table rows because of privacy and aggregation. Preserve the date range, search type, country or device filters, and export date in the report you send so another reviewer knows exactly what the rows represent.

• Use complete, equal-length periods when adding a prior Queries CSV.
• Keep search type and all country, device, query, and page filters identical between periods.
• Export Pages separately instead of assigning a query to a URL by assumption.
• Treat zero values carefully because unavailable values in the Search Console interface can become zeros in an export.

Run the same rules from a CLI or GitHub Action

The open-source GSC Opportunity Analyzer runs the same versioned decision rules outside the browser workspace. Install @demi-valerith/gsc-opportunity-analyzer from npm for a local monthly script, or add the GitHub Action to a private reporting repository and produce a Markdown, JSON, or CSV evidence ledger during a workflow. Both surfaces accept the current Queries export plus the same optional prior Queries and current Pages files, minimum-impression threshold, and striking-distance range.

The Action logs only the number of findings and the output path. It does not print imported rows or send them to SEO Report Kit, but Search Console queries and page URLs can still contain confidential business information. Keep client exports in a private repository, upload only the generated ledger as a workflow artifact, and set an appropriate retention period. The public repository includes synthetic fixtures, tests for all five rule types, and the exact rules version so a reviewer can reproduce a result.

Automation does not turn a triage label into an SEO instruction. Review the generated evidence against the live Search result, the ranking URL, seasonality, indexing, and the site's change history before opening an implementation issue. Pin the Action to a release tag or commit SHA, and record the rules version with the reporting period when reproducibility matters.

• Use the browser workspace for ad hoc analysis with no installation.
• Use the CLI when exports already live in a local reporting process.
• Use the GitHub Action only in a repository whose visibility and artifact retention match the sensitivity of the GSC data.
• Treat every generated row as a verification queue, not a traffic forecast or causal claim.

Input and evidence fields

The workspace keeps its input contract small. It reads the four Search Console metrics and adds a priority score, confidence label, evidence sentence, and recommended check. The field map below explains how each part is used. None of the generated fields replaces the source export, so keep the original files with the exported ledger when a client or teammate may need to reproduce the result.

How the opportunity rules work

Striking distance is the simplest rule: a row has at least the minimum impressions and falls inside the position range you selected. The default is positions 8 through 20, which includes results near the bottom of page one and on page two. It does not automatically mean expand the article. First open the query in Search Console, confirm the ranking URL, inspect the live result, and decide whether intent, evidence, or internal-link support is actually weak.

CTR gaps are relative to this file, not to a universal benchmark. The engine pools clicks and impressions into position bands, calculates the site's observed CTR for each band, and flags a top-10 row when its CTR is below 70 percent of that local baseline and the row has at least 50 impressions. This makes the comparison more honest for the property, but SERP features and brand demand can still explain the gap. Inspect the actual snippet before testing metadata.

Rising and decay labels require the optional prior-period file. Rising means impressions increased at least 30 percent and by at least 20 while the current position is 40 or better. Decay means clicks fell at least 30 percent with five or more clicks lost, or impressions fell at least 40 percent with 50 or more impressions lost. These thresholds suppress tiny movements, but they do not remove seasonality or reporting noise, so the output recommends investigation rather than a predetermined rewrite.

Read priority and confidence separately

Priority is a triage score from zero to 100. It rises logarithmically with impressions and receives a fixed bonus for the rule type, so a large striking-distance row appears above a tiny one without letting one very large query dominate every result. The score is deterministic and is included in the CSV and JSON exports. It is not a forecast of traffic, revenue, or probability of reaching page one.

Confidence describes sample strength, not correctness. A high-confidence row has at least 100 impressions and an available comparison period; medium generally has at least 50 impressions; lower-volume evidence stays low. A high-confidence decay can still be seasonal, and a low-confidence opportunity can still be commercially important. Use confidence to decide how much verification to do before editing, then use business value and page fit to set the real implementation order.

Turn the queue into a monthly SEO action plan

Filter the result by type and review only the first few rows in each group. For a striking-distance query, identify the exact ranking URL and check whether the page fully answers the query. For a CTR gap, compare the live title and description with the result page and note any ads, video, local, shopping, or answer features that change click behavior. For a rising row, protect the section already matching the intent. For decay, inspect demand, competitors, indexing, and the page's edit history before planning a refresh.

Export the evidence ledger as CSV when another analyst will sort or annotate it, Markdown when it belongs in a client update or issue, and JSON when it will feed another local workflow. Add the chosen owner, due date, implementation note, and expected evidence in the keyword ranking report workbook. The engine narrows the candidates; the workbook records the accountable decision that should be checked in the next reporting cycle.

A disciplined monthly run should end with only a handful of owned actions. Keeping every generated row in the backlog turns the tool back into the data dump it is meant to replace. Archive the export with its source files, ship the selected work, and compare the same dimensions after a complete period. Do not repeatedly edit a URL because preliminary daily movement changed direction.

Important limits of this analysis

Search Console position is an average of the topmost result under its aggregation rules, not a fixed daily rank. Query and page tables can use different aggregation, rare values may be hidden, and exported rows do not necessarily sum to the chart total. The engine therefore analyzes the rows it receives and never claims complete query coverage. Large properties that need exhaustive analysis should use Search Console bulk export or the API and preserve their aggregation settings.

The tool also avoids automatic cannibalization claims. A standalone Queries CSV and Pages CSV cannot prove that two pages ranked for one query. Verify that relationship by filtering a query in Search Console and opening the Pages tab, or by exporting a query-plus-page dataset through the API. Two pages receiving broad impressions are not evidence of cannibalization by themselves.