页面（Relevant Pages）

接口说明

该接口用于返回指定域名下各网页的排名与流量数据。你可以查看每个页面在自然搜索、付费搜索中的排名分布，以及对应的预估月流量。

数据更新频率：每周更新一次
最新更新时间：可通过 /v3/dataforseo_labs/status/ 查询
请求方式：POST
接口地址：https://api.seermartech.cn/v3/dataforseo_labs/google/relevant_pages/live

计费说明

该接口按请求次数计费。

由于原文未提供固定单价，无法直接换算人民币参考价。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

注意：当 include_clickstream_data=true 时，请求费用会变为基础价格的 2 倍。

调用限制

每分钟最多可发起 2000 次 API 调用
同时并发请求上限为 30

请求体格式

所有 POST 数据需使用 UTF-8 编码的 JSON，且请求体为 JSON 数组：

json

[
 {
 "target": "example.com"
 }
]

你可以在请求中控制：

返回结果数量
结果过滤
结果排序

请求参数

字段名	类型	说明
`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` 类型，结果将按数组中的第一个类型排序；且你不能按未在响应中的结果类型进行排序或过滤。
`include_clickstream_data`	boolean	可选。是否返回基于 clickstream 的指标数据。设为 `true` 后，响应中会 `clickstream_etv`、`clickstream_gender_distribution`、`clickstream_age_distribution`。默认值：`false`。开启后价格翻倍。
`limit`	integer	可选。返回页面的最大数量。默认值：`100`，最大值：`1000`
`offset`	integer	可选。结果偏移量。默认值：`0`。例如传 `10` 时，会跳过前 10 条结果并从后续页面开始返回。
`historical_serp_mode`	string	可选。数据筛选模式：`live` 表示当前仍有排名的 SERP；`lost` 表示历史上有排名、最近检查时已丢失排名的 SERP；`all` 表示两类都返回。默认值：`live`
`ignore_synonyms`	boolean	可选。是否忽略高度相似。设为 `true` 时返回核心，排除高相似词。默认值：`false`
`filters`	array	可选。结果过滤条件数组。最多支持 8 个过滤条件，条件之间可使用逻辑运算符 `and` / `or`。支持的比较运算符：`regex`、`not_regex`、`<`、`<=`、`>`、`>=`、`=`、`<>`、`in`、`not_in`。更多说明可参考 `/v3/dataforseo_labs/filters`
`order_by`	array	可选。结果排序规则。可使用与 `filters` 相同的字段路径；排序方式支持 `asc` 和 `desc`。单次请求最多支持 3 条排序规则。若 `item_types`含非 `organic` 类型，则结果会按 `item_types` 中第一个类型排序。
`tag`	string	可选。用户自定义任务标识，最长 255 个字符。可用于请求结果匹，响应中的 `data` 对象会原样返回该值。

过滤与排序说明

`filters` 示例

json

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

表示：返回“自然排名第 1 位不为 0”或“自然排名 2-3 位不为 0”的页面。

`order_by` 示例

json

[
 ["metrics.organic.etv", "desc"],
 ["metrics.organic.count", "desc"]
]

表示：按自然流量预估从高到低排序，再按自然结果覆盖数量从高到低排序。

请求示例

cURL

bash

curl --location --request POST "https://api.seermartech.cn/v3/dataforseo_labs/google/relevant_pages/live" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "target": "amazon.com",
 "language_name": "English",
 "location_code": 2840,
 "filters": [
 ["metrics.organic.pos_1", "<>", 0],
 "or",
 ["metrics.organic.pos_2_3", "<>", 0]
 ],
 "limit": 3
 }
]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/dataforseo_labs/google/relevant_pages/live"
payload = [
 {
 "target": "amazon.com",
 "location_name": "United States",
 "language_name": "English",
 "filters": [
 ["metrics.organic.pos_1", "<>", 0],
 "or",
 ["metrics.organic.pos_2_3", "<>", 0]
 ],
 "limit": 3
 }
]
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json)

TypeScript

typescript

import axios from "axios";

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

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/dataforseo_labs/google/relevant_pages/live",
 data: postArray,
 headers: {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 }
}).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[]` 字段

字段名	类型	说明
`se_type`	string	搜索引擎类型
`target`	string	请求中的目标域名
`location_code`	integer	请求中的地区编码；无数据时为 `null`
`language_code`	string	请求中的语言编码；无数据时为 `null`
`total_count`	integer	数据库中与本次请求的总结果数
`items_count`	integer	当前 `items` 数组返回的结果数
`items`	array	页面及对应指标

`items[]` 字段说明

每个 items素代表一个页面。

字段名	类型	说明
`se_type`	string	搜索引擎类型
`page_address`	string	页面绝对 URL
`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 与搜索量估算的月流量
`count`	integer	含该页面的该类 SERP 总数
`estimated_paid_traffic_cost`	float	预估流量成本，单位 USD。表示将当前流量通过付费投放获取的大致成本
`is_new`	integer	新增排名数量
`is_up`	integer	排名上升的数量
`is_down`	integer	排名下降的数量
`is_lost`	integer	丢失排名的数量

Clickstream 扩展字段

当请求中设置 include_clickstream_data=true 时返回：

字段名	类型	说明
`clickstream_etv`	integer	基于 clickstream 数据估算的流量
`clickstream_gender_distribution`	object	基于 clickstream 的性别分布
`clickstream_gender_distribution.female`	integer	女性用户数量
`clickstream_gender_distribution.male`	integer	男性用户数量
`clickstream_age_distribution`	object	基于 clickstream 的年龄分布
`clickstream_age_distribution.18-24`	integer	18-24 岁用户数量
`clickstream_age_distribution.25-34`	integer	25-34 岁用户数量
`clickstream_age_distribution.35-44`	integer	35-44 岁用户数量
`clickstream_age_distribution.45-54`	integer	45-54 岁用户数量
`clickstream_age_distribution.55-64`	integer	55-64 岁用户数量

各结果类型说明

`metrics.organic`

自然搜索中的排名与流量数据：

etv：页面自然搜索月预估流量
estimated_paid_traffic_cost：若将这部分自然流量改用广告获取，预计月成本

`metrics.paid`

付费搜索中的排名与流量数据：

etv：页面付费搜索月预估流量
estimated_paid_traffic_cost：页面当前付费月流量的预估成本

`metrics.featured_snippet`

精选摘要中的排名与流量数据。

`metrics.local_pack`

本地（Local Pack）结果中的排名与流量数据。

以上几类对象的字段结构一致，均使用前述“排名分布字段”“流量与变化字段”“Clickstream 扩展字段”。

响应示例

json

{
 "version": "0.1.20240514",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "4.1423 sec.",
 "cost": 0.0103,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "dataforseo_labs",
 "function": "relevant_pages",
 "se_type": "google",
 "target": "amazon.com",
 "language_name": "English",
 "location_code": 2840,
 "filters": [
 ["metrics.organic.pos_1", "<>", 0],
 "or",
 ["metrics.organic.pos_2_3", "<>", 0]
 ],
 "limit": 3
 },
 "result": [
 {
 "se_type": "google",
 "target": "amazon.com",
 "location_code": 2840,
 "language_code": "en",
 "total_count": 3,
 "items_count": 3,
 "items": [
 {
 "se_type": "google",
 "page_address": "https://www.amazon.com/example-page-1",
 "metrics": {
 "organic": {
 "pos_1": 15,
 "pos_2_3": 21,
 "pos_4_10": 35,
 "pos_11_20": 40,
 "pos_21_30": 22,
 "pos_31_40": 11,
 "pos_41_50": 5,
 "pos_51_60": 2,
 "pos_61_70": 1,
 "pos_71_80": 0,
 "pos_81_90": 0,
 "pos_91_100": 0,
 "etv": 12450.7,
 "count": 152,
 "estimated_paid_traffic_cost": 3850.12,
 "is_new": 6,
 "is_up": 23,
 "is_down": 9,
 "is_lost": 3
 }
 }
 }
 ]
 }
 ]
 }
 ]
}

错误处理

建议在接时同时处理以下两层状态：

顶层状态

status_code
status_message

任务级状态

tasks[].status_code
tasks[].status_message

完整错误码列表请参考 /v3/appendix/errors。

常见处理建议：

20000：请求成功
非 20000：根据状态码记录日志、告警或重试
tasks_error > 0：说明部分任务执行失败，需要逐个检查 tasks[]

使用建议

需要站页面盘点时，优使用较大的 limit 并合 offset 分页获取
需要查看当前仍有排名的页面时，使用 historical_serp_mode=live
需要找出已丢失排名的页面时，使用 historical_serp_mode=lost
若只分析核心词覆盖，可将 ignore_synonyms 设为 true
若用户画像与更贴近真实访问行为的流量估算，可开启 include_clickstream_data，但需注意价格翻倍

实用场景

识别高价值落地页：筛选 metrics.organic.etv 高、pos_1/pos_2_3 占比高的页面，快速定位自然流量核心资产。
排查流量下滑页面：结合 is_down 与 is_lost 找出排名下降或丢失的页面，更新与技术 SEO 修复。
评估页面商业价值：利用 estimated_paid_traffic_cost 判断页面自然流量替代广告投放的价值，支持 SEO 投优级排序。
分析不同搜索结果类型：通过 item_types 查看 organic、featured_snippet、local_pack 等不同结果位的页面表现，优化 SERP 占位策略。
挖掘地域与语言机会：按 location_code、language_code 细分页面表现，发现不同国家和语言市场中的增长空间。

页面（Relevant Pages） ​

接口说明 ​

计费说明 ​

调用限制 ​

请求体格式 ​

请求参数 ​

过滤与排序说明 ​

filters 示例 ​

order_by 示例 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应结构 ​

顶层字段 ​

tasks[] 字段 ​

result[] 字段 ​

items[] 字段说明 ​

metrics 指标结构 ​

通用排名分布字段 ​

通用流量与变化字段 ​

Clickstream 扩展字段 ​

各结果类型说明 ​

metrics.organic ​

metrics.paid ​

metrics.featured_snippet ​

metrics.local_pack ​

响应示例 ​

错误处理 ​

使用建议 ​

实用场景 ​

页面（Relevant Pages）

接口说明

计费说明

调用限制

请求体格式

请求参数

过滤与排序说明

`filters` 示例

`order_by` 示例

请求示例

cURL

Python

TypeScript

响应结构

顶层字段

`tasks[]` 字段

`result[]` 字段

`items[]` 字段说明

`metrics` 指标结构

通用排名分布字段

通用流量与变化字段

Clickstream 扩展字段

各结果类型说明

`metrics.organic`

`metrics.paid`

`metrics.featured_snippet`

`metrics.local_pack`

响应示例

错误处理

使用建议

实用场景