页面（旧版）

接口说明

注意：本平台 Labs API 的请求与响应结构已于 2022-03-19 更新，但本页描述的旧版接口仍继续容支持。新版本可参考 /v3/dataforseo_labs/google/relevant_pages/live/ 文档。

该接口用于获取指定域名下各网页的排名与流量数据。你可以查看每个页面在自然搜索、付费搜索，以及部分 SERP 结果类型中的排名分布和预估月流量。

请求方式

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

计费说明

该接口按请求计费。原文未提供固定单价，因此无法直接换算参考人民币价格。 扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求要求

请求体使用 UTF-8 编码的 JSON
POST 请求体格式为 JSON 数组：[{ ... }]
单分钟最多可发送 2000 次 API 调用
支持通过 limit 控制返回数量，并可结合 filters、order_by 进行筛选和排序

请求参数

顶层任务参数

字段名	类型	填	说明
`target`	string	是	目标网站域名。不要 `https://` 和 `www.`
`location_name`	string	否	地区名。使用该字段时无需再传 `location_code`。可通过 `/v3/dataforseo_labs/locations_and_languages` 查询可用地区；不传则返回所有可用地区的数据。示例：`United Kingdom`
`location_code`	integer	否	地区编码。使用该字段时无需再传 `location_name`。可通过 `/v3/dataforseo_labs/locations_and_languages` 查询。示例：`2840`
`language_name`	string	否	语言名。使用该字段时无需再传 `language_code`。可通过 `/v3/dataforseo_labs/locations_and_languages` 查询；不传则返回所有可用语言的数据。示例：`English`
`language_code`	string	否	语言编码。使用该字段时无需再传 `language_name`。可通过 `/v3/dataforseo_labs/locations_and_languages` 查询。示例：`en`
`item_types`	array	否	指定响应中的搜索结果类型。若数组中除 `organic` 之外的类型，结果将按数组中第一个类型排序。未的类型不能用于排序和过滤。
`limit`	integer	否	返回页面的最大数量。默认 `100`，最大 `1000`
`offset`	integer	否	结果偏移量。默认 `0`。例如传 `10` 表示跳过前 10 个页面，从后续页面开始返回
`filters`	array	否	结果过滤条件数组。最多可设置 8 个过滤条件，条件之间需使用逻辑运算符 `and` 或 `or` 连接
`order_by`	array	否	排序规则。可使用与 `filters` 相同的字段路径；排序方式为 `asc` 或 `desc`。单次请求最多设置 3 条排序规则
`tag`	string	否	自定义任务标识，最长 255 个字符。返回结果中的 `data` 对象会回传该值，便于请求结果对应

`filters` 说明

filters 支持以下运算符：

<
<=
>
>=
=
<>
in
not_in

条件之间使用 and / or 连接。过滤字段路径通常采用类似：

metrics.organic.pos_1
metrics.organic.pos_2_3
metrics.paid.etv

示例：

json

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

更多筛选规则可参考本平台 Labs Filters 对应文档。

`order_by` 说明

order_by 的字段写法与 filters 一致，格式为：

json

["字段路径,排序方式"]

例如：

json

["metrics.organic.etv,desc"]

说明：

asc：升序
desc：降序
最多支持 3 条排序规则
若 item_types 中非 organic 类型，则结果优按 item_types 中第一个类型排序

返回结果说明

接口返回 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	任务 ID，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	请求中的地区编码；无数据时为 `null`
`language_code`	string	请求中的语言编码；无数据时为 `null`
`total_count`	integer	数据库中与本次请求的总结果数
`items_count`	integer	`items` 数组中返回的结果数量
`items`	array	页面及指标数据

`items[]` 字段

字段名	类型	说明
`page_address`	string	页面的绝对 URL
`metrics`	object	该页面的排名与流量指标

`metrics` 字段说明

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	预估流量
`impressions_etv`	float	基于展示量计算的预估流量
`count`	integer	含该页面的对应类型 SERP 总数
`estimated_paid_traffic_cost`	float	预估流量价值/预估搜索流量成本，单位 USD
`is_new`	integer	新增排名数量
`is_up`	integer	排名上升的数量
`is_down`	integer	排名下降的数量
`is_lost`	integer	丢失排名的数量

各指标对象说明

`metrics.organic`

表示来自自然搜索的排名与流量数据。

补说明：

etv：页面的自然月预估流量，基于页面参与排名的 CTR 与搜索量计算
impressions_etv：基于展示量计算的自然月预估流量
estimated_paid_traffic_cost：将自然流量等量转化为付费搜索流量时的预估月成本

`metrics.paid`

表示来自付费搜索的排名与流量数据。

补说明：

etv：页面的付费月预估流量
impressions_etv：基于展示量计算的付费月预估流量
estimated_paid_traffic_cost：基于 etv 与 cpc 估算出的付费月流量成本

`metrics.featured_snippet`

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

补说明：

count：该页面的精选摘要结果数量
余排名区间、流量与变化字段含义同上

`metrics.local_pack`

表示页面在本地结果中的排名与流量数据。

补说明：

count：该页面的本地结果数量
余排名区间、流量与变化字段含义同上

请求示例

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",
 "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/relevant_pages/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, headers=headers, json=data)
print(response.json)

TypeScript

typescript

import axios from "axios";

const postArray = [
 {
 target: "example.com",
 location_code: 2840,
 language_name: "English",
 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/relevant_pages/live",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 },
 data: postArray
}).then((response) => {
 console.log(response.data);
}).catch((error) => {
 console.error(error);
});

响应示例

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": [
 {
 "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": 123,
 "items_count": 5,
 "items": [
 {
 "page_address": "https://example.com/page-1",
 "metrics": {
 "organic": {
 "pos_1": 12,
 "pos_2_3": 8,
 "pos_4_10": 20,
 "pos_11_20": 17,
 "pos_21_30": 9,
 "pos_31_40": 3,
 "pos_41_50": 1,
 "pos_51_60": 0,
 "pos_61_70": 0,
 "pos_71_80": 0,
 "pos_81_90": 0,
 "pos_91_100": 0,
 "etv": 1540.27,
 "impressions_etv": 1788.42,
 "count": 70,
 "estimated_paid_traffic_cost": 923.16,
 "is_new": 5,
 "is_up": 11,
 "is_down": 4,
 "is_lost": 2
 }
 }
 }
 ]
 }
 ]
 }
 ]
}

状态码与错误处理

顶层 status_code 表示整个请求的执行状态
tasks[].status_code 表示单个任务的执行状态
建议同时校验这两个层级的状态码，并为异常设计重试、告警和底逻辑
完整错误码列表可参考 /v3/appendix/errors

常见处理建议：

顶层非成功：直接记录请求失败
顶层成功但任务失败：逐个检查 tasks[].status_code
result 为空：通常表示当前筛选条件下无匹数据
分页拉取时：结合 limit 和 offset 循环获取完整结果集

使用建议

查询单一国家/语言市场时，优指定 location_code 和 language_code，返回量数据造成结果过大
如果只自然排名页面，可只保留 organic 过滤字段
对高价值落地页排序时，可优按 metrics.organic.etv,desc 或 metrics.paid.estimated_paid_traffic_cost,desc
若需要追踪页面排名变化，可重点 is_new、is_up、is_down、is_lost

实用场景

识别高流量落地页：按 metrics.organic.etv 排序，快速找出为站点贡献自然流量最多的页面，指导扩展与链强化。
筛选首页排名页面：通过 metrics.organic.pos_1、pos_2_3 等条件过滤，定位已前列的页面，优 CTR 优化和摘要改写。
评估 SEO 流量商业价值：结合 estimated_paid_traffic_cost 判断自然流量的广告替代成本， ROI 和预算分决策。
监控页面排名波动：基于 is_up、is_down、is_lost 识别近期波动明显的页面，及时排查算法波动、页面改版或竞争变化。
拆分自然与付费结构：同时查看 organic 与 paid 指标，分析某一页面在自然搜索和广告流量中的表现差异，优化投放与 SEO 协同策略。

页面（旧版） ​

接口说明 ​

请求方式 ​

计费说明 ​

请求要求 ​

请求参数 ​

顶层任务参数 ​

filters 说明 ​

order_by 说明 ​

返回结果说明 ​

顶层响应字段 ​

tasks[] 字段 ​

result[] 字段 ​

items[] 字段 ​

metrics 字段说明 ​

通用排名区间字段 ​

各指标对象说明 ​

metrics.organic ​

metrics.paid ​

metrics.featured_snippet ​

metrics.local_pack ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应示例 ​

状态码与错误处理 ​

使用建议 ​

实用场景 ​

页面（旧版）

接口说明

请求方式

计费说明

请求要求

请求参数

顶层任务参数

`filters` 说明

`order_by` 说明

返回结果说明

顶层响应字段

`tasks[]` 字段

`result[]` 字段

`items[]` 字段

`metrics` 字段说明

通用排名区间字段

各指标对象说明

`metrics.organic`

`metrics.paid`

`metrics.featured_snippet`

`metrics.local_pack`

请求示例

cURL

Python

TypeScript

响应示例

状态码与错误处理

使用建议

实用场景