主题
按域名获取搜索类别（旧版）
GET /v3/dataforseo_labs/locations_and_languages
本接口使用 POST 方法，路径为：
POST https://api.seermartech.cn/v3/dataforseo_labs/categories_for_domain/live
> 本接口为旧版（Legacy）接口，用于获取域名在 Google 搜索结果中排名所属的产品或服务类别，并返回每个类别对应的自然搜索、付费搜索、精选摘要和本地排名及流量数据。
计费与请求限制
每次请求均会产生费用。原始文档未提供固定单价，扣费以响应头 X-SeerMarTech-Charge-CNY 为准。
请求体使用 UTF-8 编码的 JSON 格式，并且顶层结构是任务数组：
json
[
{
"target": "example.com",
"location_code": 2840,
"language_code": "en"
}
]单个请求可提交多个任务。平台限流以认证说明中的 30/60/120 次/分钟规则为准。
支持以下能力：
- 指定返回结果数量；
- 按条件过滤结果；
- 按指定字段排序；
- 分页获取类别结果；
- 使用
tag标识任务。
请求参数
| 参数 | 类型 | 填 | 说明 |
|---|---|---|---|
target | string | 是 | 目标域名。请勿 https:// 或 www.，例如 example.com。 |
location_name | string | 条件填 | 地理位置完整名称。当未指定 location_code 时填。location_name 与 location_code 至少指定一个。 |
location_code | integer | 条件填 | 地理位置代码。当未指定 location_name 时填。location_name 与 location_code 至少指定一个。 |
language_name | string | 条件填 | 语言完整名称。当未指定 language_code 时填。language_name 与 language_code 至少指定一个。 |
language_code | string | 条件填 | 语言代码。当未指定 language_name 时填。language_name 与 language_code 至少指定一个。 |
include_subcategories | boolean | 否 | 是否在结果中子类别。设置为 false 时忽略子类别。默认值为 false。 |
item_types | array | 否 | 指定返回的搜索结果类型。可选值：organic、paid、featured_snippet、local_pack。如果数组中除 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 个字符。该值会原样返回在响应的 data 对象中。 |
地理位置与语言
可通过以下接口查询可用的地理位置和语言：
GET https://api.seermartech.cn/v3/dataforseo_labs/locations_and_languages
示例：
location_name：United Kingdomlocation_code：2840language_name：Englishlanguage_code：en
过滤条件示例
以下条件表示：
- 自然搜索结果中至少 100 个排名；
- 并且自然搜索第 1 名数量大于 0，或付费搜索结果数量为 1 或 2。
json
[
{
"target": "example.com",
"location_name": "United States",
"language_name": "English",
"filters": [
[
"metrics.organic.count",
">=",
100
],
"and",
[
[
"metrics.organic.pos_1",
">",
0
],
"or",
[
"metrics.paid.count",
"in",
[1, 2]
]
]
],
"limit": 5
}
]排序示例
json
[
{
"target": "example.com",
"location_code": 2840,
"language_code": "en",
"order_by": [
"metrics.organic.etv,desc",
"metrics.organic.count,desc"
],
"limit": 20
}
]请求示例
cURL
bash
curl --location --request POST \
"https://api.seermartech.cn/v3/dataforseo_labs/categories_for_domain/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.count",
">=",
100
],
"and",
[
[
"metrics.organic.pos_1",
">",
0
],
"or",
[
"metrics.paid.count",
"in",
[1, 2]
]
]
],
"limit": 5
}
]'Python
python
import requests
url = "https://api.seermartech.cn/v3/dataforseo_labs/categories_for_domain/live"
headers = {
"Authorization": "Bearer smt_live_YOUR_KEY",
"Content-Type": "application/json",
}
post_data = [
{
"target": "example.com",
"location_name": "United States",
"language_name": "English",
"filters": [
["metrics.organic.count", ">=", 100],
"and",
[
["metrics.organic.pos_1", ">", 0],
"or",
["metrics.paid.count", "in", [1, 2]],
],
],
"limit": 5,
}
]
response = requests.post(url, headers=headers, json=post_data)
response.raise_for_status()
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 response = await axios.post(
"https://api.seermartech.cn/v3/dataforseo_labs/categories_for_domain/live",
[
{
target: "example.com",
location_code: 2840,
language_code: "en",
filters: [
["metrics.organic.count", ">=", 100],
"and",
[
["metrics.organic.pos_1", ">", 0],
"or",
["metrics.paid.count", "in", [1, 2]],
],
],
limit: 5,
},
],
{
headers: {
Authorization: "Bearer smt_live_YOUR_KEY",
"Content-Type": "application/json",
},
}
);
if (response.data.status_code === 20000) {
console.log(response.data);
} else {
console.error(
`请求失败。错误码：${response.data.status_code}，错误信息：${response.data.status_message}`
);
}响应结构
接口返回 JSON 对象，核心结构如下：
json
{
"version": "0.1.20210818",
"status_code": 20000,
"status_message": "Ok.",
"time": "0.2796 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.2500 sec.",
"cost": 0.0105,
"result_count": 1,
"path": [
"v3",
"dataforseo_labs",
"categories_for_domain",
"live"
],
"data": {
"api": "dataforseo_labs",
"function": "categories_for_domain",
"target": "example.com",
"location_code": 2840,
"language_code": "en",
"limit": 5
},
"result": [
{
"target": "example.com",
"location_code": 2840,
"language_code": "en",
"total_count": 741,
"items_count": 1,
"items": [
{
"categories": [],
"metrics": {
"organic": {
"pos_1": 4,
"pos_2_3": 13,
"pos_4_10": 25,
"pos_11_20": 61,
"pos_21_30": 69,
"pos_31_40": 83,
"pos_41_50": 97,
"pos_51_60": 104,
"pos_61_70": 84,
"pos_71_80": 77,
"pos_81_90": 73,
"pos_91_100": 51,
"etv": 971.3033,
"impressions_etv": 172.2075,
"count": 741,
"estimated_paid_traffic_cost": 8051.8686,
"is_new": 185,
"is_up": 220,
"is_down": 300,
"is_lost": 0
},
"paid": null,
"featured_snippet": null,
"local_pack": null
}
}
]
}
]
}
]
}顶层响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
version | string | API 当前版本。 |
status_code | integer | 请求的总体状态码。成功通常为 20000。 |
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 | 当前任务的状态码。 |
status_message | string | 当前任务的状态信息。 |
time | string | 当前任务的执行耗时，单位为秒。 |
cost | float | 平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。 |
result_count | integer | result 数组中的数量。 |
path | array | 请求 URL 的路径组成部分。 |
data | object | 请求中提交的任务参数。 |
result | array | 任务结果数组。 |
结果字段
| 字段 | 类型 | 说明 |
|---|---|---|
target | string | 请求中的目标域名。 |
location_code | integer | 请求中的地理位置代码。 |
language_code | string | 请求中的语言代码。 |
total_count | integer | 数据库中与请求条件匹的结果总数。 |
items_count | integer | 本次返回的 items 数量。 |
items | array | 类别及排名数据。 |
items 对象
| 字段 | 类型 | 说明 |
|---|---|---|
categories | array | 产品或服务类别列表。 |
metrics | object | 目标域名在当前类别下的排名与流量指标。 |
metrics.organic | object | 自然搜索排名与流量指标。 |
metrics.paid | object | 付费搜索排名与流量指标。 |
metrics.featured_snippet | object/null | Google 搜索精选摘要中的排名与流量指标。 |
metrics.local_pack | object/null | 搜索结果本地中的排名与流量指标。 |
排名与流量指标
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 | 基于展示次数计算的预估流量值，通常根据点击率（CTR）与展示次数计算。 |
count | integer | 含该域名的对应类型搜索结果总数。 |
estimated_paid_traffic_cost | float | 预估付费流量成本。表示通过搜索广告获取等量月度流量所需的预估成本。 |
is_new | integer | 新发现的排名数量。 |
is_up | integer | 排名上升的数量。 |
is_down | integer | 排名下降的数量。 |
is_lost | integer | 上次检查时存在、但本次检查未发现的排名数量。 |
：
organic指自然搜索结果；paid指付费搜索结果；featured_snippet指精选摘要结果；local_pack指本地结果；etv、impressions_etv和estimated_paid_traffic_cost均为估算指标，不代表访问量或广告支出；categories中的类别取决于目标域名、地区、语言和数据覆盖范围。
状态码与错误处理
请根据以下字段判断请求是否成功：
- 顶层
status_code； - 任务级
tasks[].status_code； - 对应的
status_message。
建议客户端同时处理 HTTP 错误、顶层错误、任务级错误和空结果等。完整错误码请参考本平台错误码文档。
实用场景
- 识别域名的核心产品与服务类别，定位网站覆盖的搜索主题，为 SEO规划和栏目建设提供依据。
- 比较不同类别下的自然搜索排名分布，发现排名集中在第 11 至第 20 名的类别，优制定页面优化和链提升计划。
- 评估类别级自然搜索流量潜力，结合
etv、impressions_etv和count估算重点业务类别的流量贡献。 - 监控类别级排名变化，通过
is_new、is_up、is_down和is_lost识别增长、下滑及排名流失的业务主题。 - 发现自然搜索与付费搜索之间的机会差异，对比
organic与paid指标，为投放、预算分和 SEO/PPC 协同提供依据。