dataforseo-api

# DataForSEO API Use the `dfs` command to access DataForSEO directly. It accepts any relative v3 API path and refuses potentially paid requests unless `--execute` is supplied. ## Spending rule Assume DataForSEO data endpoints are paid unless current official documentation explicitly says otherwise. 1. Prefer supplied data or free first-party sources when they can answer the question reliably. 2. Before a paid call, state the endpoint, purpose, scope, and expected cost or documented cost basis. 3. Get explicit approval from the user or operator before adding `--execute`. 4. Treat approval as limited to the described call or bounded batch, not as standing authorization. 5. For unattended automation, require an explicit per-run budget and permitted scope. 6. `dfs account` uses the known free account endpoint and may be used to check authentication, balance, and limits. The CLI gate prevents accidental execution. It does not enforce a monetary limit. ## Workflow ### 1. Confirm paid SEO data is necessary Use DataForSEO when the task needs evidence such as: - search volume, difficulty, CPC, intent, or keyword trends; - live or location-specific SERPs; - ranked keywords, domain intersections, or competitor visibility; - backlinks and referring domains; - on-page crawl data; - local business, merchant, app, content-analysis, or AI-visibility data. Do not use a paid endpoint for ordinary web facts or when a free authoritative source is sufficient. ### 2. Select the endpoint from current official documentation DataForSEO changes over time. Inspect the official v3 documentation before constructing an unfamiliar request: - API index: https://docs.dataforseo.com/v3/ - Authentication: https://docs.dataforseo.com/v3/auth/ - Account data: https://docs.dataforseo.com/v3/appendix/user_data/ Do not guess endpoint paths, payload fields, pricing, location codes, or task semantics from memory. Prefer the smallest sufficient request: - narrow the location and language; - use the minimum useful result limit or depth; - avoid overlapping endpoints; - batch only when the user approved the whole batch and documentation shows it is appropriate; - prefer task or standard endpoints over live endpoints when latency is unimportant and current pricing makes them cheaper. ### 3. Check account state Run the sanitized account check when authentication, balance, limits, or recent spend matters: ```bash dfs account ``` It excludes the account login and reports compact balance, request-limit, spending-limit, and recent-spend fields. ### 4. Preflight without spending Store non-secret payloads in a temporary file or the current project's ignored artifact directory: ```bash dfs request POST /v3/<official-endpoint> --data-file /tmp/dataforseo-request.json ``` Without `--execute`, the command must fail closed with exit code `2`. This refusal occurs before credentials are loaded and before any network request. Before seeking approval, show: - request method and endpoint; - targets or queries, market, language, depth or limit, and item count; - live versus task or standard method; - expected price, documented cost basis, or clearly labelled uncertainty; - maximum bounded calls and spend where possible. ### 5. Execute only after approval ```bash dfs request POST /v3/<official-endpoint> \ --data-file /tmp/dataforseo-request.json \ --execute ``` The response JSON is written to standard output. Provider-reported actual cost is written to standard error. After execution: 1. Verify a successful exit status. 2. Check the expected result collection; do not treat an unexpected empty result as success. 3. Preserve raw JSON when auditability or reuse matters. 4. Separate provider data from interpretation. 5. Report actual DataForSEO cost. 6. Remove temporary payloads and results when they contain sensitive query context and are no longer needed. ## Task-based endpoints Some products use `task_post`, `tasks_ready`, and `task_get` instead of one live call. - Treat `task_post` as potentially billable and require approval. - Persist every returned task ID before polling. - Poll only the documented readiness or result endpoint. - Bound polling attempts and timeout visibly. - Never blindly retry a paid `task_post` after a timeout or ambiguous network failure. First inspect ready or task lists or retrieve the retained task ID to avoid duplicate spend. - Report partial, failed, and billed-but-failed tasks explicitly. ## Command reference ```text dfs account dfs request GET /v3/... [--execute] dfs request POST /v3/... --data '<json>' --execute dfs request POST /v3/... --data-file payload.json --execute dfs request POST /v3/... --data-file - --execute ``` Only relative `/v3/...` paths are accepted, and HTTP redirects are refused, so API credentials cannot leave the DataForSEO API origin. Except for the account endpoint, `GET` requests also require `--execute` because some DataForSEO GET endpoints may be billable. ## Failure handling - Exit code `2` indicates local safety refusal, invalid input, credential failure, HTTP failure, or a DataForSEO API or task error. - Do not hide empty responses, task failures, rate limits, insufficient balance, or schema failures. - Do not fabricate SEO metrics when a call fails. - Do not retry paid POST requests automatically. - If current pricing cannot be determined, state the uncertainty and ask whether to proceed. ## Verification ```bash command -v dfs dfs --help dfs account ``` When working from a source checkout, also run: ```bash python3 -m unittest discover -s tests -v ``` Do not claim the client is healthy without passing tests and a successful account check. The account check uses the documented free endpoint and makes a real authenticated network request.