竞争域名分析（旧版）

GET /v3/dataforseo_labs/locations_and_languages

本接口使用 POST 方法，路径为：

/v3/dataforseo_labs/competitors_domain/live

> 容说明：本接口为旧版（Legacy）端点。平台 API 已于 2022-03-19 更新 Labs API 的请求和响应结构，但仍继续支持此旧版接口。新项目建议优使用新版竞争域名接口。

本接口用于分析指定域名的竞争域名，返回自然搜索和付费搜索中的排名、流量及交集指标。接口还会提供竞争域名与目标域名在相同搜索结果页中排名的指标。

请求信息

请求方法：POST
请求地址：https://api.seermartech.cn/v3/dataforseo_labs/competitors_domain/live
请求格式：JSON 数组，UTF-8 编码
认证方式：Bearer Token 平台限流以认证说明中的 30/60/120 次/分钟规则为准
批量请求：每个请求体可以多个任务对象

每次请求都会计费。参考价约 ¥0.0756 / 次，扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

认证

http

Authorization: Bearer smt_live_YOUR_KEY
Content-Type: application/json

请求参数

请求体是 JSON 数组，每个数组代表一个任务。

参数	类型	填	说明
`target`	string	是	目标域名。不 `https://` 和 `www.`，例如 `example.com`。
`location_name`	string	条件填	地区名。未指定 `location_code` 时填，例如 `United Kingdom`。
`location_code`	integer	条件填	地区代码。未指定 `location_name` 时填，例如 `2840`。
`language_name`	string	条件填	语言名。未指定 `language_code` 时填，例如 `English`。
`language_code`	string	条件填	语言代码。未指定 `language_name` 时填，例如 `en`。
`item_types`	array	否	指定返回的搜索结果类型。可使用 `organic`、`paid`、`local_pack`、`featured_snippet` 等值。若 `organic` 以外的类型，结果将按数组中的第一种类型排序。未在数组中的结果类型不能用于过滤或排序。
`filters`	array	否	结果过滤条件，最多 8 个过滤条件。多个条件之间使用 `and` 或 `or`。支持 `<`、`<=`、`>`、`>=`、`=`、`<>`、`in`、`not_in`。
`order_by`	array	否	结果排序规则。排序字段可使用与 `filters` 相同的字段，排序方向为 `asc` 或 `desc`。最多设置 3 条规则，格式为 `字段,方向`。
`limit`	integer	否	返回的最大域名数量。默认 `100`，最大 `1000`。
`offset`	integer	否	结果偏移量。默认 `0`。例如设置为 `10` 时，跳过前 10 条结果。
`max_rank_group`	integer	否	参与竞争域名识别的最高排名范围。默认 `100`。设置为 `10` 时从前 10 个 Google 搜索结果中提取竞争域名。
`exclude_top_domains`	boolean	否	是否排除大型通用网站。默认 `false`。设置为 `true` 后，将排除维基百科、亚马逊、谷歌、脸书、YouTube、领英、Instagram、Reddit 等大型网站。
`intersecting_domains`	array	否	用于提高结果准确性的域名列表。指标将基于目标域名与这些域名同时出现的搜索结果页计算。最多指定 20 个域名。
`tag`	string	否	自定义任务标识，最长 255 个字符。该值会原样返回在响应的 `data` 对象中。

地区与语言

可通过以下接口查询可用地区和语言：

GET /v3/dataforseo_labs/locations_and_languages

例如：

location_name：United Kingdom
location_code：2840
language_name：English
language_code：en

过滤器示例

以下过滤器表示：

自然搜索结果数量大于或等于 50，且自然搜索第一名数量属于 1、2、3；
或自然搜索预估流量不低于 100。

json

[
  [
    ["metrics.organic.count", ">=", 50],
    "and",
    ["metrics.organic.pos_1", "in", [1, 2, 3]]
  ],
  "or",
  ["metrics.organic.etv", ">=", 100]
]

请求示例

cURL

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/dataforseo_labs/competitors_domain/live" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "target": "example.com",
      "location_name": "United States",
      "language_name": "English",
      "filters": [
        [
          ["metrics.organic.count", ">=", 50],
          "and",
          ["metrics.organic.pos_1", "in", [1, 2, 3]]
        ],
        "or",
        ["metrics.organic.etv", ">=", 100]
      ],
      "limit": 5
    }
  ]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/dataforseo_labs/competitors_domain/live"

headers = {
    "Authorization": "Bearer smt_live_YOUR_KEY",
    "Content-Type": "application/json",
}

payload = [
    {
        "target": "example.com",
        "location_name": "United States",
        "language_name": "English",
        "filters": [
            [
                ["metrics.organic.count", ">=", 50],
                "and",
                ["metrics.organic.pos_1", "in", [1, 2, 3]],
            ],
            "or",
            ["metrics.organic.etv", ">=", 100],
        ],
        "limit": 5,
    }
]

response = requests.post(url, headers=headers, json=payload)
result = response.json()

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        f"请求失败，错误码：{result.get('status_code')}，"
        f"错误信息：{result.get('status_message')}"
    )

TypeScript

typescript

import axios from "axios";

const payload = [
  {
    target: "example.com",
    location_name: "United States",
    language_name: "English",
    filters: [
      [
        ["metrics.organic.count", ">=", 50],
        "and",
        ["metrics.organic.pos_1", "in", [1, 2, 3]],
      ],
      "or",
      ["metrics.organic.etv", ">=", 100],
    ],
    limit: 5,
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/dataforseo_labs/competitors_domain/live",
    payload,
    {
      headers: {
        Authorization: "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
      },
    }
  )
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.error(error.response?.data || error.message);
  });

响应结构

接口返回 JSON 对象 tasks 数组每个任务的处理结果。

顶层字段

字段	类型	说明
`version`	string	API 当前版本。
`status_code`	integer	通用状态码。成功通常为 `20000`。
`status_message`	string	通用状态说明。
`time`	string	请求执行耗时，例如 `0.7839 sec.`。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务总数。
`tasks_error`	integer	`tasks` 数组中执行失败的任务数量。
`tasks`	array	任务结果数组。

任务字段

字段	类型	说明
`id`	string	任务唯一标识，UUID 格式。
`status_code`	integer	任务状态码，通常位于 `10000` 至 `60000` 范围。
`status_message`	string	任务状态说明。
`time`	string	任务执行耗时。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`result_count`	integer	`result` 数组中的数量。
`path`	array	请求 URL 路径。
`data`	object	请求中提交的参数。
`result`	array	任务结果数组。

结果字段

result 数组中的对象以下字段：

字段	类型	说明
`target`	string	请求中的目标域名。
`location_code`	integer	地区代码。
`language_code`	string	语言代码。
`total_count`	integer	数据库中符合请求条件的结果总数。
`items_count`	integer	本次返回的域名数量。
`items`	array	目标域名及竞争域名的详细数据。

`items` 域名数据

字段	类型	说明
`domain`	string	域名。
`avg_position`	integer	域名在搜索结果页中的平均排名。基于交集计算；同一域名与不同目标域名组合时，该值可能不同。
`sum_position`	integer	域名在搜索结果页中的排名总和。
`intersections`	integer	与目标域名排名的数量。
`full_domain_metrics`	object	域名所有排名的完整排名和流量指标。
`metrics`	object	域名与目标域名交集的排名和流量指标。
`competitor_metrics`	object	返回的竞争域名在交集上的排名和流量指标。

指标对象

full_domain_metrics、metrics 和 competitor_metrics 均可能以下结果类型对象：

organic：自然搜索指标
paid：付费搜索指标
local_pack：自然搜索中的本地结果指标
featured_snippet：自然搜索中的精选摘要指标

：

full_domain_metrics 针对该域名的排名；
metrics 针对该域名与目标域名排名的，并以目标域名的表现为主；
competitor_metrics 针对该域名与目标域名排名的，并以竞争域名的表现为主。

各结果类型的通用字段

字段	类型	说明
`pos_1`	integer	排名第 1 的搜索结果页数量。
`pos_2_3`	integer	排名第 2 至第 3 的搜索结果页数量。
`pos_4_10`	integer	排名第 4 至第 10 的搜索结果页数量。
`pos_11_20`	integer	排名第 11 至第 20 的搜索结果页数量。
`pos_21_30`	integer	排名第 21 至第 30 的搜索结果页数量。
`pos_31_40`	integer	排名第 31 至第 40 的搜索结果页数量。
`pos_41_50`	integer	排名第 41 至第 50 的搜索结果页数量。
`pos_51_60`	integer	排名第 51 至第 60 的搜索结果页数量。
`pos_61_70`	integer	排名第 61 至第 70 的搜索结果页数量。
`pos_71_80`	integer	排名第 71 至第 80 的搜索结果页数量。
`pos_81_90`	integer	排名第 81 至第 90 的搜索结果页数量。
`pos_91_100`	integer	排名第 91 至第 100 的搜索结果页数量。
`etv`	float	预估流量。表示预计的月度搜索流量，通常点击率（CTR）乘以搜索量计算。
`impressions_etv`	float	基于展示次数的预估流量，通常点击率（CTR）乘以展示次数计算。
`count`	integer	含该域名的搜索结果页总数。
`estimated_paid_traffic_cost`	float	预估流量价值。自然搜索场景下，表示将预估自然流量通过付费搜索获取所需的月度广告成本；付费搜索场景下，表示付费流量的预估月度成本。该指标基于 `etv` 和每次点击成本（CPC）计算。
`is_new`	integer	新发现的排名数量。
`is_up`	integer	排名上升的数量。
`is_down`	integer	排名下降的数量。
`is_lost`	integer	上次检查中存在、但本次检查未发现的排名数量。

> local_pack 和 featured_snippet 的字段结构与上述结果类型基本一致，但统计范围分别限定为本地结果和精选摘要。

响应示例

json

{
  "version": "0.1.20210622",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.7839 sec.",
  "cost": 0.0105,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.7000 sec.",
      "cost": 0.0105,
      "result_count": 1,
      "path": [
        "v3",
        "dataforseo_labs",
        "competitors_domain",
        "live"
      ],
      "data": {
        "api": "dataforseo_labs",
        "function": "competitors_domain",
        "target": "example.com",
        "language_name": "English",
        "location_code": 2840,
        "limit": 5
      },
      "result": [
        {
          "target": "example.com",
          "location_code": 2840,
          "language_code": "en",
          "total_count": 125,
          "items_count": 5,
          "items": [
            {
              "domain": "competitor.example",
              "avg_position": 18,
              "sum_position": 900,
              "intersections": 50,
              "full_domain_metrics": {
                "organic": {
                  "pos_1": 3,
                  "pos_2_3": 8,
                  "pos_4_10": 20,
                  "etv": 1250.5,
                  "impressions_etv": 1800.2,
                  "count": 75,
                  "estimated_paid_traffic_cost": 420.3,
                  "is_new": 4,
                  "is_up": 10,
                  "is_down": 3,
                  "is_lost": 2
                }
              },
              "metrics": {},
              "competitor_metrics": {}
            }
          ]
        }
      ]
    }
  ]
}

状态码与错误处理

请根据顶层及任务级别的 status_code 和 status_message 判断请求是否成功：

20000：请求或任务成功；
状态码：请求或任务失败，原因以 status_message 为准。

建议在客户端实现以下处理逻辑：

同时检查顶层和任务级别的状态码；
记录 id、status_code 和 status_message；
对临时性错误执行有限次数重试；
对参数错误直接修正请求，不重复提交；
按 tasks_error 统计批量任务中的失败数量。

错误码可参考本平台的错误码文档。

实用场景

识别自然搜索竞争域名：发现与目标网站排名的竞争对手，为竞品研究和市场定位提供依据。
比较交集表现：分析目标域名与竞争域名在上的排名差距，确定优优化的集合。
评估竞争对手流量规模：结合 etv、impressions_etv 和排名区间，估算竞争域名的自然搜索流量潜力。
分析付费搜索竞争：通过 paid 和 estimated_paid_traffic_cost 评估竞争对手的广告覆盖范围及潜在投放成本。
筛选高竞争对手：使用 intersecting_domains、max_rank_group 和 exclude_top_domains 缩小结果范围，提升竞品名单对业务决策的性。

竞争域名分析（旧版） ​

请求信息 ​

认证 ​

请求参数 ​

地区与语言 ​

过滤器示例 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应结构 ​

顶层字段 ​

任务字段 ​

结果字段 ​

items 域名数据 ​

指标对象 ​

各结果类型的通用字段 ​

响应示例 ​

状态码与错误处理 ​

实用场景 ​