SeerMarTech API 文档

主题

SERP 竞争对手分析（旧版） ​

GET /v3/dataforseo_labs/locations_and_languages

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

/v3/dataforseo_labs/serp_competitors/live

> 本接口为旧版容接口。请求和响应结构已更新，但旧版路径仍可继续使用。新版接口请参考对应的新版 SERP 竞争对手分析文档。

本接口根据指定，返回在搜索结果中排名的竞争对手域名，并提供平均排名、中位排名、预估流量、SERP 可见度等指标。

计费说明 ​

每次请求均会产生费用。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

所有 POST 请求体使用 UTF-8 编码的 JSON 格式，并且是 JSON 数组：

json
[
  {
    "keywords": ["phone", "watch"],
    "location_name": "United States",
    "language_name": "English"
  }
]

单个请求最多可提交 200 个；平台限流以认证说明中的 30/60/120 次/分钟规则为准。你可以通过 limit、offset、filters 和 order_by 控制返回结果数量、筛选条件及排序方式。

请求参数 ​

参数类型说明
keywordsarray填。用于分析的数组。使用 UTF-8 编码，接口会将转换为小写。每个至少 3 个字符，最多可提交 200 个。
location_namestring地区完整名称。当未指定 location_code 时填。在 location_name 和 location_code 中二选一。
location_codeinteger地区唯一标识。当未指定 location_name 时填。在 location_name 和 location_code 中二选一。示例：2840。
language_namestring语言完整名称。当未指定 language_code 时填。在 language_name 和 language_code 中二选一。示例：English。
language_codestring语言唯一标识。当未指定 language_name 时填。在 language_name 和 language_code 中二选一。示例：en。
include_subdomainsboolean是否将子域名纳搜索范围。可选，默认值为 true。设置为 false 时忽略子域名。
item_typesarray搜索结果类型。用于指定响应中的搜索结果类型。可选；旧版接口未提供固定枚举列表。
limitinteger返回的最大域名数量。可选，默认值为 100，最大值为 1000。
offsetinteger结果数组的偏移量。可选，默认值为 0。例如设置为 10 时，将跳过前 10 个域名，返回后续结果。
filtersarray结果筛选条件。可选，最多设置 8 个筛选条件。多个条件之间使用 and 或 or 连接。
order_byarray结果排序规则。可选。排序字段可使用与 filters 相同的字段，排序方向支持 asc 和 desc。单次请求最多设置 3 条排序规则。
tagstring自定义任务标识。可选，最长 255 个字符。该值会原样返回在响应的 data 对象中，可用于请求与结果。

地区和语言 ​

可通过以下接口获取可用的地区和语言列表：

/v3/dataforseo_labs/locations_and_languages

也可以使用完整名称或唯一编码，例如：

json
{
  "location_name": "United Kingdom",
  "language_name": "English"
}

或：

json
{
  "location_code": 2840,
  "language_code": "en"
}

筛选条件 ​

筛选条件支持以下运算符：

  • <
  • <=
  • >
  • >=
  • =
  • <>
  • in
  • not_in
  • like
  • not_like

使用 like 或 not_like 时，可以使用 % 匹任意长度的字符串空字符串。

示例：

json
{
  "filters": [
    ["relevant_serp_items", ">", 0],
    "or",
    ["median_position", "in", [1, 10]]
  ]
}

排序规则 ​

排序方向：

  • asc：升序
  • desc：降序

示例：

json
{
  "order_by": [
    "visibility,desc",
    "etv,desc",
    "avg_position,asc"
  ]
}

响应字段 ​

接口返回 JSON 数据，顶层 tasks 数组。

顶层字段 ​

字段类型说明
versionstring当前 API 版本。
status_codeinteger请求整体状态码。成功通常为 20000。
status_messagestring请求整体状态信息。
timestring请求执行耗时，单位为秒。
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
tasks_countintegertasks 数组中的任务总数。
tasks_errorintegertasks 数组中执行失败的任务数量。
tasksarray任务结果数组。

tasks 字段 ​

字段类型说明
idstring任务唯一标识，UUID 格式。
status_codeinteger当前任务状态码，通常处于 10000 至 60000 范围。
status_messagestring当前任务状态信息。
timestring任务执行耗时，单位为秒。
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
result_countintegerresult 数组中的数量。
patharray当前请求的 API 路径。
dataobject本次 POST 请求中提交的任务参数。
resultarray竞争对手分析结果数组。

result 字段 ​

字段类型说明
seed_keywordsstring分析。返回时会对 URL 编码进行解码，+ 会被解码为空格。
location_codeinteger请求中的地区编码。没有数据时返回 null。
language_codestring请求中的语言编码。没有数据时返回 null。
total_countinteger数据库中与请求条件的结果总数。
items_countintegeritems 数组中返回的结果数量。
itemsarray检测到的 SERP 竞争对手及指标。

items 字段 ​

字段类型说明
domainstring检测到的 SERP 竞争对手域名。
avg_positioninteger / float域名在指定下的平均排名，即 keywords_positions 中排名值的算术平均值。
median_positioninteger / float域名在指定下的中位排名，即 keywords_positions 中排名值的中位数。
ratinginteger域名在指定下的相对 SERP 可见度指标，计算方式为 sum(100 - keywords_positions)。
etvfloat预估流量值，表示指定预计每月为网站带来的流量。该值根据搜索量及在相应排名位置的点击率估算。
keywords_countinteger该域名在指定中取得 SERP 排名的数量。
visibilityfloatSERP 可见度。排名在 1 至 10 位的分别获得 1 至 0.1 的可见度指数；排名在 11 至 20 位的固定为 0.05；排名在 20 至 100 位的可见度为 0。
relevant_serp_itemsinteger与该域名的 SERP素数量，表示指定搜索结果中与该域名的结果数量。
keywords_positionsobject排名映射。键为，值为该域名在对应下的 SERP 排名。

请求示例 ​

curl ​

bash
curl --location --request POST \
  "https://api.seermartech.cn/v3/dataforseo_labs/serp_competitors/live" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "keywords": [
        "phone",
        "watch"
      ],
      "language_name": "English",
      "location_code": 2840,
      "include_subdomains": false,
      "limit": 3,
      "filters": [
        ["relevant_serp_items", ">", 0],
        "or",
        ["median_position", "in", [1, 10]]
      ]
    }
  ]'

Python ​

python
import requests

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

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

# POST 请求体是 JSON 数组
post_data = [
    {
        "keywords": [
            "phone",
            "watch",
        ],
        "location_name": "United States",
        "language_name": "English",
        "filters": [
            ["relevant_serp_items", ">", 0],
            "or",
            ["median_position", "in", [1, 10]],
        ],
    }
]

response = requests.post(url, headers=headers, json=post_data, timeout=60)
result = response.json()

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        "请求失败。状态码：%s，信息：%s"
        % (result.get("status_code"), result.get("status_message"))
    )

TypeScript ​

typescript
import axios from "axios";

const postData = [
  {
    keywords: ["phone", "watch"],
    language_name: "English",
    location_code: 2840,
    filters: [
      ["relevant_serp_items", ">", 0],
      "or",
      ["median_position", "in", [1, 10]],
    ],
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/dataforseo_labs/serp_competitors/live",
    postData,
    {
      headers: {
        Authorization: "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
      },
    }
  )
  .then((response) => {
    const result = response.data;

    if (result.status_code === 20000) {
      console.log(result);
    } else {
      console.error(
        `请求失败。状态码：${result.status_code}，信息：${result.status_message}`
      );
    }
  })
  .catch((error) => {
    console.error("请求异常：", error.message);
  });

响应示例 ​

json
{
  "version": "0.1.20200317",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.2667 sec.",
  "cost": 0.0103,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.2667 sec.",
      "cost": 0.0103,
      "result_count": 1,
      "path": [
        "v3",
        "dataforseo_labs",
        "serp_competitors",
        "live"
      ],
      "data": {
        "api": "dataforseo_labs",
        "function": "serp_competitors",
        "keywords": [
          "reuse iphone"
        ],
        "language_name": "English",
        "location_code": 2840,
        "include_subdomains": false,
        "limit": 3
      },
      "result": [
        {
          "seed_keywords": "reuse iphone",
          "location_code": 2840,
          "language_code": "en",
          "total_count": 98,
          "items_count": 3,
          "items": [
            {
              "domain": "example.com",
              "avg_position": 12.5,
              "median_position": 12,
              "rating": 175,
              "etv": 0.125,
              "keywords_count": 1,
              "visibility": 0.05,
              "relevant_serp_items": 2,
              "keywords_positions": {
                "reuse iphone": 12
              }
            },
            {
              "domain": "google.com",
              "avg_position": 20.5,
              "median_position": 20,
              "rating": 159,
              "etv": 0.094,
              "keywords_count": 1,
              "visibility": 0.05,
              "relevant_serp_items": 2,
              "keywords_positions": {
                "reuse iphone": 20
              }
            },
            {
              "domain": "ifixit.com",
              "avg_position": 31.5,
              "median_position": 29,
              "rating": 137,
              "etv": 0.084,
              "keywords_count": 1,
              "visibility": null,
              "relevant_serp_items": 2,
              "keywords_positions": {
                "reuse iphone": 29
              }
            }
          ]
        }
      ]
    }
  ]
}

错误处理 ​

请根据顶层 status_code、任务级 status_code 及对应的 status_message 判断请求和任务是否成功。建议在业务系统中针对网络异常、参数错误、权限错误、频率限制及平台数据异常建立统一的错误处理机制。

实用场景 ​

  • 识别目标的 SERP 竞争对手，发现占据搜索结果的域名，为竞品研究和策略制定提供依据。
  • 比较竞争对手的平均排名与中位排名，定位自身网站与竞争域名之间的排名差距，制定提升计划。
  • 筛选高可见度或高预估流量域名，优分析最搜索影响力的竞争对手，提升 SEO 竞品分析效率。
  • 按地区和语言分析竞争格局，评估不同国家或市场中的搜索结果差异，为本地化 SEO 和化布局提供数据支持。
  • 结合筛选与排序条件生成竞品单，批量提取符合排名、流量或 SERP素条件的域名，用于自动化监控和定期报告。

统一入口：官网 · LLM API · 控制台

© 2026 SeerMarTech · GEO · SEO 营销数据 API