dataforseo

Files (7)

• SKILL.md
• endpoints.md · references/
• source-notes.md · references/
• cli.py · scripts/
• smoke_test.py · scripts/
• test_contract.py · scripts/
• contract.json · tests/fixtures/

SKILL.md (first lines)

# DataForSEO

## Goal

Query DataForSEO's v3 endpoints through a CLI that is easy for agents to script
and humans to scan — SERP, keyword research + discovery, domain/competitor
analytics, backlinks, App Store / Play data, and one-shot idea validation.

## Use this when

- Validating an app/business idea in one scored pass (`validate <idea>`)
- Checking where a site ranks, or listing the top organic results (`serp`)
- Finding search volume, CPC, and competition for keywords (`volume`)
- Discovering keywords — long-tail (`suggestions`), semantic (`ideas`), related-search (`related`), intent (`intent`)
- Seeing what keywords a domain already ranks for (`ranked`)
- Finding a domain's organic competitors (`competitors`)
- Getting a domain's organic/paid rank overview (`domain`)
- Auditing a domain's backlinks and referring domains (`backlinks`, `refdomains`)
- Which apps rank in a store (`appsearch`); mining app reviews (`appreviews`)

## Do not use this for

- Idle exploration — **every command spends DataForSEO credits.** Run the
  narrowest command that answers the question, and use `--limit` to cap rows.
- Site audits / on-page crawling — not wrapped in v1 (uses async task endpoints).
- Bulk async jobs — this skill only calls synchronous `live` endpoints.
- Anything outside SEO data (no writes, no account/billing management).

## Setup

Requires DataForSEO **API credentials** (your API login + password from the
dashboard — these are *not* your website login/password).

1. Get them at https://app.dataforseo.com/api-access
2. Export them in `~/.zshenv` (not `.zshrc`, not a repo `.env`): `.zshenv` is
   read by every zsh — interactive and not — so the skill and the DataForSEO
   MCP subprocess both inherit them, and the secret never lands in a git repo.
   ```bash
   export DATAFORSEO_USERNAME="your_api_login"   # the email login
   export DATAFORSEO_PASSWORD="your_api_password" # plaintext — NOT the base64 token
   ```
   Then `chmod 600 ~/.zshenv` and open a fresh shell (or `source ~/.zshenv`).
3. **Use the plaintext password**, not the pre-encoded "token" the dashboard
   shows — the CLI does its own base64 encoding, so a token gives auth failures.

The CLI accepts `DATAFORSEO_USERNAME` (the DataForSEO MCP's variable name) or
`DATAFORSEO_LOGIN` for the login, so one pair of env vars powers both. It does
not read the credentials until a command actually calls the API, so `--help`
works without them.

## Preferred workflow

1. Run `scripts/cli.py` with the narrowest subcommand that answers the task.
2. Default location is New Zealand (`nz`). For keyword *volume*, a larger market
   (`--location us`) is usually more meaningful than tiny NZ numbers.
3. Use default human output for direct answers; `--json` when piping to another
   tool or agent.
4. Keep `--limit` low to control cost, especially on `ranked` and `refdomains`.

## CLI

Run with:

```bash
python3 skills/dataforseo/scripts/cli.py <command> [flags]
```

Common flags: `--location` (alias like `nz`/`us`/`uk`/`au` or a numeric
`location_code`), `--language` (default `en`), `--limit`, `--json`.

### `validate <idea>` — one-shot idea scorecard

The flagship for marketing-first validation. Runs discovery + demand + intent +
SERP + app-store competition in one pass (~6 API calls, one async) and prints a
scored scorecard: **seed demand** (anchored on the idea's own search volume, not
the noisiest discovered term), commercial intent, dominant search intent, whether
the SERP is content- or app-dominated, and app-incumbent strength — plus a
ready-to-run `appreviews` command to mine the top incumbent's pain points next.

```bash
python3 skills/dataforseo/scripts/cli.py validate "fruit tree care app" --location us --store apple
```

Use a **specific** seed that names the actual job (e.g. `"fruit tree care app"`,
`"garden planner app"`). Broad/ambiguous seeds pollute the discovery table with
off-target semantic matches — the scorecard flags this, and the seed-anchored
demand line stays honest regardless, but the discovered-terms table is noisier.
It deliberately does **not** auto-mine reviews (slow + pricey); it hands you the
command to do that as the follow-up.

### `serp <keyword> [--domain <site>]`

Top Google organic results for a keyword. With `--domain`, reports that site's
rank position instead of listing results.

```bash
python3 skills/dataforseo/scripts/cli.py serp "vegetable garden planner"
python3 skills/dataforseo/scripts/cli.py serp "garden planner app" --domain grovekeeper.app
python3 skills/dataforseo/scripts/cli.py serp "garden planner" --location us --limit 20
```

### `volume <keyword...>`

Search volume, CPC, and competition for one or more keywords (Google Ads data).

```bash
python3 skills/dataforseo/scripts/cli.py volume "garden planner" "vegetable planner" --location us
```

### `suggestions <seed>`

Long-tail keyword ideas containing the seed term, with volumes.

```bash
python3 skills/dataforseo/scripts/cli.py suggestions "companion planting" --location us --limit 25
```

### `ranked <domain>`

From thecolab-ai/.skills, MIT.

More from thecolab-ai/.skills