页面交集查询

接口说明

通过本接口可以查询多个指定页面在同一搜索结果页（SERP）中排名的，并返回每个交集对应的搜索量、竞争度、平均点击价格（CPC）等指标。

除指标外，接口还会返回这些页面在搜索结果中的排名数据，以及预估流量与预估广告流量成本。本接口支持以下结果类型：

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

两种型用法

1）查找多个页面排名的

在 pages 对象中传多个页面 URL，即可返回这些 URL 在同一 SERP 中排名的交集。

2）查找竞争对手有排名、而你没有排名的

同时传 pages 和 exclude_pages：

pages：需要纳分析的页面
exclude_pages：需要排除的页面

返回结果为：pages 中页面有排名、而 exclude_pages 中页面没有排名的。

请求方式

POST https://api.seermartech.cn/v3/dataforseo_labs/google/page_intersection/live

计费说明

本接口按请求计费。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

启用 include_clickstream_data=true 后，请求价格会变为双倍。

说明：原始文档未提供固定单价，因此此处不展示人民币参考价。

调用限制

每分钟最多 2000 次 API 调用
同时并发请求上限为 30
POST 请求体为 UTF-8 编码的 JSON 数组格式：[{ ... }]

请求参数

顶层参数

字段	类型	说明
`pages`	object	填。目标页面 URL 集合，最多可传 20 个页面。键名通常使用 `"1"` 到 `"20"`。使用绝对 URL， `http://` 或 `https://`。如果只传 1 个页面，则返回该页面结果。支持使用 `*` 通符指定 URL 模式。
`exclude_pages`	array	可选。要排除的页面 URL，最多 10 个。若设置该字段，结果将返回 `pages` 中页面有排名而 `exclude_pages` 中页面无排名的。支持 `*` 通符。
`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	可选。指定响应中的搜索结果类型。
`limit`	integer	可选。返回数量上限。默认 `100`，最大 `1000`。
`offset`	integer	可选。结果偏移量，作用于返回的 `items` 数组。默认 `0`。例如传 `10` 表示跳过前 10 个结果。
`include_subdomains`	boolean	可选。是否子域名。默认 `true`；若设为 `false`，则忽略子域名。
`intersection_mode`	string	可选。控制对 `pages` 中多个 URL 的结果执行“并集”还是“交集”。可选值：`union`、`intersect`。详见下文。
`include_serp_info`	boolean	可选。是否返回每个对应的 `serp_info` 数据。默认 `false`。
`include_clickstream_data`	boolean	可选。是否返回基于点击流的指标。默认 `false`。启用后会额外返回 `clickstream_keyword_info`、`clickstream_etv`、`keyword_info_normalized_with_clickstream`、`keyword_info_normalized_with_bing`。
`ignore_synonyms`	boolean	可选。是否忽略高度相似。设为 `true` 时返回核心。默认 `false`。
`filters`	array	可选。结果过滤条件数组，最多支持 8 个过滤条件，可通过逻辑运算符组合。
`order_by`	array	可选。结果排序规则，最多支持 3 条。
`tag`	string	可选。用户自定义任务标识，最长 255 个字符，会原样出现在响应的 `data` 对象中。

`pages` 参数说明

pages 是一个对象，最多可传 20 个页面，例如：

json

"pages": {
 "1": "https://www.apple.com/mac/*",
 "2": "https://example.com/*",
 "3": "https://support.microsoft.com/"
}

通符规则

支持在 URL 尾部使用 * 通符：

"https://example.com/page"：匹精确 URL
"https://example.com/eng/*"：匹该路径及下所有 URL，如：
https://example.com/eng/index.html
https://example.com/eng/help/

注意：

通符放在 URL 末尾的 / 之后
不支持 https://example.com*
应写为 https://example.com/*

额外限制：

如果交集数量 1000 万，接口将不返回结果。

`exclude_pages` 与 `intersection_mode` 的

当指定 exclude_pages 时：

默认结果基于 union 模式，即只要 pages 中任意 URL 有排名即可纳候选
如果你同时设置 intersection_mode: "intersect"，则结果会变为：pages 中**** URL 均在同一 SERP 有排名，且 exclude_pages 中 URL 没有排名的

地区与语言

二选一提供：

location_name 或 location_code
language_name 或 language_code

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

/v3/dataforseo_labs/locations_and_languages

`item_types`

表示要纳分析的搜索结果类型。原文未给出默认值展示，但本接口支持并返回以下核心类型的排名数据：

organic
paid
featured_snippet
local_pack

`intersection_mode`

可选值：

union：基于 pages 中任意一个 URL 有排名的
intersect：基于 pages 中所有 URL 在同一 SERP 中都有排名的

默认逻辑：

传 pages 时，默认按 intersect
同时传 exclude_pages 时，默认按 union

`filters`

可用于按结果字段过滤，最多 8 个条件，条件之间可使用：

and
or

支持的比较运算符：

regex
not_regex
<
<=
>
>=
=
<>
in
not_in
ilike
not_ilike
like
not_like
match
not_match

like、not_like、ilike、not_ilike 支持 % 通任意长度字符串。

重要： 如果需要对 intersection_result 中某个指定页面的字段进行过滤，在字段路径中带上页面编号。

例如：

按第 1 个页面的排名过滤
返回第 3 个页面属于自然结果的记录

过滤字段路径需与 intersection_result.{页面编号}.{字段名} 对应。

更多过滤规则可参考 /v3/dataforseo_labs/filters。

`order_by`

排序字段与 filters 使用相同的字段路径定义。排序方向：

asc：升序
desc：降序

单次请求最多可设置 3 条排序规则。

请求示例

cURL

bash

curl --location --request POST "https://api.seermartech.cn/v3/dataforseo_labs/google/page_intersection/live" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "pages": {
 "1": "https://example.com/*",
 "2": "https://competitor.com/*"
 },
 "language_name": "English",
 "location_code": 2840,
 "limit": 3
 }
]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/dataforseo_labs/google/page_intersection/live"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
data = [
 {
 "pages": {
 "1": "https://example.com/*",
 "2": "https://competitor.com/*"
 },
 "location_name": "United States",
 "language_name": "English",
 "limit": 3
 }
]

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

TypeScript

typescript

import axios from "axios";

const postArray = [
 {
 pages: {
 "1": "https://example.com/*",
 "2": "https://competitor.com/*"
 },
 language_name: "English",
 location_code: 2840,
 limit: 3
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/dataforseo_labs/google/page_intersection/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 对象，顶层 tasks 数组。

顶层响应字段

字段	类型	说明
`version`	string	API 当前版本号
`status_code`	integer	通用状态码
`status_message`	string	通用状态信息
`time`	string	执行耗时，单位秒
`cost`	float	本次请求总费用，单位 USD
`tasks_count`	integer	`tasks` 数组中的任务数
`tasks_error`	integer	返回错误的任务数
`tasks`	array	任务数组

`tasks[]` 字段

字段	类型	说明
`id`	string	任务唯一标识，UUID 格式
`status_code`	integer	任务状态码
`status_message`	string	任务状态说明
`time`	string	任务执行耗时
`cost`	float	单个任务费用，单位 USD
`result_count`	integer	`result` 数组数量
`path`	array	请求路径
`data`	object	原请求参数回显
`result`	array	获取结果

`result[]` 字段

字段	类型	说明
`se_type`	string	搜索引擎类型
`pages`	object	请求中传的 `pages`
`exclude_pages`	array	请求中传的 `exclude_pages`
`location_code`	integer	地区编码
`language_code`	string	语言代码
`total_count`	integer	符合条件的总结果数
`items_count`	integer	当前 `items` 返回数量
`items`	array	及排名数据

`items[]` 结果字段说明

每个 items[] 代表一个结果，主要以下对象：

keyword_data：基础数据
intersection_result：每个页面在该下的 SERP 排名

`keyword_data`

字段	类型	说明
`se_type`	string	搜索引擎类型
`keyword`	string	返回的
`location_code`	integer	地区编码
`language_code`	string	语言代码
`keyword_info`	object	指标
`clickstream_keyword_info`	object / null	点击流指标，需开启 `include_clickstream_data`
`keyword_properties`	object	属性
`serp_info`	object / null	SERP 信息，需开启 `include_serp_info`
`avg_backlinks_info`	object	该 top10 自然结果的平均外链数据
`search_intent_info`	object	搜索意图信息
`keyword_info_normalized_with_bing`	object / null	基于 Bing 归一化的搜索量数据
`keyword_info_normalized_with_clickstream`	object / null	基于点击流归一化的搜索量数据

`keyword_info`

字段	类型	说明
`last_updated_time`	string	数据更新时间，UTC
`competition`	float	竞争度，取值 0 到 1
`competition_level`	string	付费竞争等级：`LOW`、`MEDIUM`、`HIGH`，未知时为 `null`
`cpc`	float	平均点击价格，单位 USD
`search_volume`	integer	平均月搜索量
`low_top_of_page_bid`	float	首页顶部广告低位出价
`high_top_of_page_bid`	float	首页顶部广告高位出价
`categories`	array	产品/服务分类
`monthly_searches`	array	近 12 个月月度搜索量
`search_volume_trend`	object	搜索量趋势变化， `monthly`、`quarterly`、`yearly`

`clickstream_keyword_info`

在 include_clickstream_data=true 时返回。

字段	类型	说明
`search_volume`	integer	基于点击流的月均搜索量
`last_updated_time`	string	点击流数据更新时间
`gender_distribution`	object	性别分布
`age_distribution`	object	年龄分布
`monthly_searches`	array	月度点击流搜索量
`search_volume_trend`	object	趋势变化

`keyword_properties`

字段	类型	说明
`core_keyword`	string	同义词聚类中的核心
`synonym_clustering_algorithm`	string	同义词识别算法：`keyword_metrics`、`text_processing`
`keyword_difficulty`	integer	难度，0-100
`detected_language`	string	系统识别的语言
`is_another_language`	boolean	识别语言是否与请求语言不同

`serp_info`

当 include_serp_info=false 或数据库无数据时，值为 null。

字段	类型	说明
`check_url`	string	对应搜索结果页直达链接
`serp_item_types`	array	该 SERP 中出现的结果类型
`se_results_count`	string	搜索结果数量
`last_updated_time`	string	最新 SERP 更新时间
`previous_updated_time`	string	上一次 SERP 更新时间

serp_item_types 可能：

answer_box, app, carousel, multi_carousel, featured_snippet, google_flights, google_reviews, images, jobs, knowledge_graph, local_pack, map, organic, paid, people_also_ask, related_searches, people_also_search, shopping, top_stories, twitter, video, events, mention_carousel, recipes, top_sights, scholarly_articles, popular_products, podcasts, questions_and_answers, find_results_on, stocks_box, ai_overview

注意：本接口返回排名的 organic、paid、featured_snippet、local_pack。

`avg_backlinks_info`

返回该前 10 个自然结果页面的平均外链概况：

backlinks
dofollow
referring_pages
referring_domains
referring_main_domains
rank
main_domain_rank
last_updated_time

`search_intent_info`

字段	类型	说明
`main_intent`	string	主搜索意图：`informational`、`navigational`、`commercial`、`transactional`
`foreign_intent`	array	补搜索意图
`last_updated_time`	string	数据更新时间

`intersection_result` 字段说明

intersection_result含该下，各个指定页面在 SERP 中命中的结果。

它会根据 pages 中传的页面编号返回对应对象，例如：

intersection_result.1
intersection_result.2
…
intersection_result.20

每个页面对象可能对应以下类型之一：

organic
paid
local_pack
featured_snippet

同时通常这些字段：

字段	类型	说明
`se_type`	string	搜索引擎类型
`type`	string	结果类型
`rank_group`	integer	同类型结果中的位置
`rank_absolute`	integer	SERP 绝对排名
`position`	string	展示位置：`left`、`right`
`xpath`	string	素 XPath
`etv`	float	预估流量
`estimated_paid_traffic_cost`	float	预估付费流量成本，单位 USD
`clickstream_etv`	integer	基于点击流的预估流量，需开启 `include_clickstream_data`
`rank_changes`	object	排名变化信息
`backlinks_info`	object	排名页面外链信息
`rank_info`	object	页面/主域 Rank 信息

`rank_changes`

字段	类型	说明
`previous_rank_absolute`	integer	上一次绝对排名，若为新结果则可能为 `null`
`is_new`	boolean	是否为新出现结果
`is_up`	boolean	排名是否上升
`is_down`	boolean	排名是否下降

`backlinks_info`

字段	类型	说明
`referring_domains`	integer	引荐域名数
`referring_main_domains`	integer	引荐主域数
`referring_pages`	integer	引荐页面数
`dofollow`	integer	dofollow 外链数
`backlinks`	integer	外链总数
`time_update`	string	外链数据更新时间

`rank_info`

字段	类型	说明
`page_rank`	integer	页面 Rank
`main_domain_rank`	integer	主域 Rank

各结果类型专属字段

1）`organic` 自然结果

除字段外，通常还：

domain
title
url
breadcrumb
website_name
is_image
is_video
is_featured_snippet
is_malicious
description
pre_snippet
extended_snippet
amp_version
rating
highlighted
links
about_this_result
main_domain
relative_url

说明：

rating：评分信息， rating_type、value、votes_count、rating_max
links：站点链接（sitelinks）
about_this_result：搜索引擎“此结果”面板信息

2）`paid` 付费结果

除字段外，通常还：

title
domain
description
breadcrumb
url
highlighted
extra
description_rows
links
main_domain
relative_url

3）`local_pack` 本地结果

除字段外，通常还：

title
description
domain
phone
url
is_paid
rating
main_domain
relative_url

4）`featured_snippet` 精选摘要

除字段外，通常还：

domain
title
featured_title
description
url
table
about_this_result
main_domain
relative_url

说明：

table：摘要中的表格， table_header 和 table_content
about_this_result：结果来源背景信息，可能 source、source_info、source_url、language、location、search_terms、related_terms

响应示例

json

{
 "version": "0.1.20240801",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "27.7362 sec.",
 "cost": 0.0103,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "dataforseo_labs",
 "function": "page_intersection",
 "se_type": "google",
 "pages": {
 "1": "https://forbes.com",
 "2": "https://cnn.com/*"
 },
 "language_name": "English",
 "location_code": 2840,
 "include_serp_info": true,
 "limit": 3
 },
 "result": [
 {
 "se_type": "google",
 "keyword_data": {
 "se_type": "google",
 "keyword": "newsletter weekly"
 },
 "intersection_result": {
 "1": {
 "se_type": "google",
 "type": "organic",
 "rank_absolute": 11,
 "url": "https://account.forbes.com/",
 "etv": 2779.800048828125
 },
 "2": {
 "se_type": "google",
 "type": "organic",
 "rank_absolute": 6,
 "url": "https://www.cnn.com/newsletters",
 "etv": 11537.400390625
 }
 }
 }
 ]
 }
 ]
}

错误处理

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

顶层 status_code
tasks[].status_code

常见成功状态：

20000：成功

完整错误码与状态信息请参考 /v3/appendix/errors。

使用建议

对比多个 URL 的排名词时，优只传 pages，并使用默认 intersect
做竞争差距分析时，搭 exclude_pages 使用
如需查看 SERP 特征分布，开启 include_serp_info
如需更接近真实用户行为的搜索量和流量估算，可开启 include_clickstream_data，但需注意费用翻倍
针对大结果集，使用 limit + offset 分页拉取

实用场景

挖掘竞品重合：比较多个竞品页面覆盖的，快速识别行业核心流量词池。
发现缺口：用 exclude_pages 排除自身页面，找出竞争对手覆盖而你未覆盖的，指导选题和专题页建设。
评估页面争夺强度：结合 keyword_difficulty、competition、avg_backlinks_info，判断交集的自然排名难度与投放价值。
识别 SERP 机会位：查看 intersection_result 中的 featured_snippet、local_pack、paid 等，判断某类更适合做自然优化还是投放。
监控页面排名波动：基于 rank_changes 跟踪多个页面在相同下的相对升降，快速发现页面更新、算法波动或竞品动作带来的影响。

页面交集查询 ​

接口说明 ​

两种型用法 ​

请求方式 ​

计费说明 ​

调用限制 ​

请求参数 ​

顶层参数 ​

pages 参数说明 ​

通符规则 ​

exclude_pages 与 intersection_mode 的 ​

地区与语言 ​

item_types ​

intersection_mode ​

filters ​

order_by ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应结构 ​

顶层响应字段 ​

tasks[] 字段 ​

result[] 字段 ​

items[] 结果字段说明 ​

keyword_data ​

keyword_info ​

clickstream_keyword_info ​

keyword_properties ​

serp_info ​

avg_backlinks_info ​

search_intent_info ​

页面交集查询

接口说明

两种型用法

请求方式

计费说明

调用限制

请求参数

顶层参数

`pages` 参数说明

通符规则

`exclude_pages` 与 `intersection_mode` 的

地区与语言

`item_types`

`intersection_mode`

`filters`

`order_by`

请求示例

cURL

Python

TypeScript

响应结构

顶层响应字段

`tasks[]` 字段

`result[]` 字段

`items[]` 结果字段说明

`keyword_data`

`keyword_info`

`clickstream_keyword_info`

`keyword_properties`

`serp_info`

`avg_backlinks_info`

`search_intent_info`