Competitor keyword gap report
Start with a small set of relevant competitors, then test their keywords against what the site already covers. The report classifies possible gaps instead of pretending every competitor term deserves a page.
Install and run the report
Install the CLI once, then run seo start to connect your site and Google data. After setup you can run this report yourself or ask your agent to run it.
Runafter install
Install the SEO CLI globally.
npm i -g seoRun setup after installation.
seo startRun competitor keyword gaps through the report catalog.
seo reports run competitor-keyword-gap --params '{"site":"sc-domain:example.com","competitors":[{"domain":"competitor-one.example","siteType":"business"},{"domain":"competitor-two.example","siteType":"business"}],"countryCode":"GB","languageCode":"en","maxRank":20,"limitPerDomain":100,"candidateLimit":50}' --jsonWhat you get from this report
Compare up to three explicit competitors with retained Search Console themes, the site's provider footprint, and repeated ranking-page patterns.
- Best for
- You have classified a small set of relevant competitors.
- Needs
- Connected Search Console property
- You get
- A bounded candidate list with competitor evidence, own-site coverage state, provider metrics, theme matches, classifications, and verification prompts.
- Use next
- Search competitors
What you need before you run it
This report uses bounded ranked-keyword rows for the site and up to three explicit competitor domains. up to 100,000 Search Console query and page rows, aggregated and indexed for bounded lexical theme matching. exact first-party coverage, own provider ranks, repeated competitor page patterns, provider costs, source failures, and row caps.
Connected Search Console property
Provides retained owner-verified query and page evidence used to find existing topic coverage.
Site and classified competitor domains
Provide bounded estimated keyword footprints for the site and up to three explicitly relevant competitors.
Competitor ranking pages
Add repeated path-pattern evidence and representative pages for programmatic SEO research.
How the report finds the opportunity
The report uses existing search and page evidence to build a limited review list. An opportunity is a reason to inspect a page, not a promise of more traffic.
01
Separates terms already observed in retained first-party rows, terms where the site already has a provider-observed rank, plausible gap candidates, and unverified competitor terms.
02
Requires retained first-party theme overlap plus either several compared domains or a top-10 competitor rank before promoting a term to a relevant candidate.
03
Builds bounded token indexes for large Search Console datasets and applies deterministic limits, ordering, and one structured-output budget.
04
Creates a data-source research brief only when repeated page patterns support a possible new template family.
Check the evidence behind each opportunity
Start with the query, page and date range behind each suggestion. Thin or partial evidence belongs in the review pile, not the implementation queue.
| Read first | Why it matters |
|---|---|
| Result | A bounded candidate list with competitor evidence, own-site coverage state, provider metrics, theme matches, classifications, and verification prompts. |
| More detail | Repeated competitor page patterns and programmatic SEO briefs covering source rights, identifiers, fields, coverage, freshness, missing values, and distinct page value. |
| Read it with | Review relevant candidates first, then reject terms whose intent, current results, or audience do not fit the site. |
What the result cannot prove
Search Console absence means not found in retained rows. It does not prove zero impressions, no ranking, or no page coverage. Lexical overlap and URL patterns do not prove demand, intent, page quality, or that a scalable template should exist. Provider ranks, volume, difficulty, intent, and traffic are country-level estimates that need a current result check.
Review relevant candidates first, then reject terms whose intent, current results, or audience do not fit the site. Treat pSEO suggestions as research prompts. Confirm source rights, stable identifiers, fields, coverage, freshness, missing-value behavior, and distinct page value before building anything. Complete the returned data-source brief before approving a new programmatic template family.
Use a different report for these jobs
You want every competitor keyword presented as relevant or missing from the site. You have not checked whether the competitors and keyword market match the site purpose.
You have not identified and classified relevant competitors yet.
Run search competitors on a representative keyword set, inspect the returned domains, and classify only the sites that compete for the same audience or outcome.
You want to expand an existing first-party page family rather than research competitor terms.
Run pSEO opportunities to find expansion evidence in owner-verified performance and working templates before introducing an independent competitor dataset.
Use the report with an agent or in code
The command above is enough for most work. These options let an agent, script or application run the same report with explicit input and structured output.
CLI
Use the report catalog when an agent, script or CI job needs predictable JSON instead of the normal terminal output. Check the current input first, then run the report with the validated parameters.
Check the current input before the agent or script runs the report.
seo reports describe competitor-keyword-gap --jsonOnce the input is valid, run the report through the report catalog.
seo reports run competitor-keyword-gap --params '{"site":"sc-domain:example.com","competitors":[{"domain":"competitor-one.example","siteType":"business"},{"domain":"competitor-two.example","siteType":"business"}],"countryCode":"GB","languageCode":"en","maxRank":20,"limitPerDomain":100,"candidateLimit":50}' --jsonMCP
An MCP agent follows the same two-step flow. It inspects the current schema, fills the required fields and only then runs the report.
Ask the MCP server for the current report input.
{
"id": "competitor-keyword-gap"
}Run the report after the agent has checked and filled the input.
{
"id": "competitor-keyword-gap",
"params": {
"site": "sc-domain:example.com",
"competitors": [
{
"domain": "competitor-one.example",
"siteType": "business"
},
{
"domain": "competitor-two.example",
"siteType": "business"
}
],
"countryCode": "GB",
"languageCode": "en",
"maxRank": 20,
"limitPerDomain": 100,
"candidateLimit": 50
}
}TypeScript
Install the package in a Node 22 project when your application needs to run the report directly. The result includes the same evidence, warnings and limits returned through the CLI and MCP server.
Add the SEO package to your project.
npm install seoRun the report from your TypeScript application.
import { executeReport } from 'seo/mcp'
const result = await executeReport(
'competitor-keyword-gap',
{
"site": "sc-domain:example.com",
"competitors": [
{
"domain": "competitor-one.example",
"siteType": "business"
},
{
"domain": "competitor-two.example",
"siteType": "business"
}
],
"countryCode": "GB",
"languageCode": "en",
"maxRank": 20,
"limitPerDomain": 100,
"candidateLimit": 50
},
)
console.log(result)What to do next
Start with relevant candidates whose source coverage is usable, then inspect the current results and representative pages. Complete the data-source checks before approving a programmatic template, and keep no new page as a valid outcome.
- 01Inspect current results for shortlisted terms.
- 02Compare representative competitor and first-party pages.
- 03Complete the returned data-source brief before approving a new programmatic template family.
Related reports
Identify domains that repeatedly appear across an explicit keyword set while keeping unknown site types unclassified.
Find a domain's bounded ranking-page footprint and repeated URL patterns, with optional matching Search Console page evidence.
Build one bounded queue from existing Search Console opportunities, then optionally add market estimates without changing the first-party priority scores.
Sources used by this report
These primary sources define the provider data or search controls used by the result.