子域名分析（旧版）实时接口

接口说明

注意：本接口文档对应的是旧版请求/响应结构。平台 API 已在 2022-03-19 更新了本平台 Labs 的结构，但当前仍继续容本旧版接口。如需新版结构，请参考对应的新版本文档。

该接口用于获取指定域名下的子域名列表，并返回各子域名在自然搜索、付费搜索等结果类型中的排名分布。同时，还会提供基于搜索量与展示量估算的流量数据，便于分析不同子域名的 SEO 表现与流量价值。

请求方式： POST接口地址： https://api.seermartech.cn/v3/dataforseo_labs/subdomains/live

计费与调用限制

本接口按请求计费
实扣费以响应头 X-SeerMarTech-Charge-CNY 为准
调用频率上限：2000 次/分钟
POST 数据使用 JSON UTF-8 编码
请求体格式为 JSON 数组：[{ ... }]

请求参数

字段名	类型	说明
`target`	string	填。目标站点的域名，不要 `https://` 和 `www.`
`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` 类型，则结果会按数组中第一个类型排序；同时只能对响应中的结果类型进行筛选和排序
`filters`	array	可选。结果过滤条件数组，最多 8 个过滤条件。条件之间需使用逻辑运算符 `and` 或 `or` 连接。支持运算符：`<`, `<=`, `>`, `>=`, `=`, `<>`, `in`, `not_in`
`order_by`	array	可选。排序规则。可使用与 `filters` 相同的字段路径进行排序。排序方式支持 `asc`（升序）与 `desc`（降序）。单次请求最多 3 组排序规则
`limit`	integer	可选。返回结果数量，默认 `100`，最大 `1000`
`offset`	integer	可选。结果偏移量，默认 `0`。例如传 `10` 表示跳过前 10 条结果
`tag`	string	可选。用户自定义任务标识，最大长度 `255`。可用于请求与响应结果的追踪

地域与语言列表

如需获取可用的 location_name、location_code、language_name、language_code，可调用：

/v3/dataforseo_labs/locations_and_languages

过滤与排序说明

filters 结构

filters 为数组结构，可组合多个条件，例如：

json

[
 ["metrics.organic.pos_1", "<>", 0],
 "or",
 ["metrics.organic.pos_2_3", "<>", 0]
]

表示：返回自然结果中排名第 1，或排名第 2-3 有数据的子域名。

order_by 结构

order_by 也是数组结构，示例：

json

["metrics.organic.etv,desc"]

表示：按自然搜索估算流量 etv 降序排列。

说明：如果 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",
 "language_name": "English",
 "location_code": 2840,
 "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"
}
data = [
 {
 "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, json=data, headers=headers)
print(response.json)

TypeScript

typescript

import axios from "axios";

const postData = [
 {
 target: "example.com",
 language_name: "English",
 location_code: 2840,
 filters: [
 ["metrics.organic.pos_1", "<>", 0],
 "or",
 ["metrics.organic.pos_2_3", "<>", 0]
 ],
 limit: 5
 }
];

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

响应结构

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

顶层字段

字段名	类型	说明
`version`	string	当前 API 版本
`status_code`	integer	通用状态码，完整列表见参考文档 `/v3/appendix/errors`
`status_message`	string	通用状态信息
`time`	string	执行耗时，单位秒
`cost`	float	本次请求总成本，单位 USD
`tasks_count`	integer	`tasks` 数组中的任务数量
`tasks_error`	integer	返回错误的任务数量
`tasks`	array	任务结果数组

tasks 数组字段

字段名	类型	说明
`id`	string	任务唯一标识，UUID 格式
`status_code`	integer	任务状态码，范围通常为 `10000-60000`
`status_message`	string	任务状态信息
`time`	string	任务执行耗时
`cost`	float	单任务成本，单位 USD
`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 数组字段

字段名	类型	说明
`subdomain`	string	返回的子域名
`metrics`	object	子域名的排名与流量指标

metrics 指标说明

metrics 下会按不同搜索结果类型返回数据，常见：

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	含该子域名的对应类型 SERP 总数
`estimated_paid_traffic_cost`	float	估算流量成本，单位 USD。用于估算通过付费投放获取同等流量所需成本
`is_new`	integer	新增排名数量
`is_up`	integer	排名上升的数量
`is_down`	integer	排名下降的数量
`is_lost`	integer	丢失排名的数量

各类型含义补

`organic`

自然搜索维度的数据，反映子域名在自然结果中的排名分布与估算流量表现。

`paid`

付费搜索维度的数据，反映子域名在广告结果中的排名分布与估算流量表现。

`featured_snippet`

精选摘要结果中的排名与流量分布。

`local_pack`

本地结果中的排名与流量分布。

响应示例

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": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.2212 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": 123,
 "items_count": 5,
 "items": [
 {
 "subdomain": "blog.example.com",
 "metrics": {
 "organic": {
 "pos_1": 12,
 "pos_2_3": 18,
 "pos_4_10": 35,
 "pos_11_20": 22,
 "pos_21_30": 14,
 "pos_31_40": 9,
 "pos_41_50": 4,
 "pos_51_60": 3,
 "pos_61_70": 2,
 "pos_71_80": 1,
 "pos_81_90": 0,
 "pos_91_100": 0,
 "etv": 1543.6,
 "impressions_etv": 1820.4,
 "count": 120,
 "estimated_paid_traffic_cost": 428.7,
 "is_new": 8,
 "is_up": 20,
 "is_down": 6,
 "is_lost": 2
 }
 }
 }
 ]
 }
 ]
 }
 ]
}

错误处理

顶层 status_code 表示整次请求是否成功
tasks[].status_code 表示单个任务的执行状态
建议同时校验：
HTTP 状态码
顶层 status_code
任务级 tasks[].status_code

常见成功状态：

状态码	说明
`20000`	请求成功

更多错误码请参考：/v3/appendix/errors

使用建议

target 填写裸域名，例如 example.com
如果要限定国家/地区与语言，优使用 location_code + language_code，更适合程序化调用
当只特定结果类型时，可结合 item_types、filters 和 order_by 缩小结果范围
若需要翻页获取更多子域名，请使用 limit 与 offset
生产环境中请记录响应中的 cost、time、tag 与 id，便于审计与排障

实用场景

识别高价值子域名：按 metrics.organic.etv 或 estimated_paid_traffic_cost 排序，快速找出带来自然流量与商业价值最高的子域名
排查站群或频道表现差异：对比 blog、shop、help 等子域名的排名分布，定位 SEO 强弱板块，指导资源分
监控子域名排名波动：结合 is_new、is_up、is_down、is_lost 追踪各子域名的排名变化，及时发现异常波动或流量风险
分析自然流量替代成本：使用 estimated_paid_traffic_cost 评估自然流量的广告等价价值，支持 SEO ROI 评估
挖掘 SERP 特殊结果机会：通过 featured_snippet、local_pack 等结果类型识别哪些子域名更容易占据特殊展示位，优化与本地化策略

子域名分析（旧版）实时接口 ​

接口说明 ​

计费与调用限制 ​

请求参数 ​

地域与语言列表 ​

过滤与排序说明 ​

filters 结构 ​

order_by 结构 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应结构 ​

顶层字段 ​

tasks 数组字段 ​

result 数组字段 ​

items 数组字段 ​

metrics 指标说明 ​

通用排名分布字段 ​

通用流量与变动字段 ​

各类型含义补 ​

organic ​

paid ​

featured_snippet ​

local_pack ​

响应示例 ​

错误处理 ​

使用建议 ​

实用场景 ​

子域名分析（旧版）实时接口

接口说明

计费与调用限制

请求参数

地域与语言列表

过滤与排序说明

filters 结构

order_by 结构

请求示例

cURL

Python

TypeScript

响应结构

顶层字段

tasks 数组字段

result 数组字段

items 数组字段

metrics 指标说明

通用排名分布字段

通用流量与变动字段

各类型含义补

`organic`

`paid`

`featured_snippet`

`local_pack`

响应示例

错误处理

使用建议

实用场景