---
title: "Competitor keyword gap report | SEO Skill"
description: "Compare competitor keywords with Search Console themes, current rankings and repeated page patterns. Exclude irrelevant terms and evidence of existing coverage."
canonical: "https://seoskill.dev/docs/reports/competitor-keyword-gap"
language: "en"
---

# 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.

Install the SEO CLI globally.

```
npm i -g seo
```

Run setup after installation.

```
seo start
```

Run 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}' --json
```

## What 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.

Search competitor research report

](https://seoskill.dev/docs/reports/serp-competitors)[

### 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.

Programmatic SEO opportunities

](https://seoskill.dev/docs/reports/pseo-opportunities)

## 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 --json
```

Once 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}' --json
```

### MCP

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 seo
```

Run 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.

1.  01Inspect current results for shortlisted terms.
2.  02Compare representative competitor and first-party pages.
3.  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.

Search competitor research report

](https://seoskill.dev/docs/reports/serp-competitors)[

Find a domain's bounded ranking-page footprint and repeated URL patterns, with optional matching Search Console page evidence.

Organic ranking pages report

](https://seoskill.dev/docs/reports/ranking-pages)[

Build one bounded queue from existing Search Console opportunities, then optionally add market estimates without changing the first-party priority scores.

Keyword opportunity report

](https://seoskill.dev/docs/reports/keyword-opportunities)

## Sources used by this report

These primary sources define the provider data or search controls used by the result.

-   [DataForSEO ranked keywords API reference](https://docs.dataforseo.com/v3/dataforseo_labs-google-ranked_keywords-live/)
-   [DataForSEO relevant pages API reference](https://docs.dataforseo.com/v3/dataforseo_labs-google-relevant_pages-live/)
-   [Search Console Search Analytics API guidance](https://developers.google.com/webmaster-tools/v1/how-tos/search_analytics)