子域名查询（旧版）

GET /v3/dataforseo_labs/locations_and_languages

本接口使用 POST /v3/dataforseo_labs/subdomains/live，用于查询指定域名下的子域名，并返回在自然搜索、付费搜索及搜索结果类型中的排名分布、预估流量和流量价值。

本页面描述的是旧版接口结构。接口已于 2022 年 3 月 19 日更新请求和响应结构，但旧版路径仍可继续使用。新版本请参考 /v3/dataforseo_labs/google/subdomains/live/。

接口信息

请求方法： POST
请求路径： /v3/dataforseo_labs/subdomains/live
完整 URL： https://api.seermartech.cn/v3/dataforseo_labs/subdomains/live
请求格式： JSON
请求体格式： JSON 数组，编码为 UTF-8 平台限流以认证说明中的 30/60/120 次/分钟规则为准

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

请求参数

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

参数	类型	填	说明
`target`	string	是	目标网站域名。不要 `https://` 或 `www.`，例如 `example.com`。
`location_name`	string	否	地区名。设置后无需设置 `location_code`。省略时返回所有可用地区的数据。
`location_code`	integer	否	地区代码。设置后无需设置 `location_name`。省略时返回所有可用地区的数据。
`language_name`	string	否	语言名。设置后无需设置 `language_code`。省略时返回所有可用语言的数据。
`language_code`	string	否	语言代码。设置后无需设置 `language_name`。省略时返回所有可用语言的数据。
`item_types`	array	否	指定需要返回的搜索结果类型。不同于 `organic` 时，结果将数组中的第一个结果类型排序。未在数组中的结果类型不能用于筛选或排序。
`filters`	array	否	结果筛选条件。最多设置 8 个筛选条件，条件之间使用 `and` 或 `or` 连接。
`order_by`	array	否	结果排序规则。可使用与 `filters` 相同的字段和表达式，每条规则使用 `asc` 或 `desc` 指定升序或降序。单次请求最多设置 3 条排序规则。
`limit`	integer	否	返回结果的最大数量。默认值为 `100`，最大值为 `1000`。
`offset`	integer	否	结果偏移量。默认值为 `0`。例如设置为 `10` 时，跳过前 10 条结果。
`tag`	string	否	自定义任务标识，最长 255 个字符。该值会原样返回在响应的 `data` 对象中，可用于请求与结果。

地区和语言

location_name 与 location_code 二选一；language_name 与 language_code 二选一。

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

text

https://api.seermartech.cn/v3/dataforseo_labs/locations_and_languages

示例：

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

`item_types` 可选值

item_types 用于指定返回的搜索结果类型。可选值：

organic
paid
featured_snippet
local_pack

如果不传该参数，接口使用默认结果类型。

筛选条件

支持的比较运算符：

<
<=
>
>=
=
<>
in
not_in

示例：

json

[
  {
    "target": "example.com",
    "filters": [
      [
        "metrics.organic.pos_1",
        "<>",
        0
      ],
      "or",
      [
        "metrics.organic.pos_2_3",
        "<>",
        0
      ]
    ]
  }
]

筛选条件最多 8 个。多个条件之间显式指定 and 或 or。

排序规则

排序规则使用字段名和排序方向组成，例如：

json

[
  {
    "target": "example.com",
    "order_by": [
      "metrics.organic.etv,desc",
      "metrics.organic.count,desc"
    ]
  }
]

单次请求最多设置 3 条排序规则。若 item_types 中 organic 以外的类型，结果将优 item_types 数组中的第一个类型排序。

请求示例

curl

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/dataforseo_labs/subdomains/live" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "target": "example.com",
      "location_code": 2840,
      "language_code": "en",
      "filters": [
        [
          "metrics.organic.pos_1",
          "<>",
          0
        ],
        "or",
        [
          "metrics.organic.pos_2_3",
          "<>",
          0
        ]
      ],
      "limit": 5
    }
  ]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/dataforseo_labs/subdomains/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.pos_1", "<>", 0],
            "or",
            ["metrics.organic.pos_2_3", "<>", 0],
        ],
        "limit": 5,
    }
]

response = requests.post(url, headers=headers, json=payload)
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 payload = [
  {
    target: "example.com",
    location_name: "United States",
    language_name: "English",
    filters: [
      ["metrics.organic.pos_1", "<>", 0],
      "or",
      ["metrics.organic.pos_2_3", "<>", 0],
    ],
    limit: 5,
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/dataforseo_labs/subdomains/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	请求级状态码。
`status_message`	string	请求级状态信息。
`time`	string	请求执行耗时，单位为秒。
`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	请求路径。
`data`	object	本次任务使用的请求参数。
`result`	array	查询结果数组。

状态码和错误信息请参考错误码文档。

`result` 字段

字段	类型	说明
`target`	string	请求中的目标域名。
`location_code`	integer	请求中的地区代码。
`language_code`	string	请求中的语言代码。
`total_count`	integer	数据库中符合请求条件的结果总数。
`items_count`	integer	`items` 数组中的结果数量。
`items`	array	子域名及排名指标。

`items` 字段

字段	类型	说明
`subdomain`	string	返回的子域名。
`metrics`	object	该子域名的排名和流量指标。
`metrics.organic`	object	自然搜索排名和流量数据。
`metrics.paid`	object	付费搜索排名和流量数据。
`metrics.featured_snippet`	object	Google 搜索结果中精选摘要的排名和流量数据。
`metrics.local_pack`	object	搜索结果本地中的排名和流量数据。

搜索类型指标

organic、paid、featured_snippet 和 local_pack 对象均使用相同的排名区间字段：

字段	类型	说明
`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	基于展示次数估算的流量。根据排名的展示次数与点击率估算的月度流量。
`count`	integer	含该子域名的对应搜索结果总数。
`estimated_paid_traffic_cost`	float	预估流量成本。用于表示通过付费搜索获得相同月度流量所需的估算成本，通常根据预估流量和每次点击成本（CPC）计算。
`is_new`	integer	新增排名结果数量。
`is_up`	integer	排名上升的结果数量。
`is_down`	integer	排名下降的结果数量。
`is_lost`	integer	丢失排名的结果数量，即上次检测到、但本次未再出现在搜索结果中的结果数量。

：

organic 指自然搜索结果。
paid 指付费搜索结果。
featured_snippet 指精选摘要结果。
local_pack 指本地结果。
对于 paid、featured_snippet 和 local_pack，etv、impressions_etv 及 estimated_paid_traffic_cost 均对应搜索结果类型计算。

响应示例

json

{
  "version": "0.1.20210818",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.2212 sec.",
  "cost": 0.0101,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.1800 sec.",
      "cost": 0.0101,
      "result_count": 1,
      "path": [
        "v3",
        "dataforseo_labs",
        "subdomains",
        "live"
      ],
      "data": {
        "api": "dataforseo_labs",
        "function": "subdomains",
        "target": "example.com",
        "language_name": "English",
        "location_code": 2840,
        "filters": [
          [
            "metrics.organic.pos_1",
            "<>",
            0
          ],
          "or",
          [
            "metrics.organic.pos_2_3",
            "<>",
            0
          ]
        ],
        "limit": 5
      },
      "result": [
        {
          "target": "example.com",
          "location_code": 2840,
          "language_code": "en",
          "total_count": 1,
          "items_count": 1,
          "items": [
            {
              "subdomain": "blog.example.com",
              "metrics": {
                "organic": {
                  "pos_1": 10,
                  "pos_2_3": 15,
                  "pos_4_10": 32,
                  "pos_11_20": 40,
                  "pos_21_30": 21,
                  "pos_31_40": 18,
                  "pos_41_50": 12,
                  "pos_51_60": 8,
                  "pos_61_70": 5,
                  "pos_71_80": 3,
                  "pos_81_90": 2,
                  "pos_91_100": 1,
                  "etv": 12500.5,
                  "impressions_etv": 14800.2,
                  "count": 167,
                  "estimated_paid_traffic_cost": 9200.4,
                  "is_new": 6,
                  "is_up": 25,
                  "is_down": 11,
                  "is_lost": 3
                }
              }
            }
          ]
        }
      ]
    }
  ]
}

错误处理

建议根据以下字段处理请求级和任务级异常：

status_code
status_message
tasks_error
tasks[].status_code
tasks[].status_message

只有当请求级或任务级 status_code 为 20000 时，才表示对应层级处理成功。状态码请参考错误码文档。

实用场景

识别高价值子域名：按 metrics.organic.etv 或 metrics.organic.count 排序，定位贡献自然流量和覆盖最多的子域名，支持站点架构优化。
发现增长机会：筛选 pos_11_20 或 pos_21_30 大于 0 的子域名，优优化接近首页的，提升自然排名和点击量。
监控子域名排名变化：对比 is_new、is_up、is_down 和 is_lost，识别排名增长、下滑及流失的业务模块。
评估自然流量商业价值：结合 etv 与 estimated_paid_traffic_cost，估算各子域名自然流量的潜在广告替代成本， SEO 预算分。
分析不同搜索结果类型的表现：通过 item_types 查询自然搜索、付费搜索、精选摘要或本地数据，评估子域名在不同 SERP 展示位中的可见度。

子域名查询（旧版） ​

接口信息 ​

请求参数 ​

地区和语言 ​

item_types 可选值 ​

筛选条件 ​

排序规则 ​

请求示例 ​

curl ​

Python ​

TypeScript ​

响应结构 ​

任务字段 ​

result 字段 ​

items 字段 ​

搜索类型指标 ​

响应示例 ​

错误处理 ​

实用场景 ​

子域名查询（旧版）

接口信息

请求参数

地区和语言

`item_types` 可选值

筛选条件

排序规则

请求示例

curl

Python

TypeScript

响应结构

任务字段

`result` 字段

`items` 字段

搜索类型指标

响应示例

错误处理

实用场景