dataforseo-merchant-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

DataForSEO Merchant 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

适用场景

"track product listings", "monitor prices", "product availability"
"analyze sellers", "seller competition", "seller counts"
"fetch product reviews", "review monitoring"
"Google Shopping products", "Amazon product research"

「追踪产品列表」「监控价格」「产品库存状态」
「分析卖家」「卖家竞争态势」「卖家数量统计」
「获取产品评论」「评论监控」
「Google Shopping产品分析」「Amazon产品调研」

Integration Contract (Language-Agnostic)

集成协议（语言无关）

See

references/REFERENCE.md

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

有关DataForSEO集成的通用协议（认证、状态处理、任务生命周期、沙箱环境及.ai响应），请查看

references/REFERENCE.md

。

Task-based Retrieval

基于任务的检索

Merchant is largely task-based:
```
task_post
```
->
```
tasks_ready
```
->
```
task_get
```
(Advanced/HTML where available).
Store
```
tasks[].id
```
so you can resume fetching results.
If the endpoint supports
```
postback_url
```
or
```
pingback_url
```
, prefer it over polling.

Merchant主要采用任务式流程：
```
task_post
```
->
```
tasks_ready
```
->
```
task_get
```
（支持Advanced/HTML格式的场景下）。
保存
```
tasks[].id
```
以便后续恢复结果获取操作。
如果端点支持
```
postback_url
```
或
```
pingback_url
```
，优先使用该方式而非轮询。

Group Notes

注意事项

Locations and languages are required for many sources; use the source-specific reference endpoints.

许多数据源需要指定地区和语言；请使用对应数据源的参考端点进行设置。

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
```
  ）
返回结果：
- 为用户提供标准化的结果摘要
- 附上原始响应 payload 用于调试

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/merchant/overview/

Google Shopping:

Overview: https://docs.dataforseo.com/v3/merchant/google/overview/
Products Task POST: https://docs.dataforseo.com/v3/merchant/google/products/task_post/
Sellers Task POST: https://docs.dataforseo.com/v3/merchant/google/sellers/task_post/
Reviews Task POST: https://docs.dataforseo.com/v3/merchant/google/reviews/task_post/

Amazon:

Overview: https://docs.dataforseo.com/v3/merchant/amazon/overview/
Products Task POST: https://docs.dataforseo.com/v3/merchant/amazon/products/task_post/
ASIN Task POST: https://docs.dataforseo.com/v3/merchant/amazon/asin/task_post/

总览：https://docs.dataforseo.com/v3/merchant/overview/

Google Shopping相关：

总览：https://docs.dataforseo.com/v3/merchant/google/overview/
产品任务提交：https://docs.dataforseo.com/v3/merchant/google/products/task_post/
卖家任务提交：https://docs.dataforseo.com/v3/merchant/google/sellers/task_post/
评论任务提交：https://docs.dataforseo.com/v3/merchant/google/reviews/task_post/

Amazon相关：

总览：https://docs.dataforseo.com/v3/merchant/amazon/overview/
产品任务提交：https://docs.dataforseo.com/v3/merchant/amazon/products/task_post/
ASIN任务提交：https://docs.dataforseo.com/v3/merchant/amazon/asin/task_post/

Business & Product Use Cases

业务与产品应用场景

Competitive price monitoring for ecommerce operators and brands.
Marketplace intelligence dashboards (assortment, seller dynamics, review signals).
Detect unauthorized reseller activity by tracking sellers over time.
Support category managers with product discovery and benchmarking.
Create sales enablement insights (who competes, where you appear, pricing gaps).
Track reputation at SKU level via review trends.

为电商运营方和品牌提供竞品价格监控。
搭建电商平台情报仪表盘（品类布局、卖家动态、评论信号）。
通过长期追踪卖家信息，检测未经授权的经销商活动。
为品类经理提供产品发现与基准对比支持。
生成销售赋能洞察（竞争对手是谁、自身曝光位置、价格差距）。
通过评论趋势追踪SKU级别的品牌声誉。

Examples (User Prompts)

用户指令示例

"If you don't have the skill installed, install
```
dataforseo-merchant-api
```
and then continue."
"Install the Merchant skill and monitor prices for these products weekly across top sellers."
"Pull Google Shopping results for this query and compare our visibility vs competitors."
"Fetch Amazon product info for these ASINs and extract key attributes into a table."
"Analyze seller competition for our category and list top sellers by presence."
"Track review trends for our SKU and summarize recurring complaints."

「如果尚未安装该技能，请安装
```
dataforseo-merchant-api
```
后继续。」
「安装Merchant技能，并每周监控这些产品在头部卖家的价格。」
「获取该查询的Google Shopping结果，对比我们与竞品的曝光情况。」
「获取这些ASIN对应的Amazon产品信息，并将关键属性提取为表格。」
「分析我们所在品类的卖家竞争态势，按出现频次列出头部卖家。」
「追踪我们SKU的评论趋势，总结常见投诉点。」