> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appeeky.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Keywords and Competitors

> Track Google positions for your site and store listing, research new keywords, and find the searches competitors win and you don't.

This page covers the keyword side of [SEO for Apps](https://docs.appeeky.com/docs/seo-overview.md): the **Rank tracker**, **Research**, **Competitors** and **Domain** tabs. Every call needs an SEO project id.

> [!NOTE]
>
> Requires a **Startup** or **Agentic Scale** plan and an SEO project. Routes that fetch new search data cost 2 API credits with an API key or MCP; see [Credits](https://docs.appeeky.com/docs/seo-overview.md#credits).

***

## How it works

```
Research ideas  ─┐
Competitor gaps ─┼─→  Rank tracker  →  scans every 3 days  →  positions, movers, history
Playbook seeds  ─┘
```

1. **Find keywords.** Expand a seed phrase into related searches, check volume and difficulty for a list, or pull the keywords a competitor ranks for.
2. **Track them.** Tracked keywords are checked on every rank scan. Each check records your website's position, your store listing's position, and whether an AI Overview showed and who it cited.
3. **Watch movement.** The rank tracker shows the latest and previous position, best-ever position and search metrics. History explains why a keyword moved.

***

## Rank tracker

| Method | Endpoint | Description |
| - | - | - |
| GET | `/v1/seo/keywords` | List tracked keywords with positions and metrics |
| POST | `/v1/seo/keywords` | Track keywords |
| GET | `/v1/seo/keywords/:id` | One keyword with its metrics |
| PATCH | `/v1/seo/keywords/:id` | Pause or resume a keyword (`isActive`), or replace its `tags` |
| DELETE | `/v1/seo/keywords` | Stop tracking keywords: `{ "ids": [...] }`. Their rank history is removed |
| GET | `/v1/seo/keywords/:id/history` | Every rank check with the ranking URL and top results (`?days=`, 1–365, default `90`) |
| POST | `/v1/seo/keywords/:id/live-check` | Check one keyword right now |

### Track keywords

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.appeeky.com/v1/seo/keywords \
  -H "X-API-Key: $APPEEKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "PROJECT_ID",
    "keywords": ["pomodoro timer app", "focus app for studying"],
    "tags": ["core"]
  }'
```

| Field | Type | Description |
| - | - | - |
| `projectId` | string | Required |
| `keywords` | string\[] or string | Required. Up to 500 per request. A string is split on commas and new lines |
| `tags` | string\[] | Optional labels for grouping, up to 20 |
| `country`, `languageCode`, `device` | string | Default to the project's market |

Keywords you already track aren't duplicated, so sending the same list twice is safe. Positions appear after the next scan.

### List keywords

`GET /v1/seo/keywords?project=PROJECT_ID` takes these filters:

| Param | Description |
| - | - |
| `band` | `top3`, `top10`, `top100` or `not_ranking` |
| `sort` | `position`, `delta`, `volume`, `keyword` or `updated` |
| `direction` | `asc` (default) or `desc` |
| `search` | Text the keyword contains |
| `tag` | Only keywords with this tag |
| `active` | `true` or `false` |
| `limit`, `offset` | Paging. `limit` is 1–500 |

### Live check

`POST /v1/seo/keywords/:id/live-check` fetches fresh results for one keyword and returns the new rank check plus the top 20 results and any AI Overview. It counts toward the project's daily data budget and returns `402 budget_exhausted` once that is spent. To refresh a whole project, run a [rank scan](https://docs.appeeky.com/docs/seo-overview.md#rank-scans) instead.

***

## Keyword research

| Method | Endpoint | Description |
| - | - | - |
| POST | `/v1/seo/research/ideas` | Related keywords for seed phrases, with volume, difficulty, CPC and intent |
| POST | `/v1/seo/research/metrics` | Volume, difficulty, CPC, intent and 12-month seasonality for an exact list |

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.appeeky.com/v1/seo/research/ideas \
  -H "X-API-Key: $APPEEKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "projectId": "PROJECT_ID", "seeds": ["pomodoro timer"] }'
```

| Field | Description |
| - | - |
| `seeds` | Ideas only. Required, up to 20. One or two seeds work best |
| `keywords` | Metrics only. Required, up to 700 per request |
| `projectId` | Optional. Uses the project's country and language |
| `country`, `languageCode` | Optional. Default `us` and `en` when no project is given |
| `force` | Metrics only. Fetch again even when stored metrics exist |

Metrics responses include `fetchedCount` and `cachedCount` so you can see how many came from stored data. Track the keywords worth keeping with `POST /v1/seo/keywords`.

***

## Competitors and keyword gaps

Add a competitor's domain, analyze it, then review the gaps: searches where the competitor ranks and you don't.

| Method | Endpoint | Description |
| - | - | - |
| GET | `/v1/seo/competitors?project=` | List competitors with shared keywords and average position |
| POST | `/v1/seo/competitors` | Add a competitor: `projectId`, `domain`, optional `label`, `kind` (`website`, `app_store` or `play_store`; default `website`) |
| DELETE | `/v1/seo/competitors/:id` | Remove a competitor |
| POST | `/v1/seo/competitors/:id/analyze` | Pull the keywords the competitor ranks for and compare them with yours |
| GET | `/v1/seo/gaps?project=` | Review the gaps |
| POST | `/v1/seo/gaps/track` | Track gap keywords: `projectId`, `keywords` (up to 500) |

Adding a competitor does nothing on its own. Run **analyze** to fetch its keywords. `limit` in the analyze body sets how many keywords to pull, 50–1,000 (default `500`).

`GET /v1/seo/gaps` filters:

| Param | Description |
| - | - |
| `mode` | `gaps` (default): they rank, you don't. `weak`: they outrank you. `all`: everything found |
| `competitor` | Only one competitor's keywords |
| `minVolume`, `maxDifficulty` | Drop low-volume or hard keywords. Difficulty is 0–100 |
| `limit`, `offset` | Paging. `limit` is 1–500 |

Gaps with the most search volume come first.

***

## Domain overview

The **Domain** tab shows the organic footprint of your site or any other domain in the project's market: ranking keywords, estimated monthly traffic and its ad value, position distribution, keyword movement, top keywords, top pages and closest organic competitors.

| Method | Endpoint | Description |
| - | - | - |
| GET | `/v1/seo/domain/overview?project=&domain=` | The latest stored report and recently checked domains. Free |
| POST | `/v1/seo/domain/overview` | Fetch a report: `projectId`, optional `domain`, optional `refresh` |

Leave out `domain` to report on the project's own website. Reports are stored for 24 hours per project, so opening one again in that window is free and returns `cached: true`. Send `refresh: true` to fetch a new one.

***

## Page ideas from the playbook

The [SEO playbook](https://docs.appeeky.com/docs/seo-playbook.md) builds keyword lists from your app's context: `{competitor} alternative` and `vs` seeds, complaint-driven queries and programmatic templates. Its track routes add those keywords to the same rank tracker.

| Method | Endpoint | Description |
| - | - | - |
| POST | `/v1/seo/keywords/seed/preview` | Alternative and vs candidates, priced with search volume |
| POST | `/v1/seo/keywords/seed/track` | Track selected candidates |

***

## MCP

| Tool | Description |
| - | - |
| `seo_keywords_list` | Tracked keywords with positions and metrics |
| `seo_keywords_add` | Track keywords |
| `seo_keywords_remove` | Stop tracking keywords |
| `seo_keyword_history` | Rank history for one keyword |
| `seo_keyword_live_check` | Check one keyword now |
| `seo_keyword_ideas` | Keyword ideas from seed phrases |
| `seo_keyword_metrics` | Metrics for an exact keyword list |
| `seo_competitors_list` | List competitors |
| `seo_competitors_add` | Add a competitor domain |
| `seo_competitors_remove` | Remove a competitor |
| `seo_competitors_analyze` | Analyze a competitor's keywords |
| `seo_gaps_list` | Keyword gaps |
| `seo_gaps_track` | Track gap keywords |
| `seo_domain_overview` | Domain overview for your site or a competitor's |
| `seo_keywords_seed_preview`, `seo_keywords_seed_track` | Playbook seeds |

Example prompt: *"Analyze calm.com for my project, then track the 20 gap keywords with the most volume and difficulty under 40."*

***

## Tips

* Tag keywords by theme or page so you can filter the rank tracker later.
* Analyze two or three close competitors rather than the biggest name in your category. Their gaps are easier to win.
* Use `mode=weak` to find keywords where a small improvement moves you past a competitor.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.