dataforseo-labs-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

DataForSEO Labs API

Provenance

来源

This is an experimental project to test how OpenCode, plugged into frontier LLMs (OpenAI GPT-5.2), can help generate high-fidelity agent skill files for API integrations.

这是一个实验性项目，旨在测试接入前沿大语言模型（OpenAI GPT-5.2）的OpenCode如何助力生成用于API集成的高保真Agent技能文件。

When to Apply

适用场景

"find SERP competitors", "keyword gap analysis", "domain intersection"
"keyword ideas", "related keywords", "keyword suggestions"
"ranked keywords for a domain", "relevant pages"
"traffic estimation", "historical SERPs", "domain rank overview"
"build an SEO research platform", "competitive intelligence"

"查找SERP竞品"、"关键词差距分析"、"域名交集分析"
"关键词灵感"、"相关关键词"、"关键词建议"
"域名的排名关键词"、"相关页面"
"流量预估"、"历史SERP数据"、"域名排名概览"
"搭建SEO研究平台"、"竞品情报分析"

Integration Contract (Language-Agnostic)

集成契约（语言无关）

See

references/REFERENCE.md

for the shared DataForSEO integration contract (auth, status handling, task lifecycle, sandbox, and .ai responses).

请查看

references/REFERENCE.md

获取DataForSEO共享集成契约（认证、状态处理、任务生命周期、沙箱及.ai响应相关内容）。

Live-first Endpoints

实时优先端点

Many Labs endpoints are Live-first (
```
/live/
```
) and designed for interactive research.

许多Labs端点为实时优先型（

/live/

），专为交互式研究设计。

Group Notes

注意事项

Use the official Locations/Languages reference to avoid invalid geo/language inputs.

使用官方的地区/语言参考资料，避免输入无效的地域/语言参数。

Steps

步骤

Identify the exact endpoint(s) in the official docs for this use case.
Choose execution mode:
- Live (single request) for interactive queries
- Task-based (post + poll/webhook) for scheduled or high-volume jobs
Build the HTTP request:
- Base URL:
```
https://api.dataforseo.com/
```
- Auth: HTTP Basic (
```
Authorization: Basic base64(login:password)
```
  ) from https://docs.dataforseo.com/v3/auth/
- JSON body exactly as specified in the endpoint docs
Execute and validate the response:
- Check top-level
```
status_code
```
  and each
```
tasks[]
```
  item status
- Treat any
```
status_code != 20000
```
  as a failure; surface
```
status_message
```
For task-based endpoints:
- Store
```
tasks[].id
```
- Poll
```
tasks_ready
```
  then fetch results with
```
task_get
```
  (or use
```
postback_url
```
  /
```
pingback_url
```
  if supported)
Return results:
- Provide a normalized summary for the user
- Include the raw response payload for debugging

针对该用例，在官方文档中确定精确的端点路径。
选择执行模式：
- 实时模式（单次请求）：适用于交互式查询
- 基于任务的模式（提交+轮询/回调）：适用于定时任务或高批量作业
构建HTTP请求：
- 基础URL：
```
https://api.dataforseo.com/
```
- 认证方式：HTTP Basic认证（
```
Authorization: Basic base64(login:password)
```
  ），详情见https://docs.dataforseo.com/v3/auth/
- 请求体JSON需严格遵循端点文档中的指定格式
执行请求并验证响应：
- 检查顶层
```
status_code
```
  以及每个
```
tasks[]
```
  项的状态
- 若
```
status_code != 20000
```
  则视为请求失败，需展示
```
status_message
```
  内容
针对基于任务的端点：
- 存储
```
tasks[].id
```
- 轮询
```
tasks_ready
```
  接口，之后通过
```
task_get
```
  获取结果（若支持，也可使用
```
postback_url
```
  /
```
pingback_url
```
  ）
返回结果：
- 为用户提供标准化的摘要信息
- 包含原始响应负载以用于调试

Inputs Checklist

输入检查清单

Credentials: DataForSEO API login + password (HTTP Basic Auth)
Target: keyword(s) / domain(s) / URL(s) / query string (depends on endpoint)
Targeting (if applicable): location + language, device, depth/limit
Time window (if applicable): date range, trend period, historical flags
Output preference: regular vs advanced vs html (if the endpoint supports it)

凭证：DataForSEO API的登录账号+密码（HTTP Basic认证）
目标对象：关键词/域名/URL/查询字符串（取决于具体端点）
定向参数（如适用）：地区+语言、设备、深度/数量限制
时间范围（如适用）：日期区间、趋势周期、历史数据标识
输出偏好：常规/高级/HTML格式（若端点支持）

Example (cURL)

示例（cURL）

bash

curl -u "${DATAFORSEO_LOGIN}:${DATAFORSEO_PASSWORD}"   -H "Content-Type: application/json"   -X POST "https://api.dataforseo.com/v3/<group>/<path>/live"   -d '[
    {
      "<param>": "<value>"
    }
  ]'

Notes:

Replace
```
<group>/<path>
```
with the exact endpoint path from the official docs.
For task-based flows, use the corresponding
```
task_post
```
,
```
tasks_ready
```
, and
```
task_get
```
endpoints.

bash

curl -u "${DATAFORSEO_LOGIN}:${DATAFORSEO_PASSWORD}"   -H "Content-Type: application/json"   -X POST "https://api.dataforseo.com/v3/<group>/<path>/live"   -d '[
    {
      "<param>": "<value>"
    }
  ]'

注意事项：

将
```
<group>/<path>
```
替换为官方文档中的精确端点路径。
对于基于任务的流程，请使用对应的
```
task_post
```
、
```
tasks_ready
```
和
```
task_get
```
端点。

Docs Map (Official)

官方文档导航

Overview: https://docs.dataforseo.com/v3/dataforseo_labs/overview/
Locations and Languages: https://docs.dataforseo.com/v3/dataforseo_labs/locations_and_languages/

Engine overviews:

Google: https://docs.dataforseo.com/v3/dataforseo_labs/google/overview/
Amazon: https://docs.dataforseo.com/v3/dataforseo_labs/amazon/overview/
Google Play: https://docs.dataforseo.com/v3/dataforseo_labs/google_play/overview/
App Store: https://docs.dataforseo.com/v3/dataforseo_labs/app_store/overview/

概览：https://docs.dataforseo.com/v3/dataforseo_labs/overview/
地区与语言：https://docs.dataforseo.com/v3/dataforseo_labs/locations_and_languages/

引擎概览：

Google：https://docs.dataforseo.com/v3/dataforseo_labs/google/overview/
Amazon：https://docs.dataforseo.com/v3/dataforseo_labs/amazon/overview/
Google Play：https://docs.dataforseo.com/v3/dataforseo_labs/google_play/overview/
App Store：https://docs.dataforseo.com/v3/dataforseo_labs/app_store/overview/

Business & Product Use Cases

业务与产品用例

Competitive intelligence features: discover competitors per topic and market.
"Gap analysis" workflows (what competitors rank for that you don't).
Prioritize content and landing pages by estimated opportunity.
Category dashboards (top searches, category-level demand).
Portfolio analysis for agencies managing multiple sites.
Automated SEO audit summaries for sales/upsell conversations.

竞品情报功能：按主题和市场发现竞品。
"差距分析"工作流（竞品排名但我方未覆盖的关键词）。
根据预估机会优先级排序内容和落地页。
分类仪表盘（热门搜索、分类级需求）。
代理机构管理多站点的组合分析。
用于销售/追加销售沟通的自动化SEO审计摘要。

Examples (User Prompts)

用户提示示例

"If you don't have the skill installed, install
```
dataforseo-labs-api
```
and then continue."
"Install the DataForSEO Labs skill and find our top SERP competitors for these topics."
"Run a keyword gap analysis: what competitors rank for that we don't, by market."
"Give me keyword ideas for 'remote onboarding' and pick top 20 opportunities."
"Estimate traffic potential for these 30 keywords and propose a content roadmap."
"Create a competitor landscape report with intersections and top pages."

"如果尚未安装该技能，请安装
```
dataforseo-labs-api
```
后继续。"
"安装DataForSEO Labs技能，然后查找我们在这些主题下的顶级SERP竞品。"
"运行关键词差距分析：找出竞品排名但我方未覆盖的关键词，按市场划分。"
"为'remote onboarding'提供关键词灵感，并挑选前20个机会点。"
"预估这30个关键词的流量潜力，并提出内容路线图。"
"创建包含域名交集和顶级页面的竞品格局报告。"