OnPage 摘要

POST /v3/on_page/force_stop

本接口用于获取网站扫描任务的整体摘要，并汇总已发现的页面级 SEO 问题。通过返回结果中的问题统计字段，可以进一步调用对应的 OnPage 接口获取 URL 和问题。

请求方法与路径：

http

GET https://api.seermartech.cn/v3/on_page/summary/$id

，$id 为通过 /v3/on_page/task_post/ 创建任务后返回的任务标识。

计费说明

本接口对已提交的扫描任务计费，查询任务摘要本身不重复计费。

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

请求参数

参数	类型	说明
`id`	string	填。任务唯一标识，UUID 格式。例如：`07131248-1535-0216-1000-17384017ad04`。该值来自 `/v3/on_page/task_post/` 的响应。

响应结构

接口返回 JSON 对象 tasks 数组。

顶层字段

字段	类型	说明
`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 格式。
`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	爬取会话。
`crawl_status.max_crawl_pages`	integer	最大爬取页面数，即创建任务时设置的 `max_crawl_pages`。
`crawl_status.pages_in_queue`	integer	当前仍在队列中的页面数。
`crawl_status.pages_crawled`	integer	已爬取页面数。
`crawl_status.crawl_gateway_address`	string	当前爬取会话使用的爬虫 IP 地址。
`crawl_status.crawl_stop_reason`	string	爬取停止原因：`limit_exceeded`（页面数限制）、`empty_queue`（队列为空）、`force_stopped`（通过 `/v3/on_page/force_stop` 停止）、`unexpected_exception`（爬取过程中发生异常）。

`domain_info`：域名信息

字段	类型	说明
`domain_info`	object	域名级信息及爬取信息。
`domain_info.name`	string	域名名称。
`domain_info.cms`	string	检测到的管理系统，通常取自首个返回 HTTP `200` 的随机页面中的 `generator` Meta 标签；无法识别时为 `null`。
`domain_info.ip`	string	域名 IP 地址。
`domain_info.server`	string	检测到的网站服务器版本，取自首个返回 HTTP `200` 的页面响应头 `Server`。
`domain_info.crawl_start`	string	开始爬取时间，UTC 格式：`yyyy-mm-dd hh-mm-ss +00:00`。
`domain_info.crawl_end`	string	爬取结束时间，UTC 格式。当 `crawl_progress` 为 `finished` 时有意义；爬取进行中时为 `null`。
`domain_info.extended_crawl_status`	string	爬取状态及错误原因。可选值：`no_errors`、`site_unreachable`、`invalid_page_status_code`、`forbidden_meta_tag`、`forbidden_robots`、`forbidden_http_header`、`too_many_redirects`、`unknown`。

extended_crawl_status 取值说明：

no_errors：未发现爬取错误。
site_unreachable：爬虫无法访问目标网站，无法获取状态码。
invalid_page_status_code：首个爬取页面的状态码大于或等于 400。
forbidden_meta_tag：首个爬取页面禁止爬取的 Meta 标签。
forbidden_robots：robots.txt 禁止爬取页面。
forbidden_http_header：页面响应头 X-Robots-Tag: noindex。
too_many_redirects：首个爬取页面发生 10 次重定向。
unknown：未知原因。

`ssl_info`：SSL 证书信息

字段	类型	说明
`ssl_info`	object	网站 SSL 证书信息。
`ssl_info.valid_certificate`	boolean	证书是否有效，即未过期、未暂停、未吊销且未失效。
`ssl_info.certificate_issuer`	string	证书颁发机构。
`ssl_info.certificate_subject`	string	与钥的证书主体。
`ssl_info.certificate_version`	string	SSL 证书使用的 X.509 版本。
`ssl_info.certificate_hash`	string	SSL 证书使用的哈希函数版本。
`ssl_info.certificate_expiration_date`	string	证书到期时间，UTC 格式。

`checks`：网站级检查

字段	类型	说明
`checks.sitemap`	boolean	是否检测到网站 Sitemap。
`checks.robots_txt`	boolean	是否存在 `robots.txt`。
`checks.start_page_deny_flag`	boolean	起始页面是否会导致服务器返回 `403 Forbidden` 的禁止标记。
`checks.ssl`	boolean	是否使用 SSL 证书。
`checks.http2`	boolean	是否使用 HTTP/2。
`checks.test_canonicalization`	boolean	通过 IP 访问网站时，服务器是否返回 `301`，用于检查规范化跳转。
`checks.test_www_redirect`	boolean	是否实现 `www` 与非 `www` 域名之间的重定向。
`checks.test_hidden_server_signature`	object	服务器签名隐藏检查结果。值为 `false` 表示爬虫能够访问服务器签名。
`checks.test_page_not_found`	boolean	请求不存在资源时是否返回 `404`。
`checks.test_directory_browsing`	boolean	是否禁止未认证访问目录列表；目录不可访问时为 `true`。
`checks.test_https_redirect`	boolean	HTTP 请求是否重定向到 HTTPS。
`checks.total_pages`	integer	已爬取页面总数。
`checks.total_uncrawlable_resources`	integer	无法爬取的资源总数。当资源类型与爬虫预期类型不一致时，视为不可爬取。
`checks.page_not_found_status_code`	integer	不存在页面返回的状态码，通常建议为 `404`。
`checks.canonicalization_status_code`	integer	通过 IP 访问规范化页面时返回的状态码，通常建议为 `301` 或 `302`。
`checks.directory_browsing_status_code`	integer	访问目录页面时返回的状态码，通常建议为 `403` 或 `401`。
`checks.www_redirect_status_code`	integer	`www` 到非 `www` 的重定向状态码，通常建议为 `301`。
`checks.main_domain`	string	根域名。

`page_metrics`：页面指标

字段	类型	说明
`page_metrics.links_external`	integer	指向网站的外链数量。
`page_metrics.links_internal`	integer	指向目标网站页面的链数量。
`page_metrics.duplicate_title`	integer	Title 重复的页面数。
`page_metrics.duplicate_description`	integer	Description 重复的页面数。
`page_metrics.duplicate_content`	integer	重复的页面数。
`page_metrics.broken_links`	integer	站断链数量。
`page_metrics.broken_resources`	integer	图片及资源中的断链数量。
`page_metrics.links_relation_conflict`	integer	可能存在链接冲突的链接数量。例如同一目标既被 `rel="nofollow"`链引用，也被 dofollow 链接引用。
`page_metrics.redirect_loop`	integer	起点和终点为同一 URL 的重定向链数量。
`page_metrics.onpage_score`	float	网站 OnPage 优化得分，范围为 0–100。`100` 表示未发现严重页面问题和重要警告。该分数与爬取页面数。
`page_metrics.non_indexable`	integer	无法被搜索引擎索引的页面数被 `robots.txt`、HTTP 响应头或 Meta 标签阻止的页面。
`page_metrics.checks`	object	页面级 OnPage 检查结果。

`page_metrics.checks`：页面级检查结果

以下字段均为页面数量统计：

字段	说明
`canonical`	存在 Canonical 标签的页面数。
`duplicate_meta_tags`	同类型 Meta 标签一个的页面数。
`no_description`	Description Meta 标签为空或缺失的页面数。
`frame`	含 `frame`、`iframe` 或 `frameset` 标签的页面数。
`large_page_size`	页面大小 1 MB 的页面数。
`irrelevant_description`	Description 与页面性不足的页面数，性阈值为 `0.2`。
`irrelevant_meta_keywords`	Meta Keywords 与页面性不足的页面数，性阈值为 `0.6`。
`is_https`	使用 HTTPS 的页面数。
`is_http`	使用 HTTP 的页面数。
`title_too_long`	Title过 65 个字符的页面数。
`low_content_rate`	纯文本大小与页面大小之比小于 `0.1` 或大于 `0.9` 的页面数。
`small_page_size`	页面大小小于 1024 字节的页面数。
`no_h1_tag`	H1 标签为空或缺失的页面数。
`recursive_canonical`	Canonical 指向另一页面，而另一页面又指回初始页面的页面数。
`no_favicon`	缺少 Favicon 的页面数。
`no_image_alt`	含缺少 `alt` 属性图片的页面数。
`no_image_title`	含缺少 `title` 属性图片的页面数。
`seo_friendly_url`	URL 不符合 SEO 友好标准的页面数。检查条件：相对路径少于 120 个字符、不含特殊字符、不含动态参数、URL 与页面。任一条件不满足即视为不友好。
`seo_friendly_url_characters_check`	URL 大小写英文字母、数字和连字符的页面数。
`seo_friendly_url_dynamic_check`	URL 不含动态参数的页面数。
`seo_friendly_url_keywords_check`	URL 与 Title Meta 标签一致的页面数。
`seo_friendly_url_relative_length_check`	URL 长度不 120 个字符的页面数。
`title_too_short`	Title 少于 30 个字符的页面数。
`no_content_encoding`	未指定压缩算法的页面数。
`high_waiting_time`	等时间（TTFB） 1.5 秒的页面数。
`high_loading_time`	加载时间 3 秒的页面数。
`is_redirect`	返回 `3XX` 并重定向到页面的页面数。
`is_broken`	响应码小于 `200` 或大于 `400` 的页面数。
`is_4xx_code`	返回 `4XX` 状态码的页面数。
`is_5xx_code`	返回 `5XX` 状态码的页面数。
`is_www`	位于 `www` 子域名下的页面数。
`no_doctype`	缺少 `DOCTYPE` 声明的页面数。
`no_encoding_meta_tag`	缺少编码 Meta 标签的页面数；当 `Content-Type` 未显式声明编码时有意义。
`high_content_rate`	纯文本大小与页面大小之比 `0.9` 的页面数。
`low_character_count`	字符数少于 1024 的页面数。
`high_character_count`	字符数 256,000 的页面数。
`low_readability_rate`	Flesch–Kincaid 可读性测试得分低于 15 的页面数。
`irrelevant_title`	Title 与页面性不足的页面数，性阈值为 `0.3`。
`deprecated_html_tags`	使用已弃用 HTML 标签的页面数。
`duplicate_title_tag`	含多个 Title 标签的页面数。
`no_title`	Title 标签为空或缺失的页面数。
`flash`	含 Flash素的页面数。
`lorem_ipsum`	含 Lorem ipsum 占位文本的页面数。
`has_misspelling`	含拼写错误的页面数。当创建任务时将 `check_spell` 设置为 `true` 时提供。
`canonical_to_broken`	Canonical 指向返回 `404` 页面的位置数量。
`canonical_to_redirect`	Canonical 指向返回 `3XX` 重定向页面的位置数量。
`has_links_to_redirects`	链接指向会发生 `3XX` 重定向页面的页面数。
`is_orphan_page`	没有站页面链接指向的孤立页面数。
`has_meta_refresh_redirect`	使用 Meta Refresh 重定向的页面数。
`meta_charset_consistency`	Meta 声明的字符集与页面字符集不一致的页面数。
`size_greater_than_3mb`	页面大小 3 MB 的页面数。
`has_html_doctype`	含 `DOCTYPE` 声明的页面数。
`https_to_http_links`	HTTPS 页面中链接到 HTTP 页面的位置数量。
`has_render_blocking_resources`	含渲染阻塞资源的页面数。
`redirect_chain`	原始页面与目标页面之间至少经过两次重定向的页面数。
`canonical_chain`	Canonical 指向另一个页面，且该页面又指向第三个 Canonical 页面的位置数量。例如页面 A 指向 B，B 又指向 C。
`is_link_relation_conflict`	可能存在链接冲突的页面数。例如同一页面同时收到至少一个 `rel="nofollow"`链和至少一个 dofollow 链接。

> 说明：duplicate_meta_tags、no_description、large_page_size、irrelevant_description、irrelevant_meta_keywords、title_too_long、low_content_rate、small_page_size、no_h1_tag、no_favicon、no_image_alt、no_image_title、seo_friendly_url、title_too_short、no_encoding_meta_tag、high_content_rate、low_character_count、high_character_count、low_readability_rate、irrelevant_title、deprecated_html_tags、duplicate_title_tag、no_title、lorem_ipsum、has_meta_refresh_redirect、size_greater_than_3mb、https_to_http_links 和 has_render_blocking_resources 等字段，通常在创建任务时启用相应的 canonical 检查后提供。

请求示例

cURL

bash

id="07281559-0695-0216-0000-c269be8b7592"

curl --location --request GET \
  "https://api.seermartech.cn/v3/on_page/summary/${id}" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json"

PHP

php

<?php
require('RestClient.php');

$api_url = 'https://api.seermartech.cn/';
$client = new RestClient($api_url, null, null, null, [
    'Authorization: Bearer smt_live_YOUR_KEY'
]);

try {
    // 获取指定任务的 OnPage 摘要
    // GET /v3/on_page/summary/$id
    $id = "07281559-0695-0216-0000-c269be8b7592";
    $result = $client->get('/v3/on_page/summary/' . $id);
    print_r($result);
} catch (RestClientException $e) {
    echo "HTTP code: {$e->getHttpCode()}\n";
    echo "Error code: {$e->getCode()}\n";
    echo "Message: {$e->getMessage()}\n";
}
?>

TypeScript

typescript

import axios from "axios";

const taskId = "02231934-2604-0066-2000-570459f04879";

axios.get(
  `https://api.seermartech.cn/v3/on_page/summary/${taskId}`,
  {
    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);
});

Python

python

import requests

task_id = "07281559-0695-0216-0000-c269be8b7592"

response = requests.get(
    f"https://api.seermartech.cn/v3/on_page/summary/{task_id}",
    headers={
        "Authorization": "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
    },
)

if response.ok:
    result = response.json()
    print(result)
else:
    print(f"请求失败，HTTP 状态码：{response.status_code}")
    print(response.text)

响应示例

json

{
  "version": "0.1.20221214",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "1.0297 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "07281559-0695-0216-0000-c269be8b7592",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "1.0297 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "on_page",
        "summary",
        "07281559-0695-0216-0000-c269be8b7592"
      ],
      "data": {
        "api": "on_page",
        "function": "summary",
        "target": "example.com",
        "max_crawl_pages": 1000,
        "enable_www_redirect_check": true
      },
      "result": [
        {
          "crawl_progress": "finished",
          "crawl_status": {
            "max_crawl_pages": 1000,
            "pages_in_queue": 0,
            "pages_crawled": 1000,
            "crawl_gateway_address": "192.0.2.1",
            "crawl_stop_reason": "limit_exceeded"
          },
          "domain_info": {
            "name": "example.com",
            "cms": null,
            "ip": "192.0.2.1",
            "server": "nginx",
            "crawl_start": "2024-01-15 12:00:00 +00:00",
            "crawl_end": "2024-01-15 12:05:00 +00:00",
            "extended_crawl_status": "no_errors"
          },
          "ssl_info": {
            "valid_certificate": true,
            "certificate_issuer": "Example Certificate Authority",
            "certificate_subject": "example.com",
            "certificate_version": "3",
            "certificate_hash": "sha256",
            "certificate_expiration_date": "2025-01-15 12:00:00 +00:00"
          },
          "checks": {
            "sitemap": true,
            "robots_txt": true,
            "ssl": true,
            "http2": true,
            "test_https_redirect": true,
            "total_pages": 1000,
            "total_uncrawlable_resources": 0,
            "page_not_found_status_code": 404,
            "canonicalization_status_code": 301,
            "directory_browsing_status_code": 403,
            "www_redirect_status_code": 301,
            "main_domain": "example.com"
          },
          "page_metrics": {
            "links_external": 120,
            "links_internal": 2500,
            "duplicate_title": 3,
            "duplicate_description": 5,
            "duplicate_content": 1,
            "broken_links": 2,
            "broken_resources": 4,
            "redirect_loop": 0,
            "onpage_score": 86.5,
            "non_indexable": 12,
            "checks": {
              "canonical": 980,
              "no_description": 8,
              "title_too_long": 4,
              "broken_links": 2,
              "is_https": 1000,
              "is_http": 0,
              "is_4xx_code": 3,
              "is_5xx_code": 0,
              "is_orphan_page": 6
            }
          }
        }
      ]
    }
  ]
}

错误处理

建议同时检查顶层和任务级状态：

顶层 status_code 不等于成功码时，应根据 status_message 处理请求错误。
tasks_error 大于 0 时，应逐项检查 tasks 中的 status_code 和 status_message。
任务级 result 为 null 或任务状态码处于错误范围时，不应继续读取摘要字段。
当 crawl_progress 为 in_progress 时，crawl_end 可能为 null，部分统计数据也可能尚未最终完成。

实用场景

汇总网站技术健康度：读取 onpage_score、SSL、HTTP/2、Sitemap、Robots.txt 和重定向状态，为 SEO 审计报告生成总体评分。
定位站技术问题：根据 broken_links、is_4xx_code、is_5xx_code、redirect_chain 和 redirect_loop 统计结果，优修复影响抓取和用户访问的问题。
优化页面数据：利用 duplicate_title、duplicate_description、no_title、no_description 和 title_too_long 识别需要批量优化的页面。
改善网站索引覆盖：通过 non_indexable、is_orphan_page、canonical_to_broken 和 canonical_chain 发现阻碍搜索引擎索引的页面结构问题。
制定性能优化计划：结合 large_page_size、size_greater_than_3mb、high_waiting_time、high_loading_time 和 has_render_blocking_resources，确定页面速度优化优级。

OnPage 摘要 ​

计费说明 ​

请求参数 ​

响应结构 ​

顶层字段 ​

tasks 数组中的任务字段 ​

result 字段说明 ​

爬取状态 ​

domain_info：域名信息 ​

ssl_info：SSL 证书信息 ​

checks：网站级检查 ​

page_metrics：页面指标 ​

page_metrics.checks：页面级检查结果 ​

请求示例 ​

cURL ​

PHP ​

TypeScript ​

Python ​

响应示例 ​

错误处理 ​

实用场景 ​