dataforseo · git:20260719.1748a98 · 2026-07-19 · sha256 c8ee85ed963948f1
dataforseo git:20260719.1748a98A
Immutable. This exact content never changes and is served at /api/v1/blob/c8ee85ed963948f1.
--- 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.