按资源查询页面

POST /v3/on_page/pages_by_resource

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

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

本接口用于查询指定资源所在的页面列表，并返回这些页面的抓取状态、页面 SEO 数据、指标、资源错误及性能指标等信息。资源 URL 可通过 /v3/on_page/resources/ 获取。

计费说明

本接口不收取额外费用。任务结果可在提交后的 30 天获取，响应中的 cost 通常为 0。

扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求说明

所有 POST 数据均须使用 UTF-8 编码的 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	否	结果排序规则。最多支持 3 条排序规则，排序值可使用 `asc` 或 `desc`。
`tag`	string	否	用户自定义任务标识，最长 255 个字符。该值会原样返回在响应任务的 `data` 对象中。

`filters` 过滤器

支持以下运算符：

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

like 和 not_like 支持使用 % 匹零个或多个字符。

示例：

json

[
  ["status_code", "=", 200],
  "and",
  ["checks.is_https", "=", true]
]

更多过滤字段和阈值请参考 /v3/on_page/filters_and_thresholds/。

`order_by` 排序

排序规则格式为：

json

[
  "onpage_score,desc",
  "click_depth,asc"
]

多个排序规则使用逗号分隔，单个请求最多设置 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?",
      "limit": 3
    }
  ]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/on_page/pages_by_resource"

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

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

response = requests.post(url, headers=headers, json=payload)
result = response.json()

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

TypeScript

typescript

import axios from "axios";

const response = await axios.post(
  "https://api.seermartech.cn/v3/on_page/pages_by_resource",
  [
    {
      id: "02241700-1535-0216-0000-034137259bc1",
      url: "https://www.etsy.com/about/jobs.workco2018.js?",
      limit: 3
    }
  ],
  {
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json"
    }
  }
);

if (response.data.status_code === 20000) {
  console.log(response.data);
} else {
  console.error(
    `请求失败，状态码：${response.data.status_code}，信息：${response.data.status_message}`
  );
}

响应结构

响应为 JSON 对象，顶层 tasks 数组。

顶层字段

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	通用响应状态码。`20000` 表示成功。完整错误码请参考 `/v3/appendix/errors`。
`status_message`	string	通用状态信息。
`time`	string	请求执行耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务总数。
`tasks_error`	integer	`tasks` 数组中执行失败的任务数。
`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	URL 路径信息。
`data`	object	本次请求中提交的任务参数。
`result`	array	查询结果数组。

`result` 字段

字段	类型	说明
`crawl_progress`	string	抓取状态，可选值：`in_progress`、`finished`。
`crawl_status`	object	抓取会话。
`items_count`	integer	当前结果中的项目数。
`items`	array	页面项目数组。

`crawl_status`

字段	类型	说明
`max_crawl_pages`	integer	创建任务时指定的最大抓取页面数。
`pages_in_queue`	integer	当前抓取队列中的页面数。
`pages_crawled`	integer	已抓取页面数。
`total_items_count`	integer	数据库中符合条件的结果总数。

页面结果字段

每个 items素通常 html_page、content、spell、resource_errors、page_timing、cache_control 和 checks 等对象。

`html_page` 页面基本信息

字段	类型	说明
`resource_type`	string	资源类型。本接口返回页面资源时为 `html`。
`status_code`	integer	页面 HTTP 状态码。
`location`	string	`Location` 响应头中的重定向地址。
`url`	string	页面 URL。
`meta`	object	页面信息。
`title`	string	页面标题。
`charset`	integer	页面编码代码，例如 `65001`。
`follow`	boolean	`meta robots` 是否跟踪页面链接。若为 `false`，通常表示页面 `nofollow` 指令。
`generator`	string	`generator`标签。
`htags`	object	HTML 标题标签信息 `h1`、`h2`、`h3`、`h4` 等。
`description`	string	`description`标签。
`favicon`	string	页面 favicon 地址。
`meta_keywords`	string	`keywords`标签。
`canonical`	string	规范 URL。
`internal_links_count`	integer	页面链接数量。
`external_links_count`	integer	页面外部链接数量。
`images_count`	integer	图片数量。
`images_size`	integer	图片总大小，单位为字节。
`scripts_count`	integer	JavaScript 脚本数量。
`scripts_size`	integer	JavaScript 总大小，单位为字节。
`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（累计布局偏移）指标，用于衡量页面布局稳定性。
`total_dom_size`	integer	页面 DOM 总大小。

`content`指标

字段	类型	说明
`plain_text_size`	integer	页面纯文本总大小，单位为字节。
`plain_text_rate`	float	纯文本占页面大小的比例，即 `plain_text_size / size`。
`plain_text_word_count`	float	页面单词数量。
`automated_readability_index`	float	自动可读性指数。
`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	重复的标签。

`spell` 拼写检查

字段	类型	说明
`hunspell_language_code`	string	拼写检查使用的语言代码。
`misspelled`	array	拼写错误单词数组。
`misspelled[].word`	string	拼写错误的单词。

`resource_errors` 资源错误

字段	类型	说明
`errors`	array	资源错误列表。
`errors[].line`	integer	错误所在的 HTML 行号。
`errors[].message`	string	错误信息。
`warnings`	array	资源警告列表。
`warnings[].line`	integer	警告的 HTML 行号。为 `0` 时表示警告适用于整个页面。
`warnings[].message`	string	警告信息。

常见警告：

Has node with more than 60 childs.：HTML 页面存在同一层级嵌套 60 个子节点的标签。
Has more that 1500 nodes.：DOM 树 1,500 个。
HTML depth more than 32 tags.：HTML DOM 深度 32 层。

`social_media_tags` 社交媒体标签

对象中页面检测到的社交媒体标签及，支持但不限于 Open Graph 和 Twitter Card 标签，例如：

og:title
og:description
og:site_name
og:locale
fb:app_id

`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 资源的时间。

页面 SEO 与资源字段

字段	类型	说明
`onpage_score`	float	页面 SEO 优化评分，满分为 `100`。
`custom_js_response`	string/object/integer	执行自定义 JavaScript 后的结果。字段类型取决于脚本返回值。需在创建任务时 `custom_js`。
`custom_js_client_exception`	string	执行自定义 JavaScript 时发生的错误信息。
`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`。
`content_encoding`	string	编码类型，例如 `gzip`。
`media_type`	string	页面媒体类型，例如 `text/html`。
`server`	string	服务器版本信息。
`is_resource`	boolean	当前页面是否为单独资源。

`cache_control` 缓存信息

字段	类型	说明
`cachable`	boolean	页面是否可缓存。
`ttl`	integer	缓存有效期，单位取决于平台返回值。

`checks` 页面检查结果

字段	类型	说明
`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 声明。
`canonical`	boolean	页面是否设置了规范 URL。
`no_encoding_meta_tag`	boolean	页面是否缺少字符编码标签。
`no_h1_tag`	boolean	页面是否缺少或为空的 H1 标签。
`https_to_http_links`	boolean	HTTPS 页面是否链接到 HTTP 页面。
`has_html_doctype`	boolean	页面是否 HTML DOCTYPE 声明。
`size_greater_than_3mb`	boolean	页面大小是否 3 MB。
`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	页面大小是否 1 MB。
`low_readability_rate`	boolean	Flesch–Kincaid 可读性评分是否低于 15。
`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	页面是否存在同类型重复标签。
`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	指向该页面的站链接中是否同时存在 dofollow 和 nofollow。
`has_links_to_redirects`	boolean	页面是否链接到会发生 `3XX` 重定向的页面。
`canonical_chain`	boolean	canonical 是否形成链式指向。
`canonical_to_redirect`	boolean	canonical 是否指向会发生重定向的页面。
`canonical_to_broken`	boolean	canonical 是否指向返回 `4xx` 或 `5xx` 的页面。
`recursive_canonical`	boolean	canonical 是否形成循环指向。
`from_sitemap`	boolean	页面是否来自站点地图。

除 flash、frame、部分 URL 检查及链接检查外，部分检查项在 canonical 检查结果为 true 时提供。

seo_friendly_url 通常综合以下条件判断：

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

`last_modified` 最后修改时间

字段	类型	说明
`header`	string/null	HTTP Header 中记录的最后修改时间，UTC 格式。
`sitemap`	string/null	站点地图中记录的最后修改时间，UTC 格式。
`meta_tag`	string/null	页面标签中记录的最后修改时间，UTC 格式。

如果没有对应数据，字段值为 null。

响应示例

json

{
  "version": "0.1.20210129",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "3.3012 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "02241700-1535-0216-0000-034137259bc1",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "3.3012 sec.",
      "cost": 0,
      "result_count": 1,
      "data": {
        "api": "on_page",
        "function": "pages_by_resource",
        "url": "https://www.etsy.com/about/jobs.workco2018.js?",
        "limit": 3
      },
      "result": [
        {
          "crawl_progress": "finished",
          "crawl_status": {
            "max_crawl_pages": 3,
            "pages_in_queue": 0,
            "pages_crawled": 3,
            "total_items_count": 1,
            "items_count": 1
          },
          "items": [
            {
              "html_page": {
                "resource_type": "html",
                "status_code": 200,
                "location": null,
                "url": "https://www.etsy.com/about/",
                "meta": {
                  "title": "About Etsy",
                  "charset": 65001,
                  "follow": true,
                  "generator": null,
                  "htags": {
                    "h1": ["About Etsy"],
                    "h2": [],
                    "h4": []
                  },
                  "description": "Etsy is the first e-commerce company to be carbon neutral.",
                  "favicon": "https://www.etsy.com/images/favicon.ico",
                  "meta_keywords": null,
                  "canonical": null,
                  "internal_links_count": 44,
                  "external_links_count": 9,
                  "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.101563
                },
                "content": {
                  "plain_text_size": 10755,
                  "plain_text_rate": 0.083324,
                  "plain_text_word_count": 1413,
                  "automated_readability_index": 19.595897,
                  "coleman_liau_readability_index": 9.494734,
                  "dale_chall_readability_index": 11.023805,
                  "flesch_kincaid_readability_index": 2.203208,
                  "smog_readability_index": 24.268042,
                  "description_to_content_consistency": 0.214286,
                  "title_to_content_consistency": 0.333333,
                  "meta_keywords_to_content_consistency": null,
                  "deprecated_tags": null,
                  "duplicate_meta_tags": []
                },
                "spell": null,
                "resource_errors": {
                  "errors": [],
                  "warnings": []
                },
                "social_media_tags": {
                  "og:site_name": "Etsy",
                  "og:locale": "de_DE",
                  "og:title": "About Etsy",
                  "og:description": "Etsy is the first e-commerce company to be carbon neutral."
                }
              },
              "page_timing": {
                "time_to_interactive": 835,
                "dom_complete": 1073,
                "largest_contentful_paint": 1648.475,
                "first_input_delay": 0.055,
                "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,
                "low_readability_rate": true,
                "duplicate_meta_tags": true,
                "no_image_alt": true,
                "no_image_title": true,
                "seo_friendly_url": false,
                "is_orphan_page": 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"
              }
            }
          ]
        }
      ]
    }
  ]
}

状态码与异常处理

建议客户端同时检查：

HTTP 状态码；
顶层 status_code；
任务级 tasks[].status_code；
tasks_error 是否大于 0；
status_message 中的错误信息。

完整状态码和错误说明请参考 /v3/appendix/errors。

实用场景

定位引用指定 JavaScript、CSS 或图片资源的页面，评估资源变更或失效对站点 SEO 和用户体验的影响。
筛查引用失效资源的页面，结合 broken_resources、HTTP 状态码和 resource_errors 快速安排修复。
分析资源影响范围，根据页面 URL、点击深度、链接数量和页面评分确定优优化页面。
评估引用资源页面的性能表现，使用 LCP、TTI、TTFB、加载时间和阻塞资源指标定位性能瓶颈。
批量检查页面 SEO 质量，利用标题、描述、规范 URL、重复、图片替代文本及 URL 友好度等字段制定修复单。

按资源查询页面 ​

计费说明 ​

请求说明 ​

请求参数 ​

filters 过滤器 ​

order_by 排序 ​

请求示例 ​

curl ​

Python ​

TypeScript ​

响应结构 ​

顶层字段 ​

任务字段 ​

result 字段 ​

crawl_status ​

页面结果字段 ​

html_page 页面基本信息 ​

content指标 ​

spell 拼写检查 ​

resource_errors 资源错误 ​

social_media_tags 社交媒体标签 ​

page_timing 页面性能指标 ​

页面 SEO 与资源字段 ​

cache_control 缓存信息 ​

checks 页面检查结果 ​

last_modified 最后修改时间 ​

响应示例 ​

状态码与异常处理 ​

实用场景 ​

按资源查询页面

计费说明

请求说明

请求参数

`filters` 过滤器

`order_by` 排序

请求示例

curl

Python

TypeScript

响应结构

顶层字段

任务字段

`result` 字段

`crawl_status`

页面结果字段

`html_page` 页面基本信息

`content`指标

`spell` 拼写检查

`resource_errors` 资源错误

`social_media_tags` 社交媒体标签

`page_timing` 页面性能指标

页面 SEO 与资源字段

`cache_control` 缓存信息

`checks` 页面检查结果

`last_modified` 最后修改时间

响应示例

状态码与异常处理

实用场景