按资源反查页面

接口说明

该接口用于返回某个指定资源的页面列表，并同时给出这些页面的详细页面级分析数据。

例如，你可以通过 /v3/on_page/resources/ 获取某个站点中出现过的 JS、CSS、图片等资源 URL，再调用本接口反查：这个资源被哪些页面引用。

接口地址

POST https://api.seermartech.cn/v3/on_page/pages_by_resource

计费说明

调用本接口不额外收费。在任务有效期，你可以在接下来的 30 天获取结果。

响应中的 cost 字段通常为 0，扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求格式

请求方法：POST
Content-Type：application/json
请求体格式：JSON 数组 [{ ... }]

请求参数

字段名	类型	说明
`id`	string	填。任务 ID，可在 `/v3/on_page/task_post/` 的响应中获取。示例：`07131248-1535-0216-1000-17384017ad04`
`url`	string	填。资源 URL，可在 `/v3/on_page/resources/` 的响应中获取。示例：`https://ajax.googleapis.com/ajax/libs/jquery/1.12.4/jquery.min.js`
`limit`	integer	可选。返回页面数量上限。默认 `100`，最大 `1000`
`offset`	integer	可选。结果偏移量。默认 `0`，最大 `2000000`。例如设置为 `10` 时，将跳过前 10 条结果并从后续页面开始返回
`filters`	array	可选。结果过滤条件数组，最多支持 `8` 个过滤条件。多个条件之间需要使用逻辑运算符 `and` / `or`
`order_by`	array	可选。结果排序规则。可使用与 `filters` 相同的字段进行排序
`tag`	string	可选。自定义任务标识，最长 `255` 个字符。可用于请求与结果的业务，返回时会出现在响应的 `data` 对象中

`filters` 支持的运算符

支持以下运算符：

regex
not_regex
<
<=
>
>=
=
<>
in
not_in
like
not_like

说明：

like 和 not_like 支持使用 % 匹任意长度字符串；
可组合多个条件，但单次请求最多 8 个过滤条件；
可用字段范围请参考本平台的 OnPage 过滤字段说明。

`order_by` 排序说明

排序方向支持：
asc：升序
desc：降序
单次请求最多可设置 3 条排序规则
多条排序规则之间使用逗号分隔

请求示例

curl

bash

curl --location --request POST "https://api.seermartech.cn/v3/on_page/pages_by_resource" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "id": "02241700-1535-0216-0000-034137259bc1",
 "url": "https://www.etsy.com/about/jobs.workco2018.js?"
 }
]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/on_page/pages_by_resource"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
data = [
 {
 "id": "02241700-1535-0216-0000-034137259bc1",
 "url": "https://www.etsy.com/about/jobs.workco2018.js?"
 }
]

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

TypeScript

typescript

import axios from "axios";

const postData = [
 {
 id: "02241700-1535-0216-0000-034137259bc1",
 url: "https://www.etsy.com/about/jobs.workco2018.js?"
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/on_page/pages_by_resource",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 },
 data: postData
})
 .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	任务结果数组

建议对 status_code、status_message 设计统一异常处理机制。

`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[]` 字段

字段名	类型	说明
`crawl_progress`	string	抓取会话状态，可能值：`in_progress`、`finished`
`crawl_status`	object	抓取会话
`crawl_status.max_crawl_pages`	integer	抓取页面上限，即创建任务时设置的 `max_crawl_pages`
`crawl_status.pages_in_queue`	integer	当前抓取队列中的页面数
`crawl_status.pages_crawled`	integer	已抓取页面数
`total_items_count`	integer	数据库中符合条件的总条目数
`items_count`	integer	当前返回的条目数
`items`	array	页面结果列表

`items[]` 页面结果字段

以下字段主要适用于 resource_type = "html" 的页面结果。

基础字段

字段名	类型	说明
`resource_type`	string	返回资源类型，固定为 `html`
`status_code`	integer	页面状态码
`location`	string	`Location` 响应头，表示重定向目标 URL
`url`	string	页面 URL
`meta`	object	页面属性集合，字段依赖 `resource_type`

`meta` 页面属性字段

字段名	类型	说明
`title`	string	页面标题
`charset`	integer	字符编码编号，例如 `65001`
`follow`	boolean	页面 `meta robots` 是否爬虫跟踪页面中的链接；若为 `false`，通常表示 `nofollow`
`generator`	string	`generator` meta 标签
`htags`	object	页面标题标签集合，如 `h1`、`h2`、`h3` 等
`description`	string	`description` meta 标签
`favicon`	string	页面 favicon 地址
`meta_keywords`	string	`keywords` meta 标签
`canonical`	string	canonical 页面地址
`internal_links_count`	integer	站链接数量
`external_links_count`	integer	站外链接数量
`images_count`	integer	图片数量
`images_size`	integer	图片总大小，单位字节
`scripts_count`	integer	脚本数量
`scripts_size`	integer	脚本总大小，单位字节
`stylesheets_count`	integer	样式表数量
`stylesheets_size`	integer	样式表总大小，单位字节
`title_length`	integer	`title` 标签字符长度
`description_length`	integer	`description` 标签字符长度
`render_blocking_scripts_count`	integer	阻塞渲染的脚本数量
`render_blocking_stylesheets_count`	integer	阻塞渲染的样式表数量
`cumulative_layout_shift`	float	CLS 指标，用于衡量页面布局稳定性

`meta.content`分析字段

字段名	类型	说明
`plain_text_size`	integer	页面纯文本总大小，单位字节
`plain_text_rate`	float	纯文本占比，即 `plain_text_size / size`
`plain_text_word_count`	float	页面词数
`automated_readability_index`	float	Automated Readability Index 可读性指标
`coleman_liau_readability_index`	float	Coleman–Liau 可读性指标
`dale_chall_readability_index`	float	Dale–Chall 可读性指标
`flesch_kincaid_readability_index`	float	Flesch–Kincaid 可读性指标
`smog_readability_index`	float	SMOG 可读性指标
`description_to_content_consistency`	float	`description` 与正文一致性，取值 `0` 到 `1`
`title_to_content_consistency`	float	`title` 与正文一致性，取值 `0` 到 `1`
`meta_keywords_to_content_consistency`	float	`keywords` 与正文一致性，取值 `0` 到 `1`

页面分析字段

字段名	类型	说明
`deprecated_tags`	array	页面中过时的 HTML 标签
`duplicate_meta_tags`	array	重复的 meta 标签
`spell`	object	拼写检查结果
`spell.hunspell_language_code`	string	拼写检查语言代码
`spell.misspelled`	array	拼写错误词列表
`resource_errors`	object	资源错误与告警
`resource_errors.errors`	array	资源错误列表
`resource_errors.errors[].line`	integer	错误所在行号
`resource_errors.errors[].message`	string	错误信息
`resource_errors.warnings`	array	资源告警列表
`resource_errors.warnings[].line`	integer	告警行号；若为 `0` 表示针对整页
`resource_errors.warnings[].message`	string	告警信息
`social_media_tags`	object	页面上的社交媒体标签，如 Open Graph、Twitter Card
`page_timing`	object	页面加载性能指标
`onpage_score`	float	页面 OnPage 优化评分，满分 `100`
`total_dom_size`	integer	页面 DOM 总大小
`custom_js_response`	string/object/integer	自定义 JS 执行结果。在 `/v3/on_page/task_post/` 中设置 `custom_js` 时返回
`custom_js_client_exception`	string	自定义 JS 执行异常信息
`broken_resources`	boolean	页面是否损坏资源
`broken_links`	boolean	页面是否失效链接
`duplicate_title`	boolean	页面标题是否重复
`duplicate_description`	boolean	页面描述是否重复
`duplicate_content`	boolean	页面是否重复
`click_depth`	integer	点击深度，即从首页到达该页面所需点击次数
`size`	integer	页面资源大小，单位字节
`encoded_size`	integer	编码后页面大小，单位字节
`total_transfer_size`	integer	压缩传输大小
`fetch_time`	string	抓取时间，UTC 格式：`yyyy-mm-dd hh-mm-ss +00:00`
`cache_control`	object	缓存控制信息
`cache_control.cachable`	boolean	页面是否可缓存
`cache_control.ttl`	integer	缓存 TTL
`content_encoding`	string	编码类型
`media_type`	string	媒体类型
`server`	string	服务器类型/版本
`is_resource`	boolean	是否为单一资源
`last_modified`	object	资源最近修改时间信息
`last_modified.header`	string	响应头中的最后修改时间
`last_modified.sitemap`	string	站点地图中的最后修改时间
`last_modified.meta_tag`	string	meta 标签中的最后修改时间

`page_timing` 字段说明

字段名	类型	说明
`time_to_interactive`	integer	TTI，可交互时间，单位毫秒
`dom_complete`	integer	页面及子资源下载完成耗时，单位毫秒
`largest_contentful_paint`	float	LCP，最大绘制时间，单位毫秒
`first_input_delay`	float	FID，首次延迟，单位毫秒
`connection_time`	integer	建立服务器连接耗时，单位毫秒
`time_to_secure_connection`	integer	建立连接耗时，单位毫秒
`request_sent_time`	integer	请求发送耗时，单位毫秒
`waiting_time`	integer	首字节时间 TTFB，单位毫秒
`download_time`	integer	下载响应耗时，单位毫秒
`duration_time`	integer	完整响应总耗时，单位毫秒
`fetch_start`	integer	开始下载 HTML 资源的时间
`fetch_end`	integer	完成下载 HTML 资源的时间

`checks` 页面检查字段

checks 对象大量页面级 SEO 与技术检查结果，常见字段如下：

字段名	类型	说明
`no_content_encoding`	boolean	页面未启用压缩
`high_loading_time`	boolean	页面加载时间是否 3 秒
`is_redirect`	boolean	页面是否发生 `3XX` 重定向
`is_4xx_code`	boolean	页面是否返回 `4xx` 状态码
`is_5xx_code`	boolean	页面是否返回 `5xx` 状态码
`is_broken`	boolean	页面是否异常，通常指响应码小于 `200` 或大于 `400`
`is_www`	boolean	页面是否位于 `www` 子域
`is_https`	boolean	页面是否使用 `https`
`is_http`	boolean	页面是否使用 `http`
`high_waiting_time`	boolean	页面时间（TTFB）是否 1.5 秒
`no_doctype`	boolean	页面是否缺少 `<!DOCTYPE HTML>` 声明
`canonical`	boolean	页面是否为 canonical 页面
`no_encoding_meta_tag`	boolean	页面是否缺少编码 meta 标签
`no_h1_tag`	boolean	页面是否缺少或为空 `h1` 标签
`https_to_http_links`	boolean	HTTPS 页面是否链接到 HTTP 页面
`has_html_doctype`	boolean	页面是否 HTML DOCTYPE 声明
`size_greater_than_3mb`	boolean	页面大小是否 3MB
`meta_charset_consistency`	boolean	页面声明编码与编码是否不一致
`has_meta_refresh_redirect`	boolean	页面是否使用 meta refresh 跳转
`has_render_blocking_resources`	boolean	页面是否存在阻塞渲染资源
`redirect_chain`	boolean	页面是否存在重定向链
`low_content_rate`	boolean	文本占比是否低于 `0.1`
`high_content_rate`	boolean	文本占比是否高于 `0.9`
`low_character_count`	boolean	页面字符数是否少于 `1024`
`high_character_count`	boolean	页面字符数是否 `256000`
`small_page_size`	boolean	页面是否小于 `1024` 字节
`large_page_size`	boolean	页面是否 `1MB`
`low_readability_rate`	boolean	页面可读性是否偏低
`irrelevant_description`	boolean	`description` 是否与页面不，阈值 `0.2`
`irrelevant_title`	boolean	`title` 是否与页面不，阈值 `0.3`
`irrelevant_meta_keywords`	boolean	`keywords` 是否与页面不，阈值 `0.6`
`title_too_long`	boolean	`title` 是否 `65` 字符
`title_too_short`	boolean	`title` 是否短于 `30` 字符
`deprecated_html_tags`	boolean	页面是否过时 HTML 标签
`duplicate_meta_tags`	boolean	页面是否存在重复 meta 标签
`duplicate_title_tag`	boolean	页面是否多个 `title` 标签
`no_image_alt`	boolean	页面图片是否缺少 `alt`
`no_image_title`	boolean	页面图片是否缺少 `title`
`no_description`	boolean	页面是否缺少 `description`
`no_title`	boolean	页面是否缺少 `title`
`no_favicon`	boolean	页面是否缺少 favicon
`seo_friendly_url`	boolean	URL 是否满足 SEO 友好规则
`flash`	boolean	页面是否 Flash
`frame`	boolean	页面是否 `frame` / `iframe` / `frameset`
`lorem_ipsum`	boolean	页面是否占位文本 `lorem ipsum`
`has_misspelling`	boolean	页面是否存在拼写错误
`seo_friendly_url_characters_check`	boolean	URL 字符是否只拉丁字母、数字和连字符
`seo_friendly_url_dynamic_check`	boolean	URL 是否不含动态参数
`seo_friendly_url_keywords_check`	boolean	URL 是否与标题语义一致
`seo_friendly_url_relative_length_check`	boolean	URL 是否不 `120` 字符
`is_orphan_page`	boolean	是否为孤立页面，即没有站页面指向它
`is_link_relation_conflict`	boolean	是否同时收到 `nofollow` 和 dofollow 的站链接
`has_links_to_redirects`	boolean	页面是否指向会重定向的链接
`canonical_chain`	boolean	canonical 是否形成链式指向
`canonical_to_redirect`	boolean	canonical 是否指向重定向页面
`canonical_to_broken`	boolean	canonical 是否指向 `4xx/5xx` 页面
`recursive_canonical`	boolean	canonical 是否形成循环引用

说明：原始返回中部分 checks 字段在页面满足 canonical 检查条件时可用。

响应示例

json

{
 "version": "0.1.20210129",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "3.3012 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "on_page",
 "function": "pages_by_resource",
 "url": "https://www.etsy.com/about/jobs.workco2018.js?",
 "limit": 3
 },
 "result": [
 {
 "items": [
 {
 "meta": {
 "description": "Etsy is the first e-commerce company to be carbon neutral, offsetting 100% of carbon emissions from shipping. That means the negative environmental impact of every delivery is balanced with something good.",
 "favicon": "https://www.etsy.com/images/favicon.ico",
 "meta_keywords": null,
 "canonical": null,
 "internal_links_count": 44,
 "external_links_count": 9,
 "inbound_links_count": 49,
 "images_count": 2,
 "images_size": 0,
 "scripts_count": 10,
 "scripts_size": 405515,
 "stylesheets_count": 4,
 "stylesheets_size": 130964,
 "title_length": 55,
 "description_length": 205,
 "render_blocking_scripts_count": 4,
 "render_blocking_stylesheets_count": 10,
 "cumulative_layout_shift": 0.10156329069412295,
 "content": {
 "plain_text_size": 10755,
 "plain_text_rate": 0.08332429459069991,
 "plain_text_word_count": 1413,
 "automated_readability_index": 19.595897435897434,
 "coleman_liau_readability_index": 9.494734111543448,
 "dale_chall_readability_index": 11.023804479285753,
 "flesch_kincaid_readability_index": 2.2032082312591967,
 "smog_readability_index": 24.268042663318734,
 "description_to_content_consistency": 0.2142857164144516,
 "title_to_content_consistency": 0.3333333432674408,
 "meta_keywords_to_content_consistency": null
 },
 "deprecated_tags": null,
 "duplicate_meta_tags": [],
 "spell": null,
 "resource_errors": {
 "errors": [],
 "warnings": []
 },
 "social_media_tags": {
 "fb:app_id": "89186614300",
 "og:site_name": "Etsy",
 "og:locale": "de_DE",
 "og:title": "Etsy Carbon-Offset Shipping: Delivering a world of good",
 "og:description": "Etsy is the first e-commerce company to be carbon neutral, offsetting 100% of carbon emissions from shipping. That means the negative environmental impact of every delivery is balanced with something good."
 }
 },
 "page_timing": {
 "time_to_interactive": 835,
 "dom_complete": 1073,
 "largest_contentful_paint": 1648.4750006347895,
 "first_input_delay": 0.0550001859664917,
 "connection_time": 9,
 "time_to_secure_connection": 10,
 "request_sent_time": 0,
 "waiting_time": 452,
 "download_time": 6,
 "duration_time": 477,
 "fetch_start": 0,
 "fetch_end": 477
 },
 "onpage_score": 88.36,
 "total_dom_size": 3627018,
 "custom_js_response": null,
 "custom_js_client_exception": null,
 "broken_resources": false,
 "broken_links": false,
 "duplicate_title": false,
 "duplicate_description": false,
 "duplicate_content": false,
 "click_depth": 1,
 "size": 129259,
 "encoded_size": 33427,
 "total_transfer_size": 34948,
 "fetch_time": "2021-02-24 17:04:54 +00:00",
 "cache_control": {
 "cachable": false,
 "ttl": 0
 },
 "checks": {
 "no_content_encoding": false,
 "high_loading_time": false,
 "is_redirect": false,
 "is_4xx_code": false,
 "is_5xx_code": false,
 "is_broken": false,
 "is_www": true,
 "is_https": true,
 "is_http": false,
 "high_waiting_time": false,
 "no_doctype": false,
 "canonical": true,
 "no_encoding_meta_tag": true,
 "no_h1_tag": false,
 "https_to_http_links": true,
 "has_html_doctype": true,
 "size_greater_than_3mb": false,
 "meta_charset_consistency": true,
 "has_meta_refresh_redirect": false,
 "has_render_blocking_resources": true,
 "redirect_chain": false,
 "low_content_rate": true,
 "high_content_rate": false,
 "low_character_count": false,
 "high_character_count": false,
 "small_page_size": false,
 "large_page_size": false,
 "low_readability_rate": true,
 "irrelevant_description": false,
 "irrelevant_title": false,
 "irrelevant_meta_keywords": false,
 "title_too_long": false,
 "title_too_short": false,
 "deprecated_html_tags": false,
 "duplicate_meta_tags": true,
 "duplicate_title_tag": false,
 "no_image_alt": true,
 "no_image_title": true,
 "no_description": false,
 "no_title": false,
 "no_favicon": false,
 "seo_friendly_url": false,
 "flash": false,
 "frame": false,
 "lorem_ipsum": false,
 "seo_friendly_url_characters_check": true,
 "seo_friendly_url_dynamic_check": false,
 "seo_friendly_url_keywords_check": false,
 "seo_friendly_url_relative_length_check": true,
 "is_orphan_page": false,
 "is_link_relation_conflict": false,
 "has_links_to_redirects": false,
 "canonical_chain": false,
 "canonical_to_redirect": false,
 "canonical_to_broken": false,
 "recursive_canonical": false,
 "from_sitemap": false
 },
 "content_encoding": "gzip",
 "media_type": "text/html",
 "server": "Apache",
 "is_resource": false,
 "last_modified": {
 "header": "2021-10-21 14:11:10 +00:00",
 "sitemap": null,
 "meta_tag": "2021-03-15 00:00:00 +00:00"
 }
 }
 ]
 }
 ]
 }
 ]
}

错误处理

顶层 status_code 表示整个请求的处理状态；
tasks[].status_code 表示单个任务的执行状态；
当 tasks_error > 0 时，说明至少有一个任务执行失败；
请同时检查：
status_code
status_message
tasks[].status_code
tasks[].status_message

常见处理建议：

若 status_code 非成功状态，按整请求失败处理；
若顶层成功但某个 tasks[].status_code 异常，则按单任务失败重试或记录；
对 id、url 是否有效做前置校验，无效资源地址导致空结果或任务错误。

使用建议

通过 /v3/on_page/task_post/ 建立抓取任务并完成页面抓取；
再通过 /v3/on_page/resources/ 获取站点已发现的资源 URL；
最后使用本接口按资源 URL 反查对应页面列表；
如需聚焦问题页面，可结合 filters 过滤：

阻塞渲染资源页面
存在 4xx/5xx 的页面
低占比页面
高加载耗时页面

如需稳定分页拉取，合 limit + offset 使用。

实用场景

反查资源引用范围：某个 JS、CSS 或图片资源 URL，快速定位所有引用该资源的页面，便于评估资源变更影响范围。
排查异常静态资源：针对失效脚本、错误样式表或过期图片资源，找出受影响页面，提升修复效率。
识别性能问题来源：结合 render_blocking_scripts_count、page_timing 等字段，定位哪些页面因某类资源导致加载变。
评估第三方资源使用：统计某个外部资源被哪些页面调用，用于治理第三方脚本、标签管理器或广告代码。
支持站 SEO 技术审计：筛选引用特定资源的页面后，进一步检查 onpage_score、checks、质量和索引友好性。

按资源反查页面 ​

接口说明 ​

接口地址 ​

计费说明 ​

请求格式 ​

请求参数 ​

filters 支持的运算符 ​

order_by 排序说明 ​

请求示例 ​

curl ​

Python ​

TypeScript ​

响应结构 ​

顶层字段 ​

tasks[] 字段 ​

result[] 字段 ​

items[] 页面结果字段 ​

基础字段 ​

meta 页面属性字段 ​

meta.content分析字段 ​

页面分析字段 ​

page_timing 字段说明 ​

checks 页面检查字段 ​

响应示例 ​

错误处理 ​

使用建议 ​

实用场景 ​