OnPage解析

接口说明

/v3/on_page/content_parsing 用于解析指定网页的页面，并返回结构化结果：

链接 URL
锚文本
标题层级
正文文本
表格
页眉与页脚
主题块信息
评论、商品、联系方式等页面可见结构化
可选返回 Markdown 版本页面

请求方式： POST接口地址： https://api.seermartech.cn/v3/on_page/content_parsing

使用前提

调用本接口前，通过 /v3/on_page/task_post/ 或 /v3/on_page/task_post 创建对应的 OnPage 任务，并在创建任务时将 enable_content_parsing 设置为 true。

随后，你需要在本接口请求中传该任务的 id。

计费说明

该功能本身不会额外收费。在任务创建后的 30 天，可获取该任务的解析结果。

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

请求体格式

所有 POST 数据需使用 UTF-8 编码的 JSON 格式提交。请求体为 JSON 数组：

json

[
 {
 "url": "https://example.com/page",
 "id": "07131248-1535-0216-1000-17384017ad04",
 "markdown_view": true
 }
]

请求参数

字段名	类型	填	说明
`url`	string	是	需要解析的页面 URL
`id`	string	是	任务 ID，可从 `/v3/on_page/task_post/` 的响应中获取；对应任务的 `enable_content_parsing`须为 `true`
`markdown_view`	boolean	否	是否返回 Markdown 格式页面；设为 `true` 时，响应中会在 `page_as_markdown` 字段返回页面 Markdown；默认值：`false`

参数示例

url：https://example.com/blog/post
id：07131248-1535-0216-1000-17384017ad04

响应结构

接口返回 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	任务结果数组

建议为状态码与异常设计完整的错误处理机制。错误码可参考 /v3/appendix/errors。

`tasks[]` 字段

字段名	类型	说明
`id`	string	任务唯一标识，UUID 格式
`status_code`	integer	任务状态码，范围通常为 `10000-60000`
`status_message`	string	任务状态消息
`time`	string	任务执行时间
`cost`	float	单任务成本，单位 USD
`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	结果项数组

##解析结果项

`items[]` 中的 `content_parsing_element`

字段名	类型	说明
`type`	string	返回项类型，固定为 `content_parsing_element`
`fetch_time`	string	抓取页面的时间，例如：`2022-11-01 10:02:52 +00:00`
`status_code`	integer	页面状态码
`page_content`	object	页面解析后的
`page_as_markdown`	string	页面 Markdown 文本；当请求中 `markdown_view=true` 时返回

`page_content` 字段说明

1) `header`

页面页眉。

字段名	类型	说明
`primary_content`	array	主要
`secondary_content`	array	次要
`table_content`	array	页眉中表格

2) `footer`

页面页脚。

字段名	类型	说明
`primary_content`	array	主要
`secondary_content`	array	次要
`table_content`	array	页脚中表格

3)块通用结构

适用于 primary_content、secondary_content 中的：

字段名	类型	说明
`text`	string	文本
`url`	string	若该文本是链接锚文本，则返回对应页面 URL
`urls`	array	该中发现的链接与锚文本

`urls[]`

字段名	类型	说明
`url`	string	发现的 URL
`anchor_text`	string	URL 对应的锚文本

4) `table_content`

页面中的表格。

字段名	类型	说明
`header`	array	表头
`body`	array	表体
`footer`	array	表尾

表格行结构

字段名	类型	说明
`row_cells`	array	单行单格数组

表格单格结构

字段名	类型	说明
`text`	string	单格文本
`urls`	array	单格中发现的链接与锚文本
`is_header`	boolean	是否属于表头文本

5) `main_topic`

页面主主题块数组。

字段名	类型	说明
`h_title`	string	meta title
`main_title`	string	该块主标题
`author`	string	名称
`language`	string	语言
`level`	string	HTML 层级
`primary_content`	array	主题块主要
`secondary_content`	array	主题块次要
`table_content`	array	主题块中的表格

6) `secondary_topic`

页面次主题块数组，字段结构与 main_topic 相同：

字段名	类型	说明
`h_title`	string	meta title
`main_title`	string	块主标题
`author`	string	名称
`language`	string	语言
`level`	string	HTML 层级
`primary_content`	array	次主题主要
`secondary_content`	array	次主题次要
`table_content`	array	次主题中的表格

7) `ratings`

页面中商品评分信息数组。

字段名	类型	说明
`name`	string	评分名称；该对象中通常固定为 `null`
`rating_value`	integer	评分值
`max_rating_value`	integer	最大评分值
`rating_count`	integer	反馈数量
`relative_rating`	float	相对评分，范围 `0` 到 `1`

8) `offers`

页面中展示的商品数组。

字段名	类型	说明
`name`	string	商品名称
`price`	integer	商品价格
`price_currency`	string	价格币种
`price_valid_until`	integer	价格有效截止时间，UTC 格式，如 `2022-11-01 10:02:52 +00:00`

9) `comments`

页面评论数组，通常为商品评论。

字段名	类型	说明
`rating`	object	用户给商品的评分信息
`title`	string	评论标题
`publish_date`	string	发布时间
`author`	string	评论
`primary_content`	array	评论正文主要

`comments[].rating`

字段名	类型	说明
`name`	string	评分名称；该对象中通常为 `null`
`rating_value`	integer	评分值
`max_rating_value`	integer	最大评分值
`rating_count`	integer	该对象中通常固定为 `null`
`relative rating`	float	相对评分，范围 `0` 到 `1`

10) `contacts`

页面中的联系方式信息。

字段名	类型	说明
`telephones`	array	电话号码数组
`emails`	array	邮箱数组

请求示例

cURL

bash

curl --location --request POST "https://api.seermartech.cn/v3/on_page/content_parsing" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "url": "https://example.com/blog/post",
 "id": "11161551-1535-0216-0000-500b3f307f92",
 "markdown_view": true
 }
]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/on_page/content_parsing"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
data = [
 {
 "url": "https://example.com/blog/post",
 "id": "11161551-1535-0216-0000-500b3f307f92",
 "markdown_view": True
 }
]

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

TypeScript

typescript

import axios from "axios";

const postArray = [
 {
 url: "https://example.com/blog/post",
 id: "11161551-1535-0216-0000-500b3f307f92",
 markdown_view: true
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/on_page/content_parsing",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 },
 data: postArray
})
 .then((response) => {
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error);
 });

响应示例

以下为精简后的响应示例，便于理解结构：

json

{
 "version": "0.1.20240422",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.2569 sec.",
 "cost": 0.000125,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "11161551-1535-0216-0000-500b3f307f92",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.1801 sec.",
 "cost": 0,
 "result_count": 1,
 "path": [
 "v3",
 "on_page",
 "content_parsing"
 ],
 "data": {
 "api": "on_page",
 "function": "content_parsing",
 "url": "https://example.com/blog/post",
 "markdown_view": true
 },
 "result": [
 {
 "crawl_progress": "finished",
 "crawl_status": {},
 "items_count": 1,
 "items": [
 {
 "type": "content_parsing_element",
 "fetch_time": "2022-11-01 10:02:52 +00:00",
 "status_code": 200,
 "page_content": {
 "header": {
 "primary_content": [],
 "secondary_content": [],
 "table_content": null
 },
 "footer": {
 "primary_content": [],
 "secondary_content": [],
 "table_content": null
 },
 "main_topic": [],
 "secondary_topic": [],
 "ratings": null,
 "offers": null,
 "comments": null,
 "contacts": {
 "telephones": [],
 "emails": []
 }
 },
 "page_as_markdown": "# 示例页面标题\n\n这里是页面的 Markdown。"
 }
 ]
 }
 ]
 }
 ]
}

状态码与错误处理

顶层 status_code 表示整个请求状态
tasks[].status_code 表示单个任务状态
页面级状态可参考 items[].status_code

常见成功状态：

状态码	含义
`20000`	请求成功

完整错误码与说明请参考 /v3/appendix/errors。建议重点处理以下：

任务 ID 不存在
对应任务未开启 enable_content_parsing
页面尚未抓取完成，crawl_progress 仍为 in_progress
目标页面返回异常 HTTP 状态码
请求参数缺失或格式错误

使用建议

调用 /v3/on_page/task_post/ 创建任务，并启用 enable_content_parsing=true
使用返回的任务 id 调用本接口
若 crawl_progress 为 in_progress，建议稍后重试
若需要将页面用于摘要、库、知识抽取或 LLM，建议启用 markdown_view=true

实用场景

提取正文结构：解析文章页的主、次、标题层级与表格，便于做 SEO审计与页面质量评估。
识别外链布局：提取页面中的链接 URL 与锚文本，用于分析链结构、导航设计和导流路径。
监控页面模板变化：定期解析页眉、页脚、主与主题块，快速发现模板更新对 SEO分布的影响。
抽取商品与评论信息：从商品页中识别报价、评分、评论和联系方式，支持电商落地页分析与竞品监测。
生成标准化文本：返回 Markdown 格式页面，便于接知识库、分类、摘要生成或大模型处理流程。

OnPage解析 ​

接口说明 ​

使用前提 ​

计费说明 ​

请求体格式 ​

请求参数 ​

参数示例 ​

响应结构 ​

顶层响应字段 ​

tasks[] 字段 ​

result[] 字段 ​

items[] 中的 content_parsing_element ​

page_content 字段说明 ​

1) header ​

2) footer ​

3)块通用结构 ​

urls[] ​

4) table_content ​

表格行结构 ​

表格单格结构 ​

5) main_topic ​

6) secondary_topic ​

7) ratings ​

8) offers ​

9) comments ​

comments[].rating ​

10) contacts ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应示例 ​