页面交集：Google 实时接口

POST /v3/dataforseo_labs/google/page_intersection/live

接口说明

POST /v3/dataforseo_labs/google/page_intersection/live

本接口用于查询多个指定页面在 Google 同一搜索结果页中排名的，并返回每个的搜索量、竞争度、每次点击费用（CPC）等指标。同时，接口还会返回指定页面对应的 SERP素、预估流量及预估付费流量成本。

本接口支持以下 SERP 结果类型：

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

查询逻辑

查询多个页面排名的

设置 pages 对象，即可查询多个页面排名的。

查询竞争对手排名但目标页面未排名的

同时设置 pages 和 exclude_pages：

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

默认，返回 pages 中任意页面排名、但 exclude_pages 中页面未排名的。

如需要求 pages 中所有页面在同一 SERP 中排名，可将 intersection_mode 设置为 intersect。

数据更新

数据每周更新。最新更新时间可通过以下接口查询：

GET /v3/dataforseo_labs/status

> 当交集数量 1,000 万时，本接口不会返回结果。

请求信息

请求方法：POST
请求路径：/v3/dataforseo_labs/google/page_intersection/live
请求格式：JSON（UTF-8）
请求体格式：JSON 数组
单次 Live 请求：最多 1 个任务
接口调用频率：最多 2,000 次/分钟
最大并发请求数：30

每次请求会产生费用。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数

请求体中的每个数组代表一个任务。

基础参数

参数	类型	填	说明
`pages`	object	是	需要分析的页面 URL。最多设置 20 个页面，使用 `http://` 或 `https://` 的绝对 URL。对象键名通常使用 `"1"` 至 `"20"`。
`exclude_pages`	array	否	需要排除的页面 URL，最多 10 个。支持使用通符。
`location_name`	string	条件填	地区名。未设置 `location_code` 时填。
`location_code`	integer	条件填	地区代码。未设置 `location_name` 时填。
`language_name`	string	条件填	语言名。未设置 `language_code` 时填。
`language_code`	string	条件填	语言代码。未设置 `language_name` 时填。
`item_types`	array	否	要纳结果的 SERP素类型。
`limit`	integer	否	最多返回的数量。默认值为 `100`，最大值为 `1000`。
`offset`	integer	否	结果偏移量，默认值为 `0`。例如设置为 `10` 时，将跳过结果数组中的前 10 个。
`include_subdomains`	boolean	否	是否在查询中子域名。设置为 `false` 时忽略子域名，默认值为 `true`。
`intersection_mode`	string	否	合并模式，可选值为 `union`、`intersect`。
`include_serp_info`	boolean	否	是否返回每个的 SERP 信息。默认值为 `false`。
`include_clickstream_data`	boolean	否	是否返回基于点击流数据计算的指标。默认值为 `false`。启用后将返回点击流字段，且请求费用按双倍计算。
`ignore_synonyms`	boolean	否	是否忽略高度相似的。设置为 `true` 时返回核心，默认值为 `false`。
`filters`	array	否	结果过滤条件，最多 8 个过滤器。
`order_by`	array	否	结果排序规则，最多设置 3 条。
`tag`	string	否	用户自定义任务标识，最长 255 个字符。该值会原样返回在响应的 `data` 对象中。

`pages` 参数

示例：

json

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

URL 匹规则：

"https://example.com"：匹精确 URL。
"https://example.com/eng/*"：匹该页面及所有以 /eng/ 开头的 URL，例如：
- https://example.com/eng/index.html
- https://example.com/eng/help/

通符放在 URL 末尾的斜杠之后。例如：

正确：https://example.com/*
不建议：https://example.com*

`exclude_pages` 参数

示例：

json

{
  "exclude_pages": [
    "https://competitor.example.com/*",
    "https://example.org/resources/*"
  ]
}

设置该参数后：

union 模式：返回 pages 中任意 URL 排名、但 exclude_pages 中 URL 未排名的。
intersect 模式：返回 pages 中所有 URL 在同一 SERP 中排名、且 exclude_pages 中 URL 未排名的。

如果未设置 exclude_pages，默认使用 intersect 模式；如果设置了 exclude_pages，默认使用 union 模式。

地区与语言

location_name 与 location_code 至少填写一个；language_name 与 language_code 至少填写一个。

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

GET /v3/dataforseo_labs/locations_and_languages

示例：

json

{
  "location_name": "United Kingdom",
  "location_code": 2840,
  "language_name": "English",
  "language_code": "en"
}

`item_types` 可选值

常用值：

text

organic
paid
local_pack
featured_snippet

`intersection_mode`

值	说明
`union`	基于 `pages` 中任意 URL 排名的返回结果。
`intersect`	返回 `pages` 中所有 URL 在同一 SERP 中排名的。

`filters`

过滤器格式为：

json

[
  ["keyword_info.search_volume", ">", 1000],
  "and",
  ["intersection_result.1.rank_absolute", "<=", 20]
]

支持的运算符：

text

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

like、not_like、ilike、not_ilike 支持使用 % 匹任意长度的字符串。

如果要过滤 intersection_result 数组中的字段，在字段路径中指定对应页面编号。例如：

json

[
  ["intersection_result.1.rank_absolute", "<=", 10]
]

表示筛选第一个页面排名在前 10 的结果。

`order_by`

排序规则使用字段名和排序方向，例如：

json

[
  "keyword_info.search_volume,desc",
  "keyword_info.keyword_difficulty,asc"
]

排序方向：

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://www.apple.com/*",
        "2": "https://www.microsoft.com/*"
      },
      "location_name": "United States",
      "language_name": "English",
      "limit": 3,
      "include_serp_info": true
    }
  ]'

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",
}

payload = [
    {
        "pages": {
            "1": "https://www.apple.com/*",
            "2": "https://www.microsoft.com/*",
        },
        "location_name": "United States",
        "language_name": "English",
        "limit": 3,
    }
]

response = requests.post(url, headers=headers, json=payload, timeout=60)
response.raise_for_status()

result = response.json()

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

TypeScript

typescript

import axios from "axios";

const payload = [
  {
    pages: {
      "1": "https://www.apple.com/*",
      "2": "https://www.microsoft.com/*",
    },
    location_name: "United States",
    language_name: "English",
    limit: 3,
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/dataforseo_labs/google/page_intersection/live",
    payload,
    {
      headers: {
        Authorization: "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
      },
    }
  )
  .then((response) => {
    // 处理接口结果
    console.log(response.data);
  })
  .catch((error) => {
    console.error("请求失败：", error.response?.data || error.message);
  });

响应结构

接口返回 JSON 对象 tasks 任务数组。

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": [
    {
      "id": "任务 UUID",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "27.7362 sec.",
      "cost": 0.0103,
      "result_count": 1,
      "data": {
        "api": "dataforseo_labs",
        "function": "page_intersection",
        "se_type": "google",
        "pages": {
          "1": "https://example.com",
          "2": "https://example.org/*"
        },
        "language_name": "English",
        "location_code": 2840,
        "include_serp_info": true,
        "limit": 3
      },
      "result": [
        {
          "se_type": "google",
          "keyword_data": {
            "se_type": "google",
            "keyword": "example keyword",
            "location_code": 2840,
            "language_code": "en",
            "keyword_info": {
              "search_volume": 246000,
              "competition": 0.01,
              "competition_level": "LOW",
              "cpc": 4.95,
              "low_top_of_page_bid": 1.69,
              "high_top_of_page_bid": 6.33
            }
          },
          "intersection_result": {
            "1": {
              "type": "organic",
              "rank_group": 10,
              "rank_absolute": 11,
              "domain": "example.com",
              "title": "示例页面",
              "url": "https://example.com/",
              "etv": 1155
            },
            "2": {
              "type": "organic",
              "rank_group": 8,
              "rank_absolute": 9,
              "domain": "example.org",
              "title": "示例页面",
              "url": "https://example.org/",
              "etv": 980
            }
          }
        }
      ]
    }
  ]
}

响应字段

顶层字段

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	整体状态码。成功通常为 `20000`。
`status_message`	string	整体状态说明。
`time`	string	请求执行耗时，例如 `27.7362 sec.`。
`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	请求路径。
`data`	object	请求中提交的任务参数。
`result`	array	任务结果数组。

错误码可参考本平台错误码文档。

`result` 字段

字段	类型	说明
`se_type`	string	搜索引擎类型，通常为 `google`。
`pages`	object	请求中指定的页面。
`exclude_pages`	array	请求中指定的排除页面。
`location_code`	integer	地区代码。
`language_code`	string	语言代码。
`total_count`	integer	数据库中与请求条件的结果总数。
`items_count`	integer	`items` 数组中返回的结果数量。
`items`	array	、SERP素及指标。

`items` 字段

字段	类型	说明
`se_type`	string	搜索引擎类型。
`keyword_data`	object	返回的数据。
`intersection_result`	object	指定页面在该下的 SERP 排名数据。对象键名与 `pages` 中的页面编号对应，最多 `1` 至 `20`。

`keyword_data` 字段

字段	类型	说明
`se_type`	string	搜索引擎类型。
`keyword`	string	返回的。
`location_code`	integer	地区代码。
`language_code`	string	语言代码。
`keyword_info`	object	基础指标。
`clickstream_keyword_info`	object/null	点击流指标。在 `include_clickstream_data=true` 时返回。
`keyword_properties`	object	属性。
`serp_info`	object/null	SERP 信息。在 `include_serp_info=true` 且存在对应数据时返回。
`avg_backlinks_info`	object	排名前 10 的自然结果页面的平均外链指标。
`search_intent_info`	object	搜索意图信息。
`keyword_info_normalized_with_bing`	object/null	使用 Bing 搜索量归一化后的数据。
`keyword_info_normalized_with_clickstream`	object/null	使用点击流数据归一化后的数据。

`keyword_info`

字段	类型	说明
`se_type`	string	搜索引擎类型。
`last_updated_time`	string	数据更新时间，UTC 格式：`yyyy-mm-dd hh-mm-ss +00:00`。
`competition`	float	相对竞争度，取值范围为 `0` 至 `1`，数据基于广告平台统计。
`competition_level`	string/null	付费 SERP 竞争等级，可选值：`LOW`、`MEDIUM`、`HIGH`。未知时为 `null`。
`cpc`	float	历史平均每次点击费用。
`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_searches 中的字段：

字段	类型	说明
`year`	integer	年份。
`month`	integer	月份。
`search_volume`	integer	当月搜索量。

search_volume_trend 中的字段：

字段	类型	说明
`monthly`	integer	相比上月的搜索量变化百分比。
`quarterly`	integer	相比上季度的搜索量变化百分比。
`yearly`	integer	相比上一年的搜索量变化百分比。

`keyword_properties`

字段	类型	说明
`se_type`	string	搜索引擎类型。
`core_keyword`	string/null	同义词聚类中的核心。
`synonym_clustering_algorithm`	string/null	同义词识别算法：`keyword_metrics` 或 `text_processing`。
`keyword_difficulty`	integer	难度，取值范围为 `0` 至 `100`，表示自然搜索前 10 名的难度。
`detected_language`	string	系统识别出的语言。
`is_another_language`	boolean	识别出的语言是否与请求指定语言不同。

`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	点击流搜索量趋势。

gender_distribution 字段：

female：点击流数据集中的女性用户数。
male：点击流数据集中的男性用户数。

age_distribution 字段：

18-24
25-34
35-44
45-54
55-64

以上字段表示对应年龄段的用户数。

`serp_info`

当未设置 include_serp_info=true，或数据库中没有该的 SERP 数据时，serp_info 为 null。

字段	类型	说明
`se_type`	string	搜索引擎类型。
`check_url`	string	可直接访问的搜索结果 URL，可用于核验结果。
`serp_item_types`	array	SERP 中检测到的结果类型。
`se_results_count`	integer/string	搜索结果数量。
`last_updated_time`	string	SERP 数据更新时间。
`previous_updated_time`	string	上一次 SERP 数据更新时间。

serp_item_types 可能：

text

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

结果数据针对以下四类 SERP素返回：

text

organic
paid
featured_snippet
local_pack

`avg_backlinks_info`

表示该自然排名前 10 个页面的平均外链与排名指标。

字段	类型	说明
`se_type`	string	搜索引擎类型。
`backlinks`	float	平均反向链接数。
`dofollow`	float	平均 Dofollow 链接数。
`referring_pages`	float	平均引用页面数。
`referring_domains`	float	平均引用域名数。
`referring_main_domains`	float	平均引用主域名数。
`rank`	float	平均页面排名。
`main_domain_rank`	float	平均主域名排名。
`last_updated_time`	string	外链数据更新时间。

`search_intent_info`

字段	类型	说明
`se_type`	string	搜索引擎类型，通常为 `google`。
`main_intent`	string	主要搜索意图：`informational`、`navigational`、`commercial`、`transactional`。
`foreign_intent`	array/null	补搜索意图。
`last_updated_time`	string	搜索意图数据更新时间。

归一化数据

keyword_info_normalized_with_bing 和 keyword_info_normalized_with_clickstream 结构相同：

字段	类型	说明
`last_updated_time`	string	数据集更新时间。
`search_volume`	integer	当前搜索量。
`is_normalized`	boolean	是否已使用对应数据进行归一化。
`monthly_searches`	array	月度搜索量数组。

`intersection_result` 字段

intersection_result 按 pages 中的页面编号返回数据，例如：

json

{
  "intersection_result": {
    "1": {
      "type": "organic",
      "rank_absolute": 5
    },
    "2": {
      "type": "featured_snippet",
      "rank_absolute": 1
    }
  }
}

每个页面编号下可能返回以下 SERP 类型：

organic
paid
local_pack
featured_snippet

通用 SERP 字段

自然结果、付费结果、本地和精选摘要通常以下字段：

字段	类型	说明
`se_type`	string	搜索引擎类型。
`type`	string	SERP素类型。
`rank_group`	integer	同类型 SERP素中的排名。不同类型不会计该排名。
`rank_absolute`	integer	在 SERP素中的绝对排名。
`position`	string	素在 SERP 中的对齐位置：`left` 或 `right`。
`xpath`	string	SERP素的 XPath。
`domain`	string	SERP 中显示的域名或子域名。
`title`	string	搜索结果标题。
`description`	string	搜索结果描述。
`url`	string	URL。
`breadcrumb`	string	面屑路径。
`main_domain`	string	主域名。
`relative_url`	string	相对 URL。
`highlighted`	array/null	描述中加粗显示的。
`etv`	float	预估流量，通常按点击率与搜索量计算。
`estimated_paid_traffic_cost`	float/object	将自然流量转化为付费流量的预估成本。
`clickstream_etv`	integer/null	基于点击流数据估算的流量。在 `include_clickstream_data=true` 时返回。
`rank_changes`	object	相较上次更新时间的排名变化。
`backlinks_info`	object	排名页面的外链信息。
`rank_info`	object	页面及主域名排名信息。

`organic` 自然结果

字段	类型	说明
`type`	string	固定为 `organic`。
`website_name`	string	网站名称。
`is_image`	boolean	是否图片。
`is_video`	boolean	是否视频。
`is_featured_snippet`	boolean	是否为精选摘要。
`is_malicious`	boolean	是否被标记为恶意结果。
`pre_snippet`	string/null	描述前附加的信息。
`extended_snippet`	string/null	描述后附加的信息。
`amp_version`	boolean	是否提供 AMP 版本。
`rating`	object/null	评分信息。
`links`	array/null	站点链接。
`about_this_result`	object/null	“此结果”信息。

`paid` 付费结果

字段	类型	说明
`type`	string	固定为 `paid`。
`domain`	string	广告结果中的域名。
`breadcrumb`	string	广告结果的面屑。
`url`	string	广告目标 URL。
`extra`	array	结果附加信息。
`description_rows`	array/null	扩展描述。
`links`	array/null	广告站点链接。

`local_pack` 本地结果

字段	类型	说明
`type`	string	固定为 `local_pack`。
`phone`	string	电话号码。
`is_paid`	boolean	是否为广告结果。
`rating`	object/null	商家评分。

`featured_snippet` 精选摘要

字段	类型	说明
`type`	string	固定为 `featured_snippet`。
`featured_title`	string	精选摘要来源页面标题。
`table`	array/null	精选摘要中的表格数据。
`table_header`	array	表格列名。
`table_content`	array	表格，每个代表表格中的一行。
`about_this_result`	object/null	“此结果”信息。

`rating`

字段	类型	说明
`rating_type`	string	评分类型：`Max5`、`Percents`、`CustomMax`。
`value`	integer	评分值。
`votes_count`	integer	评价数量。
`rating_max`	integer	当前评分类型的最大值。

`links`

站点链接或广告附加链接。没有链接时为 null。

字段	类型	说明
`type`	string	链接类型，通常为 `link_element` 或 `ad_link_element`。
`title`	string	链接标题。
`description`	string/object	链接描述。
`url`	string	链接 URL。
`main_domain`	string	主域名。
`relative_url`	string	相对 URL。

流量与广告价值字段

字段	类型	说明
`etv`	float	预估月流量，通常按点击率 × 搜索量计算。
`estimated_paid_traffic_cost`	float	通过广告获取相同规模流量的预估月成本，通常按自然流量预估值 × CPC 计算。
`clickstream_etv`	integer	基于点击流搜索量估算的流量，只有在 `include_clickstream_data=true` 时返回。

`rank_changes`

字段	类型	说明
`previous_rank_absolute`	integer/null	上一次检查时的绝对排名。新出现的为 `null`。
`is_new`	boolean	上一次采集的 SERP 中是否不存在该。
`is_up`	boolean	排名是否提升。
`is_down`	boolean	排名是否下降。

`backlinks_info`

字段	类型	说明
`referring_domains`	integer	引用域名数，子域名按独立域名计数。
`referring_main_domains`	integer	引用主域名数。
`referring_pages`	integer	指向该页面的引用页面数。
`dofollow`	integer	Dofollow 链接数。
`backlinks`	integer	反向链接总数 Dofollow 和 Nofollow 链接。
`time_update`	string	外链数据更新时间。

`rank_info`

字段	类型	说明
`page_rank`	integer	页面排名指标，基于链接数据库中的节点排名方法计算。
`main_domain_rank`	integer	主域名排名指标。

`about_this_result`

字段	类型	说明
`type`	string	固定为 `about_this_result_element`。
`url`	string	结果 URL。
`source`	string	附加信息来源。
`source_info`	string	网站的补说明。
`source_url`	string	来源信息的完整 URL。
`language`	string	结果语言。
`location`	string	结果适用地区。
`search_terms`	array	结果中匹的搜索词。
`related_terms`	array	结果中出现的搜索词。

注意事项

pages 至少需要提供一个页面，最多支持 20 个页面。
exclude_pages 最多支持 10 个页面。
地区参数至少提供 location_name 或 location_code 之一。
语言参数至少提供 language_name 或 language_code 之一。
include_clickstream_data=true 会返回额外点击流指标，并按双倍请求费用计费。
include_serp_info=true 才会返回 serp_info 数据。
建议根据 status_code 和 status_message 完善异常处理机制。
金额字段的扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

实用场景

挖掘竞品排名：对比多个竞争页面的交集，识别行业通用搜索需求并完善覆盖。
发现竞争对手独有：使用 exclude_pages 排除目标页面，定位竞争对手排名但自身未覆盖的，指导补和专题建设。
筛选高价值 SERP 机会：结合搜索量、CPC、难度和 SERP 类型，优选择流量潜力高且竞争可控的。
分析页面 SERP 展现差异：比较多个页面的自然结果、广告、本地和精选摘要排名，优化页面结构与 SERP 展现方式。
评估流量与外链门槛：结合 etv、estimated_paid_traffic_cost、backlinks_info 和 rank_info，估算获取自然流量所需的、外链及广告。

页面交集：Google 实时接口 ​

接口说明 ​

查询逻辑 ​

查询多个页面排名的 ​

查询竞争对手排名但目标页面未排名的 ​

数据更新 ​

请求信息 ​

请求参数 ​

基础参数 ​

pages 参数 ​

exclude_pages 参数 ​

地区与语言 ​

item_types 可选值 ​

intersection_mode ​

filters ​

order_by ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应结构 ​

响应字段 ​

顶层字段 ​

任务字段 ​

result 字段 ​

items 字段 ​

keyword_data 字段 ​

keyword_info ​

keyword_properties ​

clickstream_keyword_info ​

serp_info ​

页面交集：Google 实时接口

接口说明

查询逻辑

查询多个页面排名的

查询竞争对手排名但目标页面未排名的

数据更新

请求信息

请求参数

基础参数

`pages` 参数

`exclude_pages` 参数

地区与语言

`item_types` 可选值

`intersection_mode`

`filters`

`order_by`

请求示例

cURL

Python

TypeScript

响应结构

响应字段

顶层字段

任务字段

`result` 字段

`items` 字段

`keyword_data` 字段

`keyword_info`

`keyword_properties`

`clickstream_keyword_info`

`serp_info`