按产品与服务类别获取域名指标（旧版）

GET /v3/dataforseo_labs/locations_and_languages

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

POST https://api.seermartech.cn/v3/dataforseo_labs/domain_metrics_by_categories/live

> 容说明：本接口属于旧版结构。平台 API 已于 2022 年 3 月 19 日更新请求与响应结构，但旧版接口仍提供容支持。新版本请参考对应的 Google 域名指标接口文档。

接口说明

本接口根据指定的产品与服务类别，返回域名的指标变化：

Google 自然搜索结果中的历史排名分布；
当前及历史自然搜索流量估算值（ETV）；
基于展示次数的流量估算值；
预计付费流量成本； -含目标域名的自然搜索、付费搜索、精选摘要和本地结果数量；
新增、上升、下降及丢失的排名数量；
两个时间点之间的指标差异。

每次请求最多提交 1 个任务。平台限流以认证说明中的 30/60/120 次/分钟规则为准。请求和响应均使用 UTF-8 编码的 JSON 格式。

计费

每次请求均会产生费用。参考价以本平台为准，扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数

请求体是 JSON 数组：

json

[
  {
    "category_codes": [13418, 11494],
    "location_code": 2840,
    "language_code": "en",
    "first_date": "2021-06-01",
    "second_date": "2021-10-01"
  }
]

任务参数

参数	类型	填	说明
`category_codes`	array	是	产品与服务类别编码数组，最多指定 5 个类别。
`first_date`	string	是	第一个对比日期，格式为 `yyyy-mm-dd`，例如 `2021-06-01`。最早可使用 `2020-10-01`，不能晚于当前日期。
`second_date`	string	是	第二个对比日期，格式为 `yyyy-mm-dd`，例如 `2021-10-01`。最早可使用 `2020-10-01`，不能晚于当前日期。
`location_name`	string	条件填	地理位置完整名称。未指定 `location_code` 时填。
`location_code`	integer	条件填	地理位置唯一编码。未指定 `location_name` 时填。
`language_name`	string	条件填	语言完整名称。未指定 `language_code` 时填。
`language_code`	string	条件填	语言唯一编码。未指定 `language_name` 时填。
`item_types`	array	否	按搜索结果类型返回数据。旧版接口默认返回 `organic` 对象对应的数据。若指定了不同于 `organic` 的类型，结果将按数组中的第一个类型排序。未返回的结果类型不能用于排序或筛选。
`top_categories_count`	integer	否	返回的额外域名类别数量。默认等于 `category_codes` 中的类别数量，不能小于该数量，最大值为 `5`。
`incude_subdomains`	boolean	否	是否返回子域名。`false` 返回 `main_domain`；`true` 返回主域名及可用子域名。默认值为 `true`。注意：参数名称按接口原始契约保留为 `incude_subdomains`。
`etv_min`	integer	否	当前自然搜索 ETV 最小值。返回 `organic_etv` 大于该值的域名。
`etv_max`	integer	否	当前自然搜索 ETV 最大值。返回 `organic_etv` 小于该值的域名。
`correlate`	boolean	否	是否将当前数据与此前获取的数据集进行。默认值为 `true`，用于降低数据库变化造成的数据不一致。通常不建议设置为 `false`。
`limit`	integer	否	返回结果的最大域名数量。默认值为 `100`，最大值为 `1000`。
`offset`	integer	否	结果偏移量，默认值为 `0`。例如设置为 `10` 时，跳过前 10 个域名。
`filters`	array	否	结果筛选条件，最多 8 个。多个条件之间使用逻辑运算符 `and` 或 `or`。
`order_by`	array	否	结果排序规则，最多 3 条。支持升序 `asc` 和降序 `desc`。
`tag`	string	否	自定义任务标识，最多 255 个字符。响应中会在 `data` 对象中原样返回。

日期限制

first_date 与 second_date 不能属于同一年同一月份；
两个日期可以按任意顺序传；
返回结果中的 $date_1 对应两个日期中较晚的月份；
返回结果中的 $date_2 对应两个日期中较早的月份。

地理位置和语言

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

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

：

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

筛选条件

支持以下运算符：

<、<=、>、>=、=、<>、in、not_in、like、not_like

like 和 not_like 支持使用 % 匹任意数量的字符。

筛选条件示例：

json

[
  "organic_etv",
  ">",
  1000
]

多个筛选条件示例：

json

[
  [
    "organic_etv",
    ">",
    1000
  ],
  "and",
  [
    "organic_count",
    ">=",
    10
  ]
]

排序规则示例：

json

[
  "organic_etv,desc",
  "organic_count,desc"
]

响应结构

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

顶层字段

字段	类型	说明
`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`	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	任务结果数组。

结果字段

字段	类型	说明
`categories`	array	请求中的类别信息。
`location_code`	integer	地理位置编码。
`language_code`	string	语言编码。
`total_count`	integer	数据库中符合条件的结果总数。
`items_count`	integer	本次返回的 `items` 数量。
`items`	array	域名历史排名和流量数据。

域名项目字段

字段	类型	说明
`top_categories`	array	收集该域名时匹到的类别。
`organic_etv`	float	域名当前自然搜索 ETV。
`organic_count`	integer	当前该域名的自然搜索结果数量。
`organic_is_lost`	integer	当前丢失的自然搜索排名数量。
`organic_is_new`	integer	当前新增的自然搜索排名数量。
`domain`	string	在指定类别中发现的域名。
`main_domain`	string	域名的主域名。
`metrics_history`	object	两个日期对应月份的历史排名与流量指标。
`metrics_difference`	object	两个日期之间的指标差异。

`metrics_history` 历史指标

metrics_history 使用 yyyyMM 格式的月份作为动态字段，例如 202110、202106。

每个月份下可能以下对象：

organic：自然搜索历史数据；
paid：付费搜索历史数据；
featured_snippet：精选摘要历史数据；
local_pack：本地历史数据。

没有对应搜索结果类型时，字段值可能为 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	预计付费流量成本。自然搜索数据通常按自然搜索 `etv` 与付费 `cpc` 估算，表示通过搜索广告获取相同流量的月度成本。
`is_new`	integer	新增排名数量。
`is_up`	integer	排名上升的数量。
`is_down`	integer	排名下降的数量。
`is_lost`	integer	丢失排名数量，即此前存在但在当前检查中未找到的。

，字段含义会根据所在对象变化：

organic：自然搜索排名和流量；
paid：付费搜索排名和流量；
featured_snippet：精选摘要排名和流量；
local_pack：本地排名和流量。

`metrics_difference` 指标差异

metrics_difference 表示两个日期之间的指标变化，：

organic
paid
featured_snippet
local_pack

字段结构与 metrics_history 中对应对象一致排名区间、etv、impressions_etv、count、estimated_paid_traffic_cost、is_new、is_up、is_down 和 is_lost。

差异值按以下规则计算：

> 较晚日期的指标 − 较早日期的指标

因此：

正数表示指标增加；
负数表示指标减少；
0 表示没有变化。

例如：

json

{
  "metrics_difference": {
    "organic": {
      "pos_1": 1,
      "pos_2_3": 0,
      "pos_21_30": -1,
      "etv": 8739.0163,
      "impressions_etv": -0.0555,
      "count": -68,
      "is_new": 28,
      "is_up": -4,
      "is_down": -1,
      "is_lost": -63
    },
    "paid": {
      "pos_1": 0,
      "etv": 0,
      "count": 0
    },
    "featured_snippet": null,
    "local_pack": null
  }
}

请求示例

cURL

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/dataforseo_labs/domain_metrics_by_categories/live" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "category_codes": [13418, 11494],
      "language_name": "English",
      "location_code": 2840,
      "first_date": "2021-06-01",
      "second_date": "2021-10-01",
      "limit": 5
    }
  ]'

Python

python

import requests

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

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

payload = [
    {
        "category_codes": [13418, 11494],
        "language_name": "English",
        "location_code": 2840,
        "first_date": "2021-06-01",
        "second_date": "2021-10-01",
        "limit": 5,
    }
]

response = requests.post(url, headers=headers, json=payload, 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 response = await axios.post(
  "https://api.seermartech.cn/v3/dataforseo_labs/domain_metrics_by_categories/live",
  [
    {
      category_codes: [13418, 11494],
      language_name: "English",
      location_code: 2840,
      first_date: "2021-06-01",
      second_date: "2021-10-01",
      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

{
  "version": "0.1.20210917",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "1.3303 sec.",
  "cost": 0.105,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "1.3303 sec.",
      "cost": 0.105,
      "result_count": 1,
      "path": [
        "v3",
        "dataforseo_labs",
        "domain_metrics_by_categories",
        "live"
      ],
      "data": {
        "api": "dataforseo_labs",
        "function": "domain_metrics_by_categories",
        "location_code": 2840,
        "language_code": "en",
        "category_codes": [13418, 11494],
        "first_date": "2021-06-01",
        "second_date": "2021-10-01",
        "limit": 5
      },
      "result": [
        {
          "location_code": 2840,
          "language_code": "en",
          "total_count": 1378,
          "items_count": 1,
          "items": [
            {
              "top_categories": [13418, 11494],
              "organic_etv": 106.0256969127804,
              "organic_count": 31,
              "organic_is_lost": 29,
              "organic_is_new": 17,
              "domain": "www.example.com",
              "main_domain": "example.com",
              "metrics_history": {
                "202110": {
                  "organic": {
                    "pos_1": 0,
                    "pos_2_3": 0,
                    "pos_4_10": 0,
                    "pos_11_20": 1,
                    "pos_21_30": 2,
                    "pos_31_40": 3,
                    "pos_41_50": 9,
                    "pos_51_60": 8,
                    "pos_61_70": 9,
                    "pos_71_80": 6,
                    "pos_81_90": 14,
                    "pos_91_100": 5,
                    "etv": 15815.3835,
                    "impressions_etv": 0.01071,
                    "count": 56,
                    "estimated_paid_traffic_cost": 16609.7437,
                    "is_new": 45,
                    "is_up": 7,
                    "is_down": 0,
                    "is_lost": 28
                  },
                  "paid": {
                    "pos_1": 0,
                    "etv": 0,
                    "impressions_etv": 0,
                    "count": 0,
                    "estimated_paid_traffic_cost": 0,
                    "is_new": 0,
                    "is_up": 0,
                    "is_down": 0,
                    "is_lost": 0
                  },
                  "featured_snippet": null,
                  "local_pack": null
                },
                "202106": {
                  "organic": {
                    "pos_1": 0,
                    "pos_2_3": 0,
                    "pos_4_10": 0,
                    "pos_11_20": 1,
                    "pos_21_30": 3,
                    "pos_31_40": 5,
                    "etv": 7076.3672,
                    "impressions_etv": 0.0662,
                    "count": 125,
                    "estimated_paid_traffic_cost": 7556.0705,
                    "is_new": 17,
                    "is_up": 11,
                    "is_down": 1,
                    "is_lost": 91
                  },
                  "paid": {
                    "pos_1": 0,
                    "etv": 0,
                    "impressions_etv": 0,
                    "count": 0,
                    "estimated_paid_traffic_cost": 0,
                    "is_new": 0,
                    "is_up": 0,
                    "is_down": 0,
                    "is_lost": 0
                  },
                  "featured_snippet": null,
                  "local_pack": null
                }
              },
              "metrics_difference": {
                "organic": {
                  "pos_1": 0,
                  "pos_2_3": 0,
                  "pos_21_30": -1,
                  "pos_31_40": -2,
                  "etv": 8739.0163,
                  "impressions_etv": -0.0555,
                  "count": -68,
                  "estimated_paid_traffic_cost": 9053.6733,
                  "is_new": 28,
                  "is_up": -4,
                  "is_down": -1,
                  "is_lost": -63
                },
                "paid": {
                  "pos_1": 0,
                  "etv": 0,
                  "count": 0
                },
                "featured_snippet": null,
                "local_pack": null
              }
            }
          ]
        }
      ]
    }
  ]
}

错误处理

建议根据顶层和任务级别的 status_code、status_message 实现错误处理：

首检查顶层 status_code；
再检查每个任务的 status_code；
当 tasks_error 大于 0 时，逐项读取错误任务信息；
对日期、位置、语言、类别编码及筛选条件进行参数校验；
对时、限流和临时服务异常执行重试，但应无间隔重复请求。

完整状态码和错误消息请参考错误码文档。

实用场景

发现目标行业竞品域名：按产品与服务类别检索高 ETV 域名，快速建立竞品和对标名单。
比较行业域名的 SEO 增长：对比两个日期的排名区间、ETV 和结果数量，评估竞品自然搜索表现变化。
筛选高价值外链或合作对象：使用 etv_min、organic_count 等条件筛选流量和排名基础较强的域名，外链、联盟和媒体合作决策。
识别排名流失与增长机会：分析 is_new、is_up、is_down 和 is_lost，定位行业中快速增长或排名下滑的域名。
评估自然流量的广告替代成本：结合 estimated_paid_traffic_cost 与 etv，估算通过付费搜索获取同等流量的成本，为 SEO 与 SEM 预算分提供依据。

按产品与服务类别获取域名指标（旧版） ​

接口说明 ​

计费 ​

请求参数 ​

任务参数 ​

日期限制 ​

地理位置和语言 ​

筛选条件 ​

响应结构 ​

顶层字段 ​

任务字段 ​

结果字段 ​

域名项目字段 ​

metrics_history 历史指标 ​

排名区间字段 ​

流量和变化字段 ​

metrics_difference 指标差异 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应示例 ​

错误处理 ​

实用场景 ​

按产品与服务类别获取域名指标（旧版）

接口说明

计费

请求参数

任务参数

日期限制

地理位置和语言

筛选条件

响应结构

顶层字段

任务字段

结果字段

域名项目字段

`metrics_history` 历史指标

排名区间字段

流量和变化字段

`metrics_difference` 指标差异

请求示例

cURL

Python

TypeScript

响应示例

错误处理

实用场景