OnPage 过滤器与自定义阈值

本页说明 OnPage API 中可用的过滤器（filters）与可自定义检查阈值（checks thresholds）。

OnPage 接口支持大量可的抓取与数据筛选参数，您可以：

• 按字段过滤页面、资源、链接等结果；
• 调整页面质量与性能检查项的判定阈值；
• 根据不同业务需求，定制技术 SEO 审计规则。

需要注意的是，过滤器与阈值都与 result 数组中的对象，因此针对对应端点支持的字段进行设置。

过滤器概览

可通过以下接口获取当前支持的完整过滤字段列表。

获取可用过滤器

请求方式： GET接口地址：

https://api.seermartech.cn/v3/on_page/available_filters

计费

调用该接口不收费。 扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

认证

Authorization: Bearer smt_live_YOUR_KEY

响应结构

接口返回 JSON 数据，顶层 tasks 数组。

字段	类型	说明
version	string	当前 API 版本
status_code	integer	接口总状态码
status_message	string	接口总状态信息
time	string	执行耗时，单位秒
cost	float	本次请求总费用
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	任务费用
result_count	integer	result 数组中的结果数量
path	array	URL 路径
data	array	GET 请求 URL 中传的参数
result	array	可用于数据过滤的字段列表，按端点分组

过滤器语法

在 OnPage API 中，您最多可以指定 8 个过滤条件，并通过逻辑运算符 and、or 进行组合。

支持的比较运算符

支持以下运算符：

• regex
• not_regex
• <
• <=
• >
• >=
• =
• <>
• in
• not_in
• like
• not_like
• match
• not_match

特殊说明

• regex 和 not_regex 适用于字符串字段，正则语法采用 RE2；
• regex / not_regex 的最大字符长度为 1000；
• like / not_like 中可使用 % 匹任意长度字符串（空字符串）；
• 对数组字段，可使用 has 或 has_not 进行过滤。

过滤器示例

"filters": [
 ["resource_type", "=", "image"],
 "and",
 ["checks.is_broken", "=", true]
]

数组字段过滤示例：

"filters": [
 ["meta.duplicate_meta_tags", "has", "description"]
]

---

各端点支持的过滤字段

以下按端点列出常用过滤字段。由于原始字段非常多，建议同时通过 /v3/on_page/available_filters 动态获取完整列表，并以接口返回为准。

---

/v3/on_page/resources 支持的过滤字段

用于筛选页面中抓取到的资源，如图片、脚本、样式表、损坏资源等。

字段	类型	说明	支持运算符
resource_type	str	返回资源类型；可选：script、image、stylesheet、broken	regex, not_regex, =, <>, like, not_like, match, not_match
meta.alternative_text	str	图片 alt 属性	字符串运算符
meta.title	str	资源 title 属性	字符串运算符
meta.original_width	num	图片原始宽度（像素）	数值运算符
meta.original_height	num	图片原始高度（像素）	数值运算符
meta.width	num	图片宽度（像素）	数值运算符
meta.height	num	图片高度（像素）	数值运算符
status_code	num	资源所在页面的状态码	数值运算符
location	num	资源所在页面的状态码/定位信息字段	数值运算符
url	str	资源 URL	字符串运算符
size	num	资源大小，字节	数值运算符
encoded_size	num	编码后资源大小，字节	数值运算符
total_transfer_size	num	压缩传输大小，字节	数值运算符
fetch_time	time	抓取时间，UTC：yyyy-mm-dd hh-mm-ss +00:00	数值/时间运算符
fetch_timing.duration_time	num	抓取资源总耗时，毫秒	数值运算符
fetch_timing.fetch_start	num	浏览器开始下载资源耗时，毫秒	数值运算符
fetch_timing.fetch_end	num	浏览器完成下载资源耗时，毫秒	数值运算符
cache_control.cachable	bool	是否可缓存	=, <>
cache_control.ttl	num	缓存生存时间，毫秒	数值运算符
checks.no_content_encoding	bool	是否未启用压缩	=, <>
checks.high_loading_time	bool	加载时间是否 3 秒	=, <>
checks.is_redirect	bool	是否存在 3XX 重定向	=, <>
checks.is_4xx_code	bool	是否为 4xx 响应	=, <>
checks.is_5xx_code	bool	是否为 5xx 响应	=, <>
checks.is_broken	bool	是否为损坏资源（如 404）	=, <>
checks.is_www	bool	是否位于 www 子域	=, <>
checks.is_https	bool	是否使用 https 协议	=, <>
checks.is_http	bool	是否使用 http 协议	=, <>
checks.is_minified	bool	资源是否已最小化	=, <>
checks.has_redirect	bool	资源是否有重定向	=, <>
checks.from_sitemap	bool	是否来自站点地图	=, <>
checks.has_subrequests	bool	是否子请求	=, <>
content_encoding	str	编码类型	字符串运算符
media_type	str	资源展示媒体类型	字符串运算符
accept_type	str	预期资源类型，可选：any、none、image、sitemap、robots、script、stylesheet、redirect、html、text、other、font	字符串运算符
server	str	服务器版本	字符串运算符

说明：文中“字符串运算符”指 regex, not_regex, =, <>, like, not_like, match, not_match； “数值运算符”指 <, <=, >, >=, =, <>, in, not_in。

---

/v3/on_page/pages 支持的过滤字段

用于按页面级别筛选站 HTML 页、损坏页、重定向页等。

页面类型与基础信息

字段	类型	说明	支持运算符
resource_type	str	页面类型：html、broken、redirect	字符串运算符
url	str	页面 URL	字符串运算符
status_code	num	页面状态码	数值运算符
location	num	页面定位/状态字段	数值运算符
click_depth	num	从首页到该页的点击深度	数值运算符
size	num	页面大小，字节	数值运算符
encoded_size	num	编码后页面大小，字节	数值运算符
total_transfer_size	num	压缩传输大小，字节	数值运算符
fetch_time	time	页面抓取时间，UTC	数值/时间运算符
is_resource	bool	是否被识别为资源	=, <>
url_length	num	URL 总长度	数值运算符
relative_url_length	num	相对路径长度	数值运算符

Meta 与链接统计字段

字段	类型	说明	支持运算符
meta.title	str	页面标题	字符串运算符
meta.charset	num	字符集编码页	数值运算符
meta.follow	bool	页面是否可跟踪/可索引标识	=, <>
meta.generator	str	meta generator	字符串运算符
meta.description	str	description	字符串运算符
meta.favicon	str	favicon 地址	字符串运算符
meta.meta_keywords	str	keywords	字符串运算符
meta.canonical	str	canonical 地址	字符串运算符
meta.internal_links_count	num	站链接数	数值运算符
meta.external_links_count	num	外链数	数值运算符
meta.inbound_links_count	num	指向该页的链接数	数值运算符
meta.images_count	num	图片数量	数值运算符
meta.images_size	num	图片总大小，字节	数值运算符
meta.scripts_count	num	脚本数量	数值运算符
meta.scripts_size	num	脚本总大小，字节	数值运算符
meta.stylesheets_count	num	样式表数量	数值运算符
meta.stylesheets_size	num	样式表总大小，字节	数值运算符
meta.title_length	num	title 长度	数值运算符
meta.description_length	num	description 长度	数值运算符
meta.render_blocking_scripts_count	num	阻塞渲染脚本数	数值运算符
meta.render_blocking_stylesheets_count	num	阻塞渲染样式数	数值运算符
meta.cumulative_layout_shift	num	CLS 指标	数值运算符

正文字段与可读性字段

字段	类型	说明	支持运算符
meta.content.plain_text_size	num	纯文本总大小，字节	数值运算符
meta.content.plain_text_rate	num	纯文本占比：plain_text_size / size	数值运算符
meta.content.plain_text_word_count	num	单词总数	数值运算符
meta.content.automated_readability_index	num	Automated Readability Index	数值运算符
meta.content.coleman_liau_readability_index	num	Coleman–Liau Index	数值运算符
meta.content.dale_chall_readability_index	num	Dale–Chall Readability Index	数值运算符
meta.content.flesch_kincaid_readability_index	num	Flesch–Kincaid Readability Index	数值运算符
meta.content.smog_readability_index	num	SMOG Readability Index	数值运算符
meta.content.description_to_content_consistency	num	description 与正文一致性，范围 0-1	数值运算符
meta.content.title_to_content_consistency	num	title 与正文一致性，范围 0-1	数值运算符
meta.content.meta_keywords_to_content_consistency	num	keywords 与正文一致性，范围 0-1	数值运算符
meta.spell	str	拼写检查结果与建议	字符串运算符
meta.duplicate_meta_tags	array.str	重复的 meta 标签列表	has

页面性能字段

字段	类型	说明	支持运算符
page_timing.time_to_interactive	num	TTI，可交互时间（毫秒）	数值运算符
page_timing.dom_complete	num	页面及子资源下载完成时间（毫秒）	数值运算符
page_timing.largest_contentful_paint	num	LCP 指标	数值运算符
page_timing.first_input_delay	num	FID 指标	数值运算符
page_timing.connection_time	num	建连耗时（毫秒）	数值运算符
page_timing.time_to_secure_connection	num	建立连接耗时（毫秒）	数值运算符
page_timing.request_sent_time	num	请求发送耗时（毫秒）	数值运算符
page_timing.waiting_time	num	TTFB，首字节时间（毫秒）	数值运算符
page_timing.download_time	num	响应下载耗时（毫秒）	数值运算符
page_timing.duration_time	num	总响应耗时（毫秒）	数值运算符
page_timing.fetch_start	num	开始下载 HTML 的耗时	数值运算符
page_timing.fetch_end	num	完成下载 HTML 的耗时	数值运算符

质量评分与布尔检查项

字段	类型	说明	支持运算符
onpage_score	num	页面优化评分，100 分制	数值运算符
total_dom_size	num	页面 DOM 总大小	数值运算符
broken_resources	bool	是否损坏资源	=, <>
broken_links	bool	是否损坏链接	=, <>
duplicate_title	bool	是否存在重复标题	=, <>
duplicate_description	bool	是否存在重复描述	=, <>
duplicate_content	bool	是否存在重复	=, <>

checks.* 页面检查项

以下字段均为 bool，支持运算符 =, <>：

• checks.no_content_encoding：未启用压缩
• checks.high_loading_time：加载时间过高（默认 3 秒）
• checks.is_redirect：存在重定向
• checks.is_4xx_code：页面为 4xx
• checks.is_5xx_code：页面为 5xx
• checks.is_broken：页面损坏
• checks.is_www：位于 www 子域
• checks.is_https：使用 https
• checks.high_waiting_time：TTFB 过高（默认 1.5 秒）
• checks.has_micromarkup：微数据标记
• checks.has_micromarkup_errors：微数据存在错误
• checks.no_doctype：无 <!DOCTYPE HTML>
• checks.canonical：页面为 canonical
• checks.no_encoding_meta_tag：无编码 meta 标签
• checks.no_h1_tags：无 H1 或 H1 为空
• checks.https_to_http_links：HTTPS 页 HTTP 链接
• checks.has_html_doctype： HTML doctype
• checks.size_greater_than_3mb：页面大于 3MB
• checks.meta_charset_consistency：存在 meta charset
• checks.has_meta_refresh_redirect：存在 meta refresh 跳转
• checks.has_render_blocking_resources：存在阻塞渲染资源
• checks.redirect_chain：存在多级跳转
• checks.recursive_canonical：递归 canonical 错误
• checks.low_content_rate：正文占比过低
• checks.high_content_rate：正文占比过高 canonical 页面
• checks.low_character_count：字符数过低
• checks.high_character_count：字符数过高
• checks.small_page_size：页面过小
• checks.large_page_size：页面过大
• checks.low_readability_rate：可读性评分过低
• checks.irrelevant_description：description 与正文不
• checks.irrelevant_title：title 与正文不
• checks.irrelevant_meta_keywords：keywords 与正文不
• checks.title_too_long：标题过长
• checks.title_too_short：标题过短
• checks.deprecated_html_tags：存在废弃 HTML 标签
• checks.duplicate_meta_tags：重复 meta 标签
• 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：缺少 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 与标题性校验
• checks.seo_friendly_url_relative_length_check：URL 长度校验
• checks.canonical_chain：canonical 链
• checks.canonical_to_redirect：canonical 指向重定向页
• checks.canonical_to_broken：canonical 指向损坏页
• checks.has_links_to_redirects：页面链接指向重定向页
• checks.is_orphan_page：孤立页面
• checks.is_link_relation_conflict：同时收到 nofollow 与 dofollow链
• checks.from_sitemap：来自站点地图

页面字段

字段	类型	说明	支持运算符
content_encoding	str	编码类型	字符串运算符
media_type	str	媒体类型	字符串运算符
server	str	服务器版本	字符串运算符

---

端点支持的过滤字段

/v3/on_page/non_indexable

字段	类型	说明
reason	str	不可索引原因；可选：robots_txt、meta_tag、http_header、attribute、too_many_redirects
url	str	不可索引页面 URL

字符串字段支持：regex, not_regex, =, <>, like, not_like, match, not_match

/v3/on_page/links

字段	类型	说明
type	str	链接类型：anchor、image、link、canonical、meta、alternate
domain_from	str	来源域名
domain_to	str	目标域名
page_from	str	来源页面相对 URL
page_to	str	目标页面相对 URL
link_from	str	来源页面绝对 URL
link_to	str	目标页面绝对 URL
link_attribute	array	链接属性，支持 has
dofollow	bool	是否 dofollow
page_from_scheme	str	来源页 scheme
page_to_scheme	str	目标页 scheme
direction	str	链接方向：internal、external
page_to_status_code	num	目标页状态码

/v3/on_page/page_by_resource

该端点支持的过滤字段与 /v3/on_page/pages 大体一致，适用于按资源反查页面的场景。可使用同类页面级字段：

• 页面基础字段：resource_type、url、status_code、size 等
• Meta 字段：meta.title、meta.description、meta.canonical 等 -字段：meta.content.*
• 性能字段：page_timing.*
• 检查项字段：checks.*
• 资源传输字段：encoded_size、total_transfer_size、cache_control.* 等

/v3/on_page/keyword_density

字段	类型	说明	运算符
keyword	str	页面或站点中发现的	字符串运算符
frequency	num	出现次数	数值运算符
density	num	密度	数值运算符

/v3/on_page/uncrawlable_resources

字段	类型	说明
url	str	无法抓取的资源 URL
reason	str	无法抓取原因；当前可见值：content_type_inconsistency
status_code	num	返回的 HTTP 状态码
fetch_time	time	抓取时间，UTC
meta.content_type	str	实类型

---

自定义阈值（Thresholds）

OnPage API 支持在创建任务时通过 checks_threshold 对若干检查项的判定阈值进行自定义。 该参数应放在 /v3/on_page/task_post/ 的 POST 请求体中。

请求体示例

[
 {
 "target": "example.com",
 "max_crawl_pages": 100,
 "checks_threshold": {
 "title_too_short": 20,
 "title_too_long": 70,
 "high_loading_time": 4000
 }
 }
]

可自定义的 checks_threshold 字段

字段	类型	说明	默认值
title_too_short	integer	标题过短阈值；当标题长度小于或等于该值时标记	30
title_too_long	integer	标题过长阈值；当标题长度大于或等于该值时标记	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	正文占比过低阈值；plain_text_size / page_size 小于或等于该值时标记	0.1
high_content_rate	float	正文占比过高阈值；比值大于或等于该值时标记	0.9
high_loading_time	integer	页面加载时间过高阈值（毫秒）	3000
high_waiting_time	integer	页面时间（TTFB）过高阈值（毫秒）	1500
low_readability_rate	integer	可读性评分阈值；基于 Flesch–Kincaid	15.0
irrelevant_description	float	description 与正文性过低阈值；小于或等于该值时标记	0.2
irrelevant_title	integer	title 与正文性过低阈值；小于或等于该值时标记	0.3
irrelevant_meta_keywords	integer	keywords 与正文性过低阈值；小于或等于该值时标记	0.6

阈值示例

标题长度阈值

"checks_threshold": {
 "title_too_short": 10,
 "title_too_long": 50
}

页面大小阈值

"checks_threshold": {
 "small_page_size": 2048,
 "large_page_size": 2000000
}

####与性能阈值

"checks_threshold": {
 "low_content_rate": 0.3,
 "high_content_rate": 0.8,
 "high_loading_time": 4000,
 "high_waiting_time": 1000
}

性阈值

"checks_threshold": {
 "irrelevant_description": 0.5,
 "irrelevant_title": 0.1,
 "irrelevant_meta_keywords": 0.5
}

---

请求示例

cURL

curl -X GET "https://api.seermartech.cn/v3/on_page/available_filters" \
 -H "Authorization: Bearer smt_live_YOUR_KEY"

Python

import requests

url = "https://api.seermartech.cn/v3/on_page/available_filters"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY"
}

response = requests.get(url, headers=headers)
print(response.json)

TypeScript

const response = await fetch("https://api.seermartech.cn/v3/on_page/available_filters", {
 method: "GET",
 headers: {
 "Authorization": "Bearer smt_live_YOUR_KEY"
 }
});

const data = await response.json;
console.log(data);

---

响应示例

{
 "version": "0.1.20250724",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0387 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "on_page",
 "function": "available_filters"
 },
 "result": []
 }
 ]
}

错误说明

• 顶层 status_code / status_message：表示整个请求的执行状态；
• tasks[].status_code / tasks[].status_message：表示任务状态；
• 如需处理失败请求，请同时检查：
• 顶层状态码；
• tasks_error 是否大于 0；
• 各任务的 status_code 与 status_message；
• 实错误码与错误信息请参考 /v3/appendix/errors。

使用建议

1. 调用 /v3/on_page/available_filters 获取最新字段单；
2. 按端点匹字段，不要将 pages 的字段用于 links 或 resources；
3. 复杂过滤尽量控制在 8 个条件；
4. 对布尔检查项优使用 checks.* 字段，便于快速定位技术 SEO 问题；
5. 需要调整判定标准时使用 checks_threshold，依赖默认阈值造成误判。

实用场景

• 筛出页面：按 page_timing.waiting_time、page_timing.largest_contentful_paint、checks.high_loading_time 过滤高延迟页面，快速定位影响收录与转化的性能瓶颈。
• 定位薄页面：按 meta.content.plain_text_word_count、checks.low_content_rate、checks.low_character_count 识别不足页面，为补强和页质量治理提供依据。
• 排查标题与描述问题：结合 meta.title_length、meta.description_length、checks.title_too_long、checks.no_description 批量发现标签异常，提高搜索结果点击率。
• 发现损坏资源与坏链：使用 checks.is_broken、broken_links、broken_resources、page_to_status_code 过滤障链接和失效资源，降低抓取浪费并改善用户体验。
• 审计 canonical 与索引异常：按 checks.canonical_to_redirect、checks.recursive_canonical、reason（non_indexable 端点）筛选索引阻塞原因，提升页面收录稳定性。