# SEO Competitor Keyword Research — Any Domain Ranking Keywords (`amassuo/semrush-competitor-keywords`) Actor

Find every keyword your competitor ranks for: position, search volume, CPC, traffic share and the exact ranking URL. SEO competitor analysis and keyword research for any domain. Auto-discover rival domains. Excel export included.

- **URL**: https://apify.com/amassuo/semrush-competitor-keywords.md
- **Developed by:** [oussama dahbi](https://apify.com/amassuo) (community)
- **Categories:** SEO tools, Automation, Developer tools
- **Stats:** 4 total users, 3 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 ranking keywords

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Competitor Keyword Spy (Semrush)

Enter a domain → get **every keyword it ranks for**, with position, search volume, CPC,
traffic share and the exact **ranking URL**. Optionally discover its organic competitors
and analyse them too. Excel export included.

### Why this actor

The single most-requested SEO job is *"what does my competitor rank for?"*. This turns one
domain into thousands of billable rows — a much better revenue shape than tools where the
user supplies the keywords.

### How it works

```
domain(s) ─▶ (optional) domain_organic_organic → competitors
          └▶ domain_organic (sorted by traffic, server-side filtered)
                 └▶ dataset + Excel  ·  charge per delivered row
```

- **`domain_organic`** — ranking keywords. ~10 units/row.
- **`domain_organic_organic`** — organic competitors.
- **Server-side filters** (`minVolume` / `maxPosition`) are applied by Semrush *before*
  billing, so you don't pay units for rows the user would discard.

#### API facts verified against a live key

| Fact | Result |
|---|---|
| `display_limit` | works up to at least **2000 rows in one call** |
| `display_offset` | **not supported** on `domain_organic` (returns HTTP 400) — use a bigger `display_limit`, not paging |
| `display_filter` | works — `+\|Nq\|Gt\|999`, `+\|Po\|Lt\|11` verified to actually filter |
| `display_sort=tr_desc` | returns highest-traffic keywords first |
| Cost | **10 units per returned row** |

### Safety rails

- **Domain clean + dedup** — `https://www.ahrefs.com/`, `ahrefs.com` → one target.
- **`maxKeywordsPerDomain`** — hard per-domain cap.
- **Units pre-flight** — logs the estimate and your balance before spending.
- **Charge-limit guard** — respects the user's max-cost-per-run so you never spend
  Semrush units you can't bill.
- **Fatal-error stop** — bad key/quota halts the run; rows already delivered are kept.

### Setup

Set **`SEMRUSH_API_KEY`** as a secret environment variable on the actor (Apify Console →
Settings → Environment variables). Users can override with the `semrushApiKey` input if you
prefer bring-your-own-key.

### Run locally

```bash
cd semrush-competitor-keywords
npm install
## PowerShell:
$env:SEMRUSH_API_KEY = "your-semrush-api-key"
node src/main.js     # reads storage/key_value_stores/default/INPUT.json
```

Example input:

```json
{
  "domains": ["ahrefs.com", "moz.com"],
  "database": "us",
  "maxKeywordsPerDomain": 1000,
  "minVolume": 1000,
  "maxPosition": 10,
  "discoverCompetitors": true,
  "competitorsPerDomain": 5
}
```

### Input

| Field | Meaning |
|---|---|
| `domains` / `domainsText` | domains to analyse |
| `database` | country market (`us`, `uk`, `de`…) |
| `maxKeywordsPerDomain` | per-domain row cap |
| `minVolume` / `maxPosition` | server-side filters (also reduce cost) |
| `excludeKeywords` | drop keywords containing these terms (server-side → also cheaper) |
| `discoverCompetitors` | also return each domain's organic competitors |
| `competitorsPerDomain` | how many competitors per seed |
| `includeCompetitorKeywords` | also pull keywords for discovered competitors (multiplies cost) |
| `xlsxOutput` | save formatted Excel (default on) |
| `semrushApiKey` | optional key override |

### Output

Keyword row:

```json
{
  "domain": "ahrefs.com",
  "keyword": "search operators",
  "position": 1,
  "volume": 1220000,
  "cpc": 2.02,
  "url": "https://ahrefs.com/blog/google-advanced-search-operators/",
  "traffic_pct": 11.45,
  "database": "us"
}
```

Competitor row (when enabled) carries `type: "competitor"`, `seed_domain`,
`competitor_domain`, `relevance`, `organic_keywords`, `organic_traffic`.

The Excel file has two sheets: **Keywords** and **Competitors**.

### Publish + pay-per-event

```bash
apify login
apify push
```

Then **Publication ▸ Monetization ▸ Pay per event**. Delete the auto-added
`apify-default-dataset-item` "Result" event (the code charges explicitly — keeping both
double-charges), then add:

| Event name | Title | Suggested price |
|---|---|---|
| `keyword` | Ranking keyword | **$0.002** ($2 / 1,000) |
| `competitor` | Competitor found | **$0.002** |

Both cost ~10 Semrush units, so the same price applies to each.

### Revenue shape

One domain at `maxKeywordsPerDomain: 5000` = 5,000 rows ≈ **$10 per run** — versus a
user-supplied keyword list where they might paste 200. That's the reason to build this
one alongside the bulk-metrics actor: it cross-sells (find competitor keywords → enrich
them in bulk) and each run is worth far more.

### Roadmap

1. **Keyword gap** — keywords competitor A ranks for that you don't.
2. **Position tracking** — schedule weekly runs and diff positions over time.
3. **`phrase_related` expansion** — turn top competitor keywords into thousands more.
4. **URL-level analysis** — group by ranking URL to find their best-performing pages.

# Actor input Schema

## `domains` (type: `array`):

Domains to analyse, e.g. ahrefs.com. Paste with or without https:// and www.

## `domainsText` (type: `string`):

Alternative: paste domains separated by new lines or commas. Merged with the list above.

## `database` (type: `string`):

Semrush country database: us, uk, de, fr, es, it, ca, au, in…

## `maxKeywordsPerDomain` (type: `integer`):

How many ranking keywords to pull per domain (sorted by traffic, highest first). Caps cost.

## `minVolume` (type: `integer`):

Only return keywords above this monthly search volume. Filtered by Semrush before billing, so it also saves money.

## `maxPosition` (type: `integer`):

Only return keywords ranking at or above this position (e.g. 10 = first page only).

## `discoverCompetitors` (type: `boolean`):

Also find each domain's top organic competitors (who else ranks for the same keywords).

## `competitorsPerDomain` (type: `integer`):

How many competitors to return per seed domain.

## `includeCompetitorKeywords` (type: `boolean`):

Run the keyword report for each discovered competitor too. Multiplies cost — use with a keyword cap.

## `xlsxOutput` (type: `boolean`):

Also save a formatted Excel file (Keywords + Competitors sheets) to the run's key-value store.

## `semrushApiKey` (type: `string`):

Optional. Normally the operator sets SEMRUSH\_API\_KEY as an actor environment variable.

## `excludeKeywords` (type: `array`):

Drop keywords containing any of these terms (case-insensitive). Applied by Semrush before billing where possible, so it also reduces cost. Useful for stripping irrelevant/brand/adult terms big domains rank for.

## Actor input object example

```json
{
  "domains": [
    "ahrefs.com"
  ],
  "database": "us",
  "maxKeywordsPerDomain": 1000,
  "discoverCompetitors": false,
  "competitorsPerDomain": 5,
  "includeCompetitorKeywords": false,
  "xlsxOutput": true
}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "domains": [
        "ahrefs.com"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("amassuo/semrush-competitor-keywords").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "domains": ["ahrefs.com"] }

# Run the Actor and wait for it to finish
run = client.actor("amassuo/semrush-competitor-keywords").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "domains": [
    "ahrefs.com"
  ]
}' |
apify call amassuo/semrush-competitor-keywords --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,amassuo/semrush-competitor-keywords"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/EwTuhh36bS55ULaxh/builds/ovVpCGj5u3iFtQBEW/openapi.json