页面（Legacy）

GET /v3/dataforseo_labs/locations_and_languages

本接口使用 POST 方法，路径为 /v3/dataforseo_labs/relevant_pages/live。接口用于查询指定域名下排名的网页，并返回各页面在自然搜索、付费搜索及搜索结果类型中的排名分布、预估月流量和流量价值等数据。

> 本页面为 Legacy 版本。虽然接口请求和响应结构已更新，平台仍继续容本版本。新项目建议优使用新版页面接口。

请求信息

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

每个任务对象应放请求体数组中。接口支持设置返回数量、偏移量、筛选条件和排序规则。

计费说明

每次请求任务计费。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

响应中的 cost 字段（平台原始 USD 成本兼容字段）为接口容字段，金额请以人民币扣费响应头为准。

请求参数

任务级参数

参数	类型	填	说明
`target`	string	是	目标网站域名。请勿 `https://` 或 `www.`，例如 `example.com`。
`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` 以外的类型，结果将数组中的第一个类型排序；未在数组中的类型不能用于筛选或排序。
`limit`	integer	否	最多返回的页面数量。默认值为 `100`，最大值为 `1000`。
`offset`	integer	否	结果偏移量，默认值为 `0`。例如设置为 `10` 时，将跳过前 10 条结果并返回后续页面。
`filters`	array	否	结果筛选条件。最多支持 8 个筛选条件，可使用 `and` 或 `or` 连接。
`order_by`	array	否	结果排序规则。最多支持 3 条排序规则。
`tag`	string	否	自定义任务标识，最长 255 个字符。该值会原样返回在响应的 `data` 对象中，可用于任务与结果。

地区与语言

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

GET /v3/dataforseo_labs/locations_and_languages

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

`item_types` 可选值

item_types 用于指定需要统计的结果类型。常见值：

organic：自然搜索结果
paid：付费搜索结果
featured_snippet：精选摘要
local_pack：本地结果

筛选条件

筛选条件采用数组表示，可使用以下运算符：

<、<=、>、>=、=、<>、in、not_in

多个条件示例：

json

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

也可以组合多个逻辑层级：

json

[
  [
    ["metrics.organic.pos_1", ">", 0],
    "or",
    ["metrics.organic.pos_2_3", ">", 0]
  ],
  "and",
  ["metrics.organic.etv", ">", 100]
]

排序规则

排序规则使用与筛选条件相同的字段表达式，并追加排序方向：

json

[
  "metrics.organic.etv,desc",
  "page_address,asc"
]

asc：升序
desc：降序

最多可设置 3 条排序规则。若 item_types 中 organic 以外的类型，结果默认 item_types 数组中的第一个类型排序。

请求示例

cURL

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/dataforseo_labs/relevant_pages/live" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "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
    }
  ]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/dataforseo_labs/relevant_pages/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)
data = response.json()

if data.get("status_code") == 20000:
    print(data)
else:
    print(
        f"请求失败，状态码：{data.get('status_code')}，"
        f"消息：{data.get('status_message')}"
    )

TypeScript

typescript

import axios from "axios";

const response = await axios.post(
  "https://api.seermartech.cn/v3/dataforseo_labs/relevant_pages/live",
  [
    {
      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,
    },
  ],
  {
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
  }
);

console.log(response.data);

响应结构

接口返回 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	请求中提交的任务参数。若请求 `tag`，该值也会返回在此对象中。
`result`	array	任务结果数组。

`result` 字段

字段	类型	说明
`target`	string	请求中的目标域名。
`location_code`	integer \| null	请求中的地区代码。无对应数据时为 `null`。
`language_code`	string \| null	请求中的语言代码。无对应数据时为 `null`。
`total_count`	integer	数据库中与请求条件匹的结果总数。
`items_count`	integer	本次返回的页面数量。
`items`	array	页面及指标数据。

页面结果字段

页面基础字段

字段	类型	说明
`page_address`	string	页面的绝对 URL。
`metrics`	object	页面排名与流量指标，不同搜索结果类型的统计对象。

metrics 可能以下对象：

organic：自然搜索数据
paid：付费搜索数据
featured_snippet：精选摘要数据
local_pack：本地结果数据

搜索结果类型指标

以下字段结构适用于 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）估算，计算方式为搜索量与 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` 对象

metrics.organic 表示页面在自然搜索结果中的排名与流量数据。

：

etv 表示页面的预估自然搜索月流量；
impressions_etv 表示基于展示次数估算的自然搜索月流量；
count 表示该页面的自然搜索结果数量；
estimated_paid_traffic_cost 表示通过付费搜索获取相同自然流量规模的预估月成本。

`paid` 对象

metrics.paid 表示页面在付费搜索结果中的排名与流量数据。

：

etv 表示页面的预估付费搜索月流量；
impressions_etv 表示基于展示次数估算的付费搜索月流量；
count 表示该页面的付费搜索结果数量；
estimated_paid_traffic_cost 表示基于 etv 和每次点击费用（CPC）估算的月度搜索广告成本。

`featured_snippet` 对象

metrics.featured_snippet 表示页面在搜索结果精选摘要中的排名与流量数据。

：

pos_1 至 pos_91_100 表示页面在精选摘要结果中的排名区间分布；
etv 表示精选摘要带来的预估月流量；
impressions_etv 表示基于展示次数估算的月流量；
count 表示该页面的精选摘要结果数量；
estimated_paid_traffic_cost 表示通过付费搜索获取相同流量规模的预估月成本；
is_new、is_up、is_down、is_lost 表示精选摘要排名的新增、上升、下降和丢失数量。

`local_pack` 对象

metrics.local_pack 表示页面在搜索结果本地结果中的排名与流量数据。

：

pos_1 至 pos_91_100 表示页面在本地结果中的排名区间分布；
etv 表示本地结果带来的预估月流量；
impressions_etv 表示基于展示次数估算的月流量；
count 表示该页面的本地结果数量；
estimated_paid_traffic_cost 表示通过付费搜索获取相同流量规模的预估月成本；
is_new、is_up、is_down、is_lost 表示本地结果排名的新增、上升、下降和丢失数量。

响应示例

json

{
  "version": "0.1.20210818",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.2370 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.2200 sec.",
      "cost": 0.0105,
      "result_count": 1,
      "path": [
        "v3",
        "dataforseo_labs",
        "relevant_pages",
        "live"
      ],
      "data": {
        "api": "dataforseo_labs",
        "function": "relevant_pages",
        "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": 125,
          "items_count": 1,
          "items": [
            {
              "page_address": "https://example.com/page",
              "metrics": {
                "organic": {
                  "pos_1": 2,
                  "pos_2_3": 5,
                  "pos_4_10": 18,
                  "pos_11_20": 24,
                  "pos_21_30": 16,
                  "pos_31_40": 11,
                  "pos_41_50": 8,
                  "pos_51_60": 6,
                  "pos_61_70": 4,
                  "pos_71_80": 3,
                  "pos_81_90": 2,
                  "pos_91_100": 1,
                  "etv": 1250.5,
                  "impressions_etv": 1480.2,
                  "count": 100,
                  "estimated_paid_traffic_cost": 820.4,
                  "is_new": 3,
                  "is_up": 7,
                  "is_down": 2,
                  "is_lost": 1
                }
              }
            }
          ]
        }
      ]
    }
  ]
}

错误处理

请同时检查以下状态字段：

顶层 status_code 与 status_message
每个任务的 status_code 与 status_message
顶层 tasks_error

状态码为 20000 通常表示请求成功。建议在客户端实现重试、时、部分任务失败和空结果等异常的处理逻辑。

实用场景

定位高价值落地页：按自然排名和 etv 筛选页面，识别能够带来最多搜索流量的资产，优化运营优级。
发现排名提升机会：筛选 pos_11_20 或 pos_21_30 大于零的页面，优改进接近首页的和页面。
监控竞争域名页面表现：比较多个域名的页面、排名分布和预估流量，评估竞争对手的布局。
识别流量损失页面：结合 is_down 和 is_lost 定位排名下降或丢失的页面，及时开展更新和技术排查。
评估搜索结果类型价值：通过 paid、featured_snippet 和 local_pack 指标，判断页面在广告、精选摘要及本地搜索场景中的增长机会。

页面（Legacy） ​

请求信息 ​

计费说明 ​

请求参数 ​

任务级参数 ​

地区与语言 ​

item_types 可选值 ​

筛选条件 ​

排序规则 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应结构 ​

顶层字段 ​

任务字段 ​

result 字段 ​

页面结果字段 ​

页面基础字段 ​

搜索结果类型指标 ​

排名分布字段 ​

流量与变化字段 ​

organic 对象 ​

paid 对象 ​

featured_snippet 对象 ​

local_pack 对象 ​

响应示例 ​

错误处理 ​

实用场景 ​

页面（Legacy）

请求信息

计费说明

请求参数

任务级参数

地区与语言

`item_types` 可选值

筛选条件

排序规则

请求示例

cURL

Python

TypeScript

响应结构

顶层字段

任务字段

`result` 字段

页面结果字段

页面基础字段

搜索结果类型指标

排名分布字段

流量与变化字段

`organic` 对象

`paid` 对象

`featured_snippet` 对象

`local_pack` 对象

响应示例

错误处理

实用场景