Dataforseo

---
name: dataforseo
description: "Query DataForSEO for SEO + market-validation data — Google SERP rank checks, keyword search volume, keyword discovery (semantic ideas, related-search expansion, search-intent classification), domain/competitor analytics, backlinks, and App Store / Play data (which apps rank + review mining). Use when checking where a site ranks, finding or discovering what people search for, validating demand and competition for an app/business idea, analysing a domain or its competitors, auditing backlinks, or mining competitor app reviews for pain points. Requires DATAFORSEO_USERNAME (or DATAFORSEO_LOGIN) and DATAFORSEO_PASSWORD. Every call spends DataForSEO credits."
license: MIT
compatibility: "Requires Python 3.10+ and network access for live data"
metadata:
  thecolab.category: "finance"
  thecolab.source_owner: "DataForSEO"
  thecolab.source_type: "commercial"
  thecolab.auth: "paid-credential"
  thecolab.access_mode: "public-api"
  thecolab.data_class: "public"
  thecolab.writes: "false"
  thecolab.browser: "false"
  thecolab.risk: "medium"
  thecolab.cache_ttl: "24h"
  thecolab.schema_version: "1"
  thecolab.skill_type: "public-api"
  thecolab.pack: "paid-data-connectors"
  thecolab.source_url: "https://api.dataforseo.com"
  thecolab.allowed_domains: "api.dataforseo.com,app.dataforseo.com"
  thecolab.last_verified: "2026-07-19"
  thecolab.health: "gated"
  thecolab.maintainer: "@adam91holt"
---

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

Keywords a domain already ranks for.

```bash
python3 skills/dataforseo/scripts/cli.py ranked grovekeeper.app --location us --limit 25
```

### `competitors <domain>`

Domains competing for the same keywords.

```bash
python3 skills/dataforseo/scripts/cli.py competitors grovekeeper.app --location us
```

### `domain <domain>`

Organic/paid rank overview: keyword count, estimated traffic, position buckets.

```bash
python3 skills/dataforseo/scripts/cli.py domain grovekeeper.app --location us
```

### `backlinks <domain>`

Backlink summary: total backlinks, referring domains, domain rank. (No location.)

```bash
python3 skills/dataforseo/scripts/cli.py backlinks grovekeeper.app
```

### `refdomains <domain>`

Referring domains, ranked by domain rank. (No location.)

```bash
python3 skills/dataforseo/scripts/cli.py refdomains grovekeeper.app --limit 25
```

## Discovery commands (counter confirmation bias)

These surface demand you did **not** seed — the antidote to "I searched my own
idea and found some volume, so it's validated." Run these before deciding what a
market wants.

### `ideas <seed...>`

Semantically *related* keywords that need not contain the seed (category match,
not text match). The workhorse for finding demand you'd never have typed. Review
the output — semantic matching also surfaces adjacent meanings (a "grow a garden"
seed can pull in a Roblox game).

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

### `related <seed>`

Google's "searches related to" expansion, walked to `--depth` (0-4; default 2 —
higher is wider and pricier). Lateral exploration of a topic.

```bash
python3 skills/dataforseo/scripts/cli.py related "raised garden bed" --location us --depth 2
```

### `intent <keyword...>`

Classifies each keyword as informational / navigational / commercial /
transactional (with confidence). Tells "wants a free answer" from "wants to buy"
— use it to separate real commercial demand from idle curiosity. (No location.)

```bash
python3 skills/dataforseo/scripts/cli.py intent "buy raised garden bed" "how to build raised bed" --language en
```

## App Store / Play commands (async)

⚠️ **DataForSEO does NOT provide in-store search volume** (App Store / Play ASO
keyword demand) — nobody does; Apple/Google don't publish it. For apps you get
**which apps rank, their ratings/review counts, and review text**, so you *infer*
demand and read competition + pain points directly. Web search `volume` stays
your quantified demand signal.

These are async (submit + poll), so they take a few seconds and print after
polling — unlike the instant `live` commands. Raise `--timeout` if one is slow.

### `appsearch <keyword> [--store apple|google]`

Which apps rank in the store for a query, with ratings and review counts (your
incumbent-strength read). Default store `apple`.

```bash
python3 skills/dataforseo/scripts/cli.py appsearch "plant identifier" --store apple --location us
```

### `appreviews <app_id> [--store apple|google] [--worst]`

Mine an app's reviews for pain points (`app_id` comes from `appsearch`). `--worst`
floats the lowest-rated reviews to the top — the store-agnostic way to find what
users hate about the incumbent, in their own words. This is the highest-signal,
lowest-bias input for spotting a gap. Pull a larger `--limit` to reach more
critical reviews (Apple has no "most critical" API sort).

```bash
python3 skills/dataforseo/scripts/cli.py appreviews 1252497129 --store apple --worst --limit 30
```

## Notes

- Location aliases: `nz us uk/gb au ca ie za in`. For anything else, pass a
  numeric `location_code` (see the DataForSEO locations endpoints).
- Errors surface DataForSEO's `status_message` and exit non-zero rather than
  dumping raw JSON. HTTP 401/403 means the credentials are wrong (or you used
  your website login instead of the API login).
- See `references/endpoints.md` for the endpoint each command hits and
  approximate per-call cost.

## Testing

```bash
python3 skills/dataforseo/scripts/smoke_test.py
```

Offline checks (`--help`, arg validation, missing-credential handling) always
run. Live API checks run only when `DATAFORSEO_LOGIN`/`DATAFORSEO_PASSWORD` are
set, and each one spends a small amount of credit.