OnPage 过滤器与可自定义阈值

本页介绍本平台 OnPage API 支持的过滤器与可自定义检查阈值。

过滤器和阈值均与响应 result 数组中的对象，因此根据所调用端点及返回对象进行。

获取完整过滤器列表

HTTP 请求

GET /v3/on_page/available_filters

该接口用于获取 OnPage API 支持的完整过滤参数列表，不产生接口调用费用。

bash

curl --request GET \
  --url https://api.seermartech.cn/v3/on_page/available_filters \
  --header 'Authorization: Bearer smt_live_YOUR_KEY'

响应结构

接口返回 JSON 数据，核心字段如下：

字段	类型	说明
`version`	string	API 当前版本
`status_code`	integer	通用状态码
`status_message`	string	通用状态信息
`time`	string	执行耗时，单位为秒
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务数量
`tasks_error`	integer	`tasks` 数组中返回错误的任务数量
`tasks`	array	任务结果数组
`tasks[].id`	string	任务唯一标识，UUID 格式
`tasks[].status_code`	integer	任务状态码，通常位于 `10000`–`60000` 范围
`tasks[].status_message`	string	任务状态信息
`tasks[].time`	string	任务执行耗时
`tasks[].cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks[].result_count`	integer	`result` 数组中的数量
`tasks[].path`	array	请求 URL 路径
`tasks[].data`	array	GET 请求中传递的参数
`tasks[].result`	array	过滤器列表，按可用端点分组

完整错误码请参考错误码文档。

响应示例

json

{
  "version": "0.1.20250724",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.0387 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.0010 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "on_page",
        "available_filters"
      ],
      "data": [
        {
          "api": "on_page",
          "function": "available_filters"
        }
      ],
      "result": [
        {
          "resources": [],
          "pages": [],
          "non_indexable": [],
          "links": [],
          "page_by_resource": [],
          "keyword_density": [],
          "uncrawlable_resources": []
        }
      ]
    }
  ]
}

过滤器

OnPage API 支持在请求中使用过滤器筛选返回结果。每个请求最多可 8 个过滤条件，条件之间可使用 and 或 or 连接。

过滤器格式

json

{
  "filters": [
    ["field_name", "operator", "value"],
    "and",
    ["another_field", "operator", "value"]
  ]
}

例如，筛选页面评分低于 50 且断链的页面：

json

{
  "filters": [
    ["onpage_score", "<", 50],
    "and",
    ["broken_links", "=", true]
  ]
}

支持的运算符

运算符	适用场景
`regex`	匹正则表达式
`not_regex`	排除匹正则表达式的值
`<`、`<=`、`>`、`>=`	数值或时间比较
`=`	等于
`<>`	不等于
`in`	值属于指定集合
`not_in`	值不属于指定集合
`like`	模糊匹
`not_like`	排除模糊匹
`match`	文本匹
`not_match`	排除文本匹
`has`	数组字段指定值
`has_not`	数组字段不指定值

regex 和 not_regex 使用 RE2 正则表达式语法，表达式最大长度为 1000 个字符。
使用 like 或 not_like 时，可使用 % 匹零个或多个字符。

`resources` 端点过滤器

适用于：

/v3/on_page/resources

字段	类型	说明	支持的运算符
`resource_type`	string	资源类型：`script`、`image`、`stylesheet`、`broken`	文本运算符
`meta.alternative_text`	string	图片 `alt` 属性	文本运算符
`meta.title`	string	资源的 `title` 属性	文本运算符
`meta.original_width`	number	原始图片宽度，单位为像素	数值运算符
`meta.original_height`	number	原始图片高度，单位为像素	数值运算符
`meta.width`	number	图片宽度，单位为像素	数值运算符
`meta.height`	number	图片高度，单位为像素	数值运算符
`status_code`	number	资源所在页面的 HTTP 状态码	数值运算符
`location`	number	资源所在页面的状态码信息	数值运算符
`url`	string	资源 URL	文本运算符
`size`	number	资源大小，单位为字节	数值运算符
`encoded_size`	number	编码后的资源大小，单位为字节	数值运算符
`total_transfer_size`	number	压缩后的资源传输大小，单位为字节	数值运算符
`fetch_time`	time	资源抓取时间，UTC 格式：`yyyy-mm-dd hh-mm-ss +00:00`	数值/时间运算符
`fetch_timing.duration_time`	number	获取资源耗时，单位为毫秒	数值运算符
`fetch_timing.fetch_start`	number	浏览器开始下载资源所需时间，单位为毫秒	数值运算符
`fetch_timing.fetch_end`	number	浏览器完成下载资源所需时间，单位为毫秒	数值运算符
`cache_control.cachable`	boolean	资源是否可缓存	`=`、`<>`
`cache_control.ttl`	number	缓存有效期，单位为毫秒	数值运算符
`checks.no_content_encoding`	boolean	页面是否未使用压缩	`=`、`<>`
`checks.high_loading_time`	boolean	资源加载时间是否 3 秒	`=`、`<>`
`checks.is_redirect`	boolean	页面是否存在 `3XX` 重定向	`=`、`<>`
`checks.is_4xx_code`	boolean	是否返回 `4XX` 状态码	`=`、`<>`
`checks.is_5xx_code`	boolean	是否返回 `5XX` 状态码	`=`、`<>`
`checks.is_broken`	boolean	是否返回 `404` 状态码	`=`、`<>`
`checks.is_www`	boolean	页面是否位于 `www` 子域名	`=`、`<>`
`checks.is_https`	boolean	页面是否使用 HTTPS	`=`、`<>`
`checks.is_http`	boolean	页面是否使用 HTTP	`=`、`<>`
`checks.is_minified`	boolean	资源是否已压缩或最小化	`=`、`<>`
`checks.has_redirect`	boolean	资源是否发生重定向	`=`、`<>`
`checks.from_sitemap`	boolean	资源是否来自站点地图	`=`、`<>`
`checks.has_subrequests`	boolean	资源是否子请求	`=`、`<>`
`content_encoding`	string	编码类型	文本运算符
`media_type`	string	用于展示资源的媒体类型	文本运算符
`accept_type`	string	期望的资源类型，例如 `image`、`script`、`html`、`font`	文本运算符
`server`	string	服务器版本信息	文本运算符

accept_type 可取值：

any、none、image、sitemap、robots、script、stylesheet、redirect、html、text、other、font。

`pages` 端点过滤器

适用于：

/v3/on_page/pages

页面基础与数据字段

字段	类型	说明
`resource_type`	string	页面类型：`html`、`broken`、`redirect`
`meta.title`	string	页面标题
`meta.charset`	number	页面编码页码
`meta.follow`	boolean	页面是否可被索引
`meta.generator`	string	`generator`标签
`meta.description`	string	`description`标签
`meta.favicon`	string	网站图标 URL
`meta.meta_keywords`	string	`keywords`标签
`meta.canonical`	string	规范页面 URL
`meta.internal_links_count`	number	页面链接数量
`meta.external_links_count`	number	页面外部链接数量
`meta.inbound_links_count`	number	指向该页面的链接数量
`meta.images_count`	number	页面图片数量
`meta.images_size`	number	图片总大小，单位为字节
`meta.scripts_count`	number	页面脚本数量
`meta.scripts_size`	number	脚本总大小，单位为字节
`meta.stylesheets_count`	number	样式表数量
`meta.stylesheets_size`	number	样式表总大小，单位为字节
`meta.title_length`	number	`title` 标签字符数
`meta.description_length`	number	`description` 标签字符数
`meta.render_blocking_scripts_count`	number	阻塞页面渲染的脚本数量
`meta.render_blocking_stylesheets_count`	number	阻塞页面渲染的样式表数量
`meta.cumulative_layout_shift`	number	累积布局偏移 CLS
`meta.content.plain_text_size`	number	页面纯文本大小，单位为字节
`meta.content.plain_text_rate`	number	纯文本大小与页面大小的比值
`meta.content.plain_text_word_count`	number	页面文字数量
`meta.content.automated_readability_index`	number	自动可读性指数
`meta.content.coleman_liau_readability_index`	number	Coleman–Liau 可读性指数
`meta.content.dale_chall_readability_index`	number	Dale–Chall 可读性指数
`meta.content.flesch_kincaid_readability_index`	number	Flesch–Kincaid 可读性指数
`meta.content.smog_readability_index`	number	SMOG 可读性指数
`meta.content.description_to_content_consistency`	number	描述与页面的一致性，范围为 0–1
`meta.content.title_to_content_consistency`	number	标题与页面的一致性，范围为 0–1
`meta.content.meta_keywords_to_content_consistency`	number	与页面的一致性，范围为 0–1
`meta.spell`	string	拼写检查错误与建议
`meta.duplicate_meta_tags`	array<string>	重复的标签

上述字段中，字符串字段支持文本运算符；数值字段支持数值运算符；布尔字段支持 =、<>；meta.duplicate_meta_tags 支持 has。

页面性能与技术检查字段

字段	类型	说明
`page_timing.time_to_interactive`	number	可交互时间 TTI，单位为毫秒
`page_timing.dom_complete`	number	页面及子资源加载完成时间，单位为毫秒
`page_timing.largest_contentful_paint`	number	最大绘制 LCP，单位为毫秒
`page_timing.first_input_delay`	number	首次延迟 FID，单位为毫秒
`page_timing.connection_time`	number	建立服务器连接耗时，单位为毫秒
`page_timing.time_to_secure_connection`	number	建立连接耗时，单位为毫秒
`page_timing.request_sent_time`	number	发送请求耗时，单位为毫秒
`page_timing.waiting_time`	number	等首字节时间 TTFB，单位为毫秒
`page_timing.download_time`	number	浏览器接收响应耗时，单位为毫秒
`page_timing.duration_time`	number	接收完整响应的总耗时，单位为毫秒
`page_timing.fetch_start`	number	开始下载 HTML 的时间
`page_timing.fetch_end`	number	完成下载 HTML 的时间
`onpage_score`	number	页面优化评分，满分 100
`total_dom_size`	number	页面 DOM 总大小
`broken_resources`	boolean	页面是否失效资源
`broken_links`	boolean	页面是否断链
`duplicate_title`	boolean	页面是否存在重复标题
`duplicate_description`	boolean	页面是否存在重复描述
`duplicate_content`	boolean	页面是否存在重复
`status_code`	number	页面 HTTP 状态码
`location`	number	页面重定向或位置状态信息
`url`	string	页面 URL
`click_depth`	number	从首页到达该页面所需的点击层级
`size`	number	页面大小，单位为字节
`encoded_size`	number	编码后的页面大小，单位为字节
`total_transfer_size`	number	压缩后的页面传输大小，单位为字节
`fetch_time`	time	页面抓取时间，UTC 格式
`cache_control.cachable`	boolean	页面是否可缓存
`cache_control.ttl`	number	页面缓存有效期，单位为毫秒
`content_encoding`	string	编码类型
`media_type`	string	媒体类型
`server`	string	服务器版本
`is_resource`	boolean	是否为资源页面
`url_length`	number	完整 URL 长度
`relative_url_length`	number	相对 URL 长度

上述性能、计数及大小字段支持数值运算符；布尔字段支持 =、<>；字符串字段支持文本运算符。

`checks` 布尔检查字段

以下字段均为 boolean 类型支持 = 和 <>：

字段	说明
`checks.no_content_encoding`	页面未使用压缩
`checks.high_loading_time`	页面加载时间阈值，默认 3 秒
`checks.is_redirect`	页面存在 `3XX` 重定向
`checks.is_4xx_code`	页面返回 `4XX` 状态码
`checks.is_5xx_code`	页面返回 `5XX` 状态码
`checks.is_broken`	页面返回 `404`
`checks.is_www`	页面位于 `www` 子域名
`checks.is_https`	页面使用 HTTPS
`checks.is_http`	页面使用 HTTP
`checks.high_waiting_time`	TTFB过阈值，默认 1.5 秒
`checks.has_micromarkup`	页面微数据标记
`checks.has_micromarkup_errors`	微数据标记存在错误
`checks.no_doctype`	缺少 `<!DOCTYPE HTML>` 声明
`checks.canonical`	页面为规范页面
`checks.no_encoding_meta_tag`	缺少编码标签；当 `Content-Type` 未明确编码时有效
`checks.no_h1_tags`	`h1` 标签为空或缺失
`checks.https_to_http_links`	HTTPS 页面指向 HTTP 页面的链接
`checks.has_html_doctype`	页面 HTML 文档类型声明
`checks.size_greater_than_3mb`	页面大小 3 MB
`checks.meta_charset_consistency`	页面一致的 `meta charset`置
`checks.has_meta_refresh_redirect`	页面使用 Meta Refresh 重定向
`checks.has_render_blocking_resources`	页面阻塞渲染的脚本或样式表
`checks.redirect_chain`	页面存在多次连续重定向
`checks.recursive_canonical`	页面与规范页面相互指向，形成递归规范链
`checks.low_content_rate`	纯文本与页面大小的比值低于阈值，默认 0.1
`checks.high_content_rate`	纯文本与页面大小的比值高于阈值，默认 0.9；规范页面可用
`checks.low_character_count`	页面字符数低于阈值，默认 1024
`checks.high_character_count`	页面字符数高于阈值，默认 256000
`checks.small_page_size`	页面大小低于阈值，默认 1024 字节
`checks.large_page_size`	页面大小高于阈值，默认 1 MB
`checks.low_readability_rate`	Flesch–Kincaid 可读性评分低于阈值，默认 15
`checks.irrelevant_description`	`description` 与页面性不足；默认阈值 0.2规范页面可用
`checks.irrelevant_title`	`title` 与页面性不足；默认阈值 0.3规范页面可用
`checks.irrelevant_meta_keywords`	`keywords` 与页面性不足；默认阈值 0.6规范页面可用
`checks.title_too_long`	`title` 字符数阈值，默认 65
`checks.title_too_short`	`title` 字符数低于阈值，默认 30
`checks.deprecated_html_tags`	页面使用已废弃的 HTML 标签
`checks.duplicate_meta_tags`	页面存在同类型重复标签；规范页面可用
`checks.duplicate_title_tag`	页面存在多个 `title` 标签；规范页面可用
`checks.no_image_alt`	图片缺少 `alt` 属性
`checks.no_image_title`	图片缺少 `title` 属性
`checks.no_description`	`description`标签为空或缺失；规范页面可用
`checks.no_title`	`title` 标签为空或缺失
`checks.no_favicon`	页面缺少网站图标
`checks.seo_friendly_url`	URL 不符合 SEO 友好标准；规范页面可用
`checks.flash`	页面 Flash素
`checks.frame`	页面 `frame`、`iframe` 或 `frameset` 标签
`checks.lorem_ipsum`	页面占位文本 `lorem ipsum`
`checks.seo_friendly_url_characters_check`	URL 大小写拉丁字母、数字和短横线
`checks.seo_friendly_url_dynamic_check`	URL 不动态参数
`checks.seo_friendly_url_keywords_check`	URL 与 `title`标签
`checks.seo_friendly_url_relative_length_check`	URL 相对路径不 120 个字符
`checks.canonical_chain`	规范页面指向另一个仍指向页面的规范页面
`checks.canonical_to_redirect`	规范链接指向重定向页面
`checks.canonical_to_broken`	规范链接指向失效页面
`checks.has_links_to_redirects`	页面指向重定向页面的链接
`checks.is_orphan_page`	页面没有链接指向
`checks.is_link_relation_conflict`	页面同时收到 `nofollow` 和 dofollow部链接
`checks.from_sitemap`	页面来自站点地图

SEO 友好 URL 检查：

相对路径长度小于 120 个字符；
不特殊字符；
不动态参数；
URL 与页面。

任一条件不满足时，checks.seo_friendly_url 将被判定为不符合 SEO 友好标准。

`non_indexable` 端点过滤器

适用于：

/v3/on_page/non_indexable

字段	类型	说明	支持的运算符
`reason`	string	页面不可索引原因：`robots_txt`、`meta_tag`、`http_header`、`attribute`、`too_many_redirects`	文本运算符
`url`	string	不可索引页面 URL	文本运算符

`links` 端点过滤器

适用于：

/v3/on_page/links

字段	类型	说明	支持的运算符
`type`	string	链接类型：`anchor`、`image`、`link`、`canonical`、`meta`、`alternate`	文本运算符
`domain_from`	string	引用域名	文本运算符
`domain_to`	string	目标域名	文本运算符
`page_from`	string	发现链接的页面相对 URL	文本运算符
`page_to`	string	链接目标页面相对 URL	文本运算符
`link_from`	string	发现链接的页面绝对 URL	文本运算符
`link_to`	string	链接目标页面绝对 URL	文本运算符
`link_attribute`	array	外部链接属性，例如 `nofollow`	`has`
`dofollow`	boolean	是否为 dofollow 链接；为 `true` 时不 `rel="nofollow"`	`=`、`<>`
`page_from_scheme`	string	引用页面 URL 协议	文本运算符
`page_to_scheme`	string	目标页面 URL 协议	文本运算符
`direction`	string	链接方向：`internal`、`external`	文本运算符
`page_to_status_code`	number	目标页面 HTTP 状态码	数值运算符

`page_by_resource` 端点过滤器

适用于：

/v3/on_page/page_by_resource

该端点支持与 pages 端点相同的大部分页面字段和检查字段，差异如下：

resource_type 的可选值为 html、broken；
支持页面数据、质量、页面性能、URL、资源大小和 checks 字段；
checks 字段的含义及支持运算符与 pages 端点一致。

主要字段：

meta.title、meta.charset、meta.follow、meta.generator、meta.description、meta.favicon、meta.meta_keywords、meta.canonical、meta.internal_links_count、meta.external_links_count、meta.inbound_links_count、meta.images_count、meta.images_size、meta.scripts_count、meta.scripts_size、meta.stylesheets_count、meta.stylesheets_size、meta.title_length、meta.description_length、meta.render_blocking_scripts_count、meta.render_blocking_stylesheets_count、meta.cumulative_layout_shift、meta.content.*、meta.spell、meta.duplicate_meta_tags、page_timing.*、onpage_score、total_dom_size、broken_resources、broken_links、duplicate_title、duplicate_description、duplicate_content、status_code、location、url、size、encoded_size、total_transfer_size、fetch_time、cache_control.*、checks.*、content_encoding、media_type、server、is_resource。

字段类型和运算符规则如下：

string 字段：支持文本运算符；
number 字段：支持数值运算符；
boolean 字段：支持 =、<>；
array 字段：支持 has。

`keyword_density` 端点过滤器

适用于：

/v3/on_page/keyword_density

字段	类型	说明	支持的运算符
`keyword`	string	在网站或页面中发现的	文本运算符
`frequency`	number	出现次数；如果任务指定了 `url`，则表示页面中的出现次数	数值运算符
`density`	number	密度，即 `frequency` 与指定 `keyword_length` 下总数的比值	数值运算符

`uncrawlable_resources` 端点过滤器

适用于：

/v3/on_page/uncrawlable_resources

字段	类型	说明	支持的运算符
`url`	string	无法抓取的资源 URL	文本运算符
`reason`	string	无法抓取原因，目前可为 `content_type_inconsistency`	文本运算符
`status_code`	number	资源返回的 HTTP 状态码，目前通常为 `200`	数值运算符
`fetch_time`	time	资源抓取时间，UTC 格式	数值/时间运算符
`meta.content_type`	string	资源类型	文本运算符

阈值

OnPage API 通过 POST 请求中的 checks_threshold 对页面检查阈值进行自定义。

任务接口使用：

POST /v3/on_page/task_post

请求体示例

POST 请求体为 JSON 数组：

json

[
  {
    "target": "https://example.com",
    "checks_threshold": {
      "title_too_short": 20,
      "title_too_long": 60,
      "small_page_size": 2048,
      "large_page_size": 2000000,
      "high_loading_time": 4000,
      "high_waiting_time": 1000
    }
  }
]

可阈值

字段	类型	判断逻辑	默认值
`title_too_short`	integer	`title` 字符数小于或等于该值时标记	`30`
`title_too_long`	integer	`title` 字符数大于或等于该值时标记	`65`
`small_page_size`	integer	页面大小小于或等于该值时标记，单位为字节	`1024`
`large_page_size`	integer	页面大小大于或等于该值时标记，单位为字节	`1048576`
`low_character_count`	integer	页面字符数小于或等于该值时标记	`1024`
`high_character_count`	integer	页面字符数大于或等于该值时标记	`256000`
`low_content_rate`	float	纯文本大小与页面大小比值小于或等于该值时标记	`0.1`
`high_content_rate`	float	纯文本大小与页面大小比值大于或等于该值时标记	`0.9`
`high_loading_time`	integer	页面加载耗时大于或等于该值时标记，单位为毫秒	`3000`
`high_waiting_time`	integer	TTFB 大于或等于该值时标记，单位为毫秒	`1500`
`low_readability_rate`	float	Flesch–Kincaid 可读性评分低于或等于该值时标记	`15.0`
`irrelevant_description`	float	`description` 与正文匹度小于或等于该值时标记	`0.2`
`irrelevant_title`	float	`title` 与正文匹度小于或等于该值时标记	`0.3`
`irrelevant_meta_keywords`	float	`keywords` 与正文匹度小于或等于该值时标记	`0.6`

阈值示例

json

[
  {
    "target": "https://example.com",
    "checks_threshold": {
      "title_too_short": 10,
      "title_too_long": 50,
      "small_page_size": 2048,
      "large_page_size": 2000000,
      "low_character_count": 1500,
      "high_character_count": 500000,
      "low_content_rate": 0.3,
      "high_content_rate": 0.8,
      "high_loading_time": 4000,
      "high_waiting_time": 1000,
      "low_readability_rate": 20.5,
      "irrelevant_description": 0.5,
      "irrelevant_title": 0.1,
      "irrelevant_meta_keywords": 0.5
    }
  }
]

> 注意：阈值字段的判断方向以检查项定义为准。自定义阈值后，响应中的对应 checks 字段将依据新的阈值进行标记。

实用场景

筛选加载时间过长的页面，定位影响 Core Web Vitals 和用户体验的 URL，优安排前端性能优化。
识别断链、失效资源和 4XX/5XX 页面，减少抓取浪费并修复影响搜索引擎访问的技术问题。
筛查标题、描述和正文质量问题，批量发现缺失、过短、过长或与页面不的标签。
分析链接结构，识别孤立页面、重定向链、指向失效页面的链接以及 nofollow 与 dofollow 冲突。
按频率和密度筛选页面，发现堆砌、覆盖不足或需要扩主题性的页面。

OnPage 过滤器与可自定义阈值 ​

获取完整过滤器列表 ​

HTTP 请求 ​

响应结构 ​

响应示例 ​

过滤器 ​

过滤器格式 ​

支持的运算符 ​

resources 端点过滤器 ​

pages 端点过滤器 ​

页面基础与数据字段 ​

页面性能与技术检查字段 ​

checks 布尔检查字段 ​

non_indexable 端点过滤器 ​

links 端点过滤器 ​

page_by_resource 端点过滤器 ​

keyword_density 端点过滤器 ​

uncrawlable_resources 端点过滤器 ​

阈值 ​

请求体示例 ​

可阈值 ​

阈值示例 ​

实用场景 ​

OnPage 过滤器与可自定义阈值

获取完整过滤器列表

HTTP 请求

响应结构

响应示例

过滤器

过滤器格式

支持的运算符

`resources` 端点过滤器

`pages` 端点过滤器

页面基础与数据字段

页面性能与技术检查字段

`checks` 布尔检查字段

`non_indexable` 端点过滤器

`links` 端点过滤器

`page_by_resource` 端点过滤器

`keyword_density` 端点过滤器

`uncrawlable_resources` 端点过滤器

阈值

请求体示例

可阈值

阈值示例

实用场景