页面交集（旧版）

本接口使用 POST 方法，路径为：

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

> 本接口为旧版容接口。平台 API 已于 2022-03-19 更新请求和响应结构，但旧版仍可继续使用。新版本请参考 /v3/dataforseo_labs/google/page_intersection/live/。

接口说明

页面交集接口用于查询多个页面在相同搜索结果页（SERP）中排名的，并返回以下数据：

搜索量、竞争度和每次点击费用（CPC）
基于广告展示次数的预估数据
页面对应的 SERP素及排名
预估流量（ETV）
预估付费流量成本
自然结果、付费结果、本地结果和精选摘要数据

查询多个页面排名的

设置 pages 参数，即可查询指定页面排名的。

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

同时设置 pages 和 exclude_pages：

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

默认，设置 exclude_pages 后，结果基于 pages 中任意页面排名的。若要返回所有 pages 页面排名、且 exclude_pages 页面未排名的，请将 intersection_mode 设置为 intersect。

计费与限制

每次请求单独计费。
实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。
单个请求最多 20 个目标页面。
exclude_pages 最多 10 个页面。平台限流以认证说明中的 30/60/120 次/分钟规则为准。
当页面交集数量 1000 万时，本接口不会返回结果。
请求体使用 UTF-8 编码的 JSON 数组。

请求参数

请求体格式：

json

[
  {
    "pages": {
      "1": "https://example.com/blog/*",
      "2": "https://competitor.example/*"
    },
    "location_code": 2840,
    "language_code": "en",
    "limit": 100
  }
]

任务参数

参数	类型	填	说明
`pages`	object	是	目标页面集合，最多 20 个。键名应使用 `"1"` 至 `"20"`，值为 `http://` 或 `https://` 的绝对 URL。
`exclude_pages`	array	否	需要排除的页面，最多 10 个。支持通符。
`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	否	结果偏移量，默认 `0`。例如设置为 `10` 时，跳过前 10 个结果。
`include_subdomains`	boolean	否	是否将子域名纳搜索，默认 `true`；设置为 `false` 时忽略子域名。
`intersection_mode`	string	否	合并方式，可选 `union` 或 `intersect`。
`include_serp_info`	boolean	否	是否返回每个的 SERP 信息，默认 `false`。
`filters`	array	否	结果过滤条件，最多 8 个过滤器。
`order_by`	array	否	结果排序规则，最多 3 条。
`tag`	string	否	用户自定义任务标识，最多 255 个字符。响应中的 `data` 对象会原样返回该值。

URL 通符规则

支持使用 * 匹页面路径：

text

https://example.com

匹精确 URL。

text

https://example.com/eng/*

匹 example.com/eng/ 及下级 URL，例如：

https://example.com/eng/index.html
https://example.com/eng/help/

通符放在 URL 路径末尾的斜杠之后，不能直接放在域名后：

text

错误：https://example.com*
正确：https://example.com/*

`intersection_mode` 取值

值	说明
`union`	基于 `pages` 中任意页面排名的。
`intersect`	返回 `pages` 中所有页面在相同 SERP 中排名的。

使用方式：

指定 pages 时，默认使用 intersect。
同时指定 pages 和 exclude_pages 时，默认使用 union。
同时指定 exclude_pages 并将该参数设为 intersect，可查询所有目标页面排名、且排除页面未排名的。

`filters`

过滤器使用数组表达式，并需在条件之间指定逻辑运算符 and 或 or。

支持的比较运算符：

text

<、<=、>、>=、=、<>、in、not_in、like、not_like

like 和 not_like 支持 % 通符，可匹任意长度的字符串。

示例：

json

[
  {
    "pages": {
      "1": "https://example.com/*",
      "2": "https://competitor.example/*"
    },
    "location_code": 2840,
    "language_code": "en",
    "filters": [
      ["keyword_data.keyword", "like", "%seo%"],
      "and",
      ["keyword_data.keyword_info.search_volume", ">=", 100]
    ]
  }
]

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

text

intersection_result.1.rank_absolute
intersection_result.3.type

`order_by`

排序参数使用字段名和排序方向：

json

[
  "keyword_data.keyword_info.search_volume,desc"
]

排序方向：

asc：升序
desc：降序

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

地区与语言

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

GET https://api.seermartech.cn/v3/dataforseo_labs/locations_and_languages

可使用以下任一组合：

location_name 或 location_code
language_name 或 language_code

请求示例

curl

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/dataforseo_labs/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.example/*"
      },
      "location_name": "United States",
      "language_name": "English",
      "limit": 100,
      "include_serp_info": true
    }
  ]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/dataforseo_labs/page_intersection/live"

headers = {
    "Authorization": "Bearer smt_live_YOUR_KEY",
    "Content-Type": "application/json",
}

payload = [
    {
        "pages": {
            "1": "https://example.com/*",
            "2": "https://competitor.example/*",
        },
        "location_name": "United States",
        "language_name": "English",
        "limit": 100,
    }
]

response = requests.post(url, headers=headers, json=payload)
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://example.com/*",
      "2": "https://competitor.example/*",
    },
    location_name: "United States",
    language_name: "English",
    limit: 100,
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/dataforseo_labs/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 数组。

顶层字段

字段	类型	说明
`version`	string	API 当前版本。
`status_code`	integer	通用状态码。`20000` 表示请求成功。
`status_message`	string	通用状态信息。
`time`	string	请求执行耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务总数。
`tasks_error`	integer	执行失败的任务数量。
`tasks`	array	任务结果数组。

任务字段

字段	类型	说明
`id`	string	任务唯一标识，UUID 格式。
`status_code`	integer	任务状态码。
`status_message`	string	任务状态信息。
`time`	string	任务执行耗时。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`result_count`	integer	`result` 数组中的数量。
`path`	array	请求路径。
`data`	object	与请求中提交的任务参数基本一致。
`result`	array	查询结果数组。

`result` 字段

字段	类型	说明
`pages`	object	请求中指定的目标页面。
`exclude_pages`	array	请求中指定的排除页面。
`location_code`	integer	地区代码。
`language_code`	string	语言代码。
`total_count`	integer	数据库中符合条件的结果总数。
`items_count`	integer	`items` 数组中的结果数量。
`items`	array	、SERP素和数据。

`items` 字段

`keyword_data`

字段	类型	说明
`keyword`	string	返回的。
`location_code`	integer	地区代码。
`language_code`	string	语言代码。
`keyword_info`	object	统计信息。
`impressions_info`	object	广告展示次数数据。
`bing_keyword_info`	object	基于 Bing 广告数据的信息。
`serp_info`	object	SERP 数据；未请求或无数据时为 `null`。
`intersection_result`	object	每个目标页面对应的 SERP素数据。

`keyword_info`

字段	类型	说明
`last_updated_time`	string	数据更新时间，UTC 格式：`yyyy-mm-dd hh:mm:ss +00:00`。
`competition`	float	竞争度，取值范围 `0` 至 `1`。
`cpc`	float	历史平均每次点击费用。
`search_volume`	integer	Google 平均月搜索量。
`categories`	array	产品和服务分类。
`monthly_searches`	array	最近 12 个月的月度搜索量。

monthly_searches素字段：

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

`impressions_info`

展示次数数据使用最高出价 999 计算，用于降低账户级因素对结果的影响。该数据可作为搜索量的补参考。

字段	类型	说明
`last_updated_time`	string	展示次数数据更新时间。
`bid`	integer	最高 CPC 出价，接口通常返回 `999`。
`match_type`	string	匹类型：`exact`、`broad`、`phrase`。
`ad_position_min`	float	最低广告位置。
`ad_position_max`	float	最高广告位置。
`ad_position_average`	float	平均广告位置。
`cpc_min`	float	估算最低 CPC。
`cpc_max`	float	估算最高 CPC。
`cpc_average`	float	估算平均 CPC。
`daily_impressions_min`	float	估算最低日展示次数。
`daily_impressions_max`	float	估算最高日展示次数。
`daily_impressions_average`	float	估算平均日展示次数。
`daily_clicks_min`	float	估算最低日点击次数。
`daily_clicks_max`	float	估算最高日点击次数。
`daily_clicks_average`	float	估算平均日点击次数。
`daily_cost_min`	float	估算最低日广告成本。
`daily_cost_max`	float	估算最高日广告成本。
`daily_cost_average`	float	估算平均日广告成本。

，cpc_min、cpc_max 和 cpc_average 是基于 999 出价的估算值，并不代表 CPC。 CPC 应读取 keyword_info.cpc。

`bing_keyword_info`

Bing 数据覆盖部分地区和语言。

字段	类型	说明
`last_updated_time`	string	Bing 数据更新时间。
`search_volume`	integer	Bing 月搜索量。
`monthly_searches`	array	指定地区的月度 Bing 搜索量。

`serp_info`

字段	类型	说明
`check_url`	string	可直接访问的搜索结果 URL。
`serp_item_types`	array	SERP 中出现的结果类型。
`se_results_count`	string/integer	搜索结果数量。
`keyword_difficulty`	integer	难度，范围 `0` 至 `100`。
`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

详细结果针对以下类型返回：

text

organic、paid、featured_snippet、local_pack

`intersection_result`

intersection_result 按请求中 pages 的编号返回数据。例如：

json

{
  "intersection_result": {
    "1": {
      "type": "organic",
      "rank_group": 3,
      "rank_absolute": 5,
      "domain": "example.com",
      "title": "示例页面标题",
      "url": "https://example.com/page",
      "etv": 120.5,
      "impressions_etv": 98.2,
      "estimated_paid_traffic_cost": 350.6,
      "rank_changes": {
        "previous_rank_absolute": 8,
        "is_new": false,
        "is_up": true,
        "is_down": false
      }
    }
  }
}

每个页面编号对应一个 SERP素对象，编号范围为 "1" 至 "20"。

通用 SERP 字段

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

字段	类型	说明
`type`	string	SERP素类型。
`rank_group`	integer	同类型中的排名。
`rank_absolute`	integer	在整个 SERP 中的绝对排名。
`position`	string	素所在位置，可为 `left` 或 `right`。
`xpath`	string	SERP素的 XPath。
`domain`	string	SERP 中显示的域名或子域名。
`title`	string	结果标题。
`url`	string	结果 URL。
`breadcrumb`	string	面屑路径。
`description`	string	结果描述。
`highlighted`	array	描述中加粗显示的。
`main_domain`	string	主域名。
`relative_url`	string	相对 URL。
`etv`	float	预估自然月流量，通常按点击率乘以搜索量计算。
`impressions_etv`	float	基于展示次数计算的预估自然月流量。
`estimated_paid_traffic_cost`	float	将预估自然流量通过付费广告获取时的月度估算成本。
`rank_changes`	object	自上次更新时间以来的排名变化。

rank_changes 字段：

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

`organic` 自然结果字段

当 type 为 organic 时，还可能返回：

字段	类型	说明
`is_image`	boolean	是否图片。
`is_video`	boolean	是否视频。
`is_featured_snippet`	boolean	是否同时为精选摘要。
`is_malicious`	boolean	是否被标记为恶意结果。
`pre_snippet`	string	描述前的附加文本。
`extended_snippet`	string	描述后的附加文本。
`amp_version`	boolean	是否存在 AMP 版本。
`rating`	object/null	评分信息。
`links`	array/null	站点链接。

rating 对象：

字段	类型	说明
`rating_type`	string	评分类型：`Max5`、`Percents` 或 `CustomMax`。
`value`	integer	评分值。
`votes_count`	integer	评价数量。
`rating_max`	integer	评分上限。

links 中的站点链接：

字段	类型	说明
`type`	string	固定为 `link_element`。
`title`	string	链接标题。
`description`	string	链接描述。
`url`	string	站点链接 URL。
`main_domain`	string	主域名。
`relative_url`	string	相对 URL。

`paid` 付费结果字段

当 type 为 paid 时，还可能返回：

字段	类型	说明
`ad_aclk`	string	广告标识。
`extra`	array	广告附加信息。
`description_rows`	array/null	扩展描述行。
`links`	array/null	广告站点链接。

广告站点链接的字段：

字段	类型	说明
`type`	string	固定为 `ad_link_element`。
`title`	string	链接标题。
`description`	string	链接描述。
`url`	string	链接 URL。
`ad_aclk`	string	广告标识。
`main_domain`	string	主域名。
`relative_url`	string	相对 URL。

`local_pack` 本地结果字段

当 type 为 local_pack 时，还可能返回：

字段	类型	说明
`phone`	string	电话号码。
`is_paid`	boolean	是否为付费广告。
`rating`	object/null	本地结果评分。

`featured_snippet` 精选摘要字段

当 type 为 featured_snippet 时，还可能返回：

字段	类型	说明
`featured_title`	string	精选摘要来源页面标题。
`table`	array/null	摘要中的表格。
`table_header`	array	表格列名。
`table_content`	array	表格。
`about_this_result`	object	“此结果”信息。

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	搜索词。

响应示例

json

{
  "version": "0.1.20210430",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.5750 sec.",
  "cost": 0.0103,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.5700 sec.",
      "cost": 0.0103,
      "result_count": 1,
      "data": {
        "api": "dataforseo_labs",
        "function": "page_intersection",
        "pages": {
          "1": "https://example.com/*",
          "2": "https://competitor.example/*"
        },
        "location_code": 2840,
        "language_name": "English",
        "limit": 3
      },
      "result": [
        {
          "pages": {
            "1": "https://example.com/*",
            "2": "https://competitor.example/*"
          },
          "location_code": 2840,
          "language_code": "en",
          "total_count": 120,
          "items_count": 3,
          "items": [
            {
              "keyword_data": {
                "keyword": "seo software",
                "location_code": 2840,
                "language_code": "en",
                "keyword_info": {
                  "last_updated_time": "2021-05-03 15:17:18 +00:00",
                  "competition": 0.32,
                  "cpc": 11.75,
                  "search_volume": 880,
                  "categories": [],
                  "monthly_searches": []
                },
                "impressions_info": {
                  "last_updated_time": "2021-05-01 14:18:46 +00:00",
                  "bid": 999,
                  "match_type": "exact",
                  "ad_position_min": 1.48,
                  "ad_position_max": 2,
                  "ad_position_average": 1.35,
                  "cpc_min": 231.31,
                  "cpc_max": 282.71,
                  "cpc_average": 257.01,
                  "daily_impressions_min": 0.44,
                  "daily_impressions_max": 0.54,
                  "daily_impressions_average": 0.49,
                  "daily_clicks_min": 0.01,
                  "daily_clicks_max": 0.01,
                  "daily_clicks_average": 0.01,
                  "daily_cost_min": 1.62,
                  "daily_cost_max": 1.33,
                  "daily_cost_average": 1.48
                },
                "bing_keyword_info": {
                  "last_updated_time": "2021-05-01 12:15:11 +00:00",
                  "search_volume": 50,
                  "monthly_searches": []
                },
                "serp_info": {
                  "check_url": "https://www.google.com/search?q=seo%20software",
                  "serp_item_types": [
                    "organic",
                    "paid",
                    "featured_snippet"
                  ],
                  "se_results_count": 285000000,
                  "keyword_difficulty": 47,
                  "last_updated_time": "2021-04-16 15:50:51 +00:00",
                  "previous_updated_time": "2021-03-17 14:50:50 +00:00"
                }
              },
              "intersection_result": {
                "1": {
                  "type": "organic",
                  "rank_group": 3,
                  "rank_absolute": 5,
                  "position": "left",
                  "domain": "example.com",
                  "title": "示例页面标题",
                  "url": "https://example.com/page",
                  "main_domain": "example.com",
                  "relative_url": "/page",
                  "etv": 120.5,
                  "impressions_etv": 98.2,
                  "estimated_paid_traffic_cost": 350.6,
                  "rank_changes": {
                    "previous_rank_absolute": 8,
                    "is_new": false,
                    "is_up": true,
                    "is_down": false
                  }
                },
                "2": {
                  "type": "organic",
                  "rank_group": 7,
                  "rank_absolute": 9,
                  "position": "left",
                  "domain": "competitor.example",
                  "title": "竞争页面标题",
                  "url": "https://competitor.example/article",
                  "main_domain": "competitor.example",
                  "relative_url": "/article",
                  "etv": 85.3,
                  "impressions_etv": 66.1,
                  "estimated_paid_traffic_cost": 242.8,
                  "rank_changes": {
                    "previous_rank_absolute": null,
                    "is_new": true,
                    "is_up": false,
                    "is_down": false
                  }
                }
              }
            }
          ]
        }
      ]
    }
  ]
}

错误处理

请根据顶层和任务级别的 status_code、status_message 判断请求是否成功：

status_code = 20000：请求成功。
tasks_error > 0：至少有一个任务执行失败。
状态码：表示请求、参数或任务执行异常。

应用程序应针对网络错误、认证失败、参数校验失败、数据为空和任务级别错误建立重试、告警及降级处理机制。

完整错误码请参考：

/v3/appendix/errors

实用场景

发现排名：对比多个页面的交集，识别行业通用主题和覆盖空白，指导选题与页面规划。
挖掘竞争对手独占：通过 exclude_pages 找出竞争对手排名而目标页面未排名的词，制定优级明确的和外链优化计划。
评估页面排名差距：结合 intersection_result 中的 rank_absolute、rank_changes 和 keyword_difficulty，定位页面与竞争对手之间的排名差距。
筛选商业价值：使用搜索量、CPC、ETV 和 estimated_paid_traffic_cost，优选择流量潜力高且备转化价值的。
分析 SERP 展现机会：启用 include_serp_info，识别精选摘要、本地结果和付费结果等 SERP 特征，优化结构和搜索结果占位策略。

页面交集（旧版） ​

接口说明 ​

查询多个页面排名的 ​

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

计费与限制 ​

请求参数 ​

任务参数 ​

URL 通符规则 ​

intersection_mode 取值 ​

filters ​

order_by ​

地区与语言 ​

请求示例 ​

curl ​

Python ​

TypeScript ​

响应结构 ​

顶层字段 ​

任务字段 ​

result 字段 ​

items 字段 ​

keyword_data ​

keyword_info ​

impressions_info ​

bing_keyword_info ​

serp_info ​

intersection_result ​

通用 SERP 字段 ​

organic 自然结果字段 ​

paid 付费结果字段 ​

local_pack 本地结果字段 ​

页面交集（旧版）

接口说明

查询多个页面排名的

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

计费与限制

请求参数

任务参数

URL 通符规则

`intersection_mode` 取值

`filters`

`order_by`

地区与语言

请求示例

curl

Python

TypeScript

响应结构

顶层字段

任务字段

`result` 字段

`items` 字段

`keyword_data`

`keyword_info`

`impressions_info`

`bing_keyword_info`

`serp_info`

`intersection_result`

通用 SERP 字段

`organic` 自然结果字段

`paid` 付费结果字段

`local_pack` 本地结果字段