OnPage解析

POST /v3/on_page/content_parsing

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

text

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

本接口用于解析指定网页，并返回结构化页面数据链接 URL、锚文本、标题、正文、表格、主题、评分、商品、评论和联系方式等。

> 使用前，请通过 /v3/on_page/task_post/ 创建任务，并将请求参数 enable_content_parsing 设置为 true。随后使用任务返回的 id 调用本接口获取解析结果。

计费说明

本接口不额外收取费用。任务结果可在任务创建后的 30 天获取。

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

请求说明

请求体使用 UTF-8 编码的 JSON 数组格式。所有任务参数都放在数组中。

请求参数

参数	类型	填	说明
`url`	string	是	解析页面的 URL。
`id`	string	是	任务 ID，由 `/v3/on_page/task_post/` 返回。创建任务时将 `enable_content_parsing` 设置为 `true`。
`markdown_view`	boolean	否	是否以 Markdown 格式返回页面。设置为 `true` 后，结果将写 `page_as_markdown` 字段。默认值为 `false`。

请求示例

json

[
  {
    "url": "https://example.com/article",
    "id": "11161551-1535-0216-0000-500b3f307f92",
    "markdown_view": true
  }
]

响应说明

接口返回 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`	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	解析结果数组。

结果字段

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

`items` 字段

字段	类型	说明
`type`	string	返回项目类型，固定为 `content_parsing_element`。
`fetch_time`	string	页面抓取时间，例如 `2022-11-01 10:02:52 +00:00`。
`status_code`	integer	页面 HTTP 状态码。
`page_content`	object	页面解析。
`page_as_markdown`	string	页面 Markdown。当请求参数 `markdown_view` 为 `true` 时返回。

`page_content` 页面

页面头部与底部

header 和 footer 对象用于描述页面头部和底部，结构相同，均可能以下字段：

字段	类型	说明
`primary_content`	array	页面主要。
`secondary_content`	array	页面次要。
`table_content`	array	页面中的表格。

primary_content 和 secondary_content 均为数组，每个：

字段	类型	说明
`text`	string	文本。
`url`	string	当文本是链接锚文本时，对应的页面 URL。
`urls`	array	当前中发现的 URL 和锚文本。

urls 数组中的：

字段	类型	说明
`url`	string	发现的链接 URL。
`anchor_text`	string	链接锚文本。

表格

table_content 用于表示页面中的表格，可能 header、body 和 footer 三部分。每部分由行组成，每行 row_cells 单格数组。

行单格字段

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

urls 中的字段为：

字段	类型	说明
`url`	string	单格中的链接 URL。
`anchor_text`	string	链接锚文本。

页面主题

`main_topic`

main_topic 为页面主要主题数组。每个主题对象：

字段	类型	说明
`h_title`	string	页面标题。
`main_title`	string	区块的主标题。
`author`	string	。
`language`	string	语言。
`level`	string	HTML 标题层级。
`primary_content`	array	主题下的主要。
`secondary_content`	array	主题下的次要。
`table_content`	array	主题下的表格。

`secondary_topic`

secondary_topic 为页面次要主题数组，字段结构与 main_topic 相同。

评分、商品与评论

`ratings`

ratings 为页面中产品评分信息的数组。

字段	类型	说明
`name`	string \| null	评分名称。当前对象中未使用，通常为 `null`。
`rating_value`	integer	评分值。
`max_rating_value`	integer	评分最大值。
`rating_count`	integer	评价数量。
`relative_rating`	float	相对评分，取值范围为 `0` 至 `1`。

`offers`

offers 为页面中展示的商品数组。

字段	类型	说明
`name`	string	商品名称。
`price`	integer	商品价格。
`price_currency`	string	商品价格的货币单位。
`price_valid_until`	string	商品价格有效期，UTC 格式：`yyyy-mm-dd hh-mm-ss +00:00`。

`comments`

comments 为页面中的评论数组，每条评论可能：

字段	类型	说明
`rating`	object	评论的商品评分。
`title`	string	评论标题。
`publish_date`	string	评论发布日期。
`author`	string	评论。
`primary_content`	array	评论正文。

评论中的 rating 对象字段：

字段	类型	说明
`name`	string \| null	评分名称，通常为 `null`。
`rating_value`	integer	评分值。
`max_rating_value`	integer	评分最大值。
`rating_count`	integer \| null	评价数量，当前对象中通常为 `null`。
`relative_rating`	float	相对评分，取值范围为 `0` 至 `1`。

联系方式

`contacts`

contacts 为页面中识别出的联系信息。

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

Markdown

当请求参数中设置：

json

{
  "markdown_view": true
}

接口会在结果中返回 page_as_markdown 字段。该字段页面的 Markdown 格式文本，适合用于提取、文本分析、知识库构建和审核。

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/article",
      "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",
}

post_data = [
    {
        "url": "https://example.com/article",
        "id": "11161551-1535-0216-0000-500b3f307f92",
        "markdown_view": True,
    }
]

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

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

TypeScript 示例

typescript

import axios from "axios";

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

axios
  .post(
    "https://api.seermartech.cn/v3/on_page/content_parsing",
    postData,
    {
      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);
  });

响应示例

以下示例展示主要响应结构：

json

{
  "version": "0.1.20240422",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.2569 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "11161551-1535-0216-0000-500b3f307f92",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.2411 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "on_page",
        "content_parsing"
      ],
      "data": {
        "url": "https://example.com/article",
        "id": "11161551-1535-0216-0000-500b3f307f92",
        "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": [
                    {
                      "text": "页面标题",
                      "url": null,
                      "urls": []
                    }
                  ],
                  "secondary_content": [],
                  "table_content": []
                },
                "primary_content": [
                  {
                    "text": "这是页面正文。",
                    "url": null,
                    "urls": [
                      {
                        "url": "https://example.com/related",
                        "anchor_text": ""
                      }
                    ]
                  }
                ],
                "secondary_content": [],
                "table_content": [],
                "footer": {
                  "primary_content": [],
                  "secondary_content": [],
                  "table_content": []
                },
                "main_topic": [],
                "secondary_topic": [],
                "ratings": [],
                "offers": [],
                "comments": [],
                "contacts": {
                  "telephones": [],
                  "emails": []
                }
              },
              "page_as_markdown": "# 页面标题\n\n这是页面正文。"
            }
          ]
        }
      ]
    }
  ]
}

错误处理

建议根据顶层和任务级别的 status_code、status_message 实现错误处理机制：

首检查顶层 status_code，确认请求是否成功接收。
再检查每个任务的 status_code，判断任务是否成功。
根据 crawl_progress 判断抓取是否仍在进行。
对页面 HTTP 状态码、解析失败、任务不存在等异常进行重试或记录。
对无法解析的页面保留任务 ID，便于后续查询和排查。

实用场景

提取竞品页面正文、标题和链接，批量分析竞争对手的结构与链布局，制定和站链接策略。
生成 SEO审计数据，获取页面标题层级、主要和次要，识别正文缺失、结构混乱或模板占比过高的页面。
解析商品页的价格、评分和评论，汇总竞品商品信息，为电商 SEO、价格监控和商品优化提供数据支持。
构建知识库或检索系统，通过 page_as_markdown 获取标准化文本，降低网页洗成本并便于后续分段、向量化和语义分析。
识别网页中的联系方式和外部链接，提取邮箱、电话号码及链接锚文本，用于本地 SEO、站点资产盘点和外链分析。

OnPage解析 ​

计费说明 ​

请求说明 ​

请求参数 ​

请求示例 ​

响应说明 ​

顶层响应字段 ​

任务字段 ​

结果字段 ​

items 字段 ​

page_content 页面 ​

页面头部与底部 ​

​

表格 ​

行单格字段 ​

页面主题 ​

main_topic ​

secondary_topic ​

评分、商品与评论 ​

ratings ​

offers ​

comments ​

联系方式 ​

contacts ​

Markdown ​

curl 示例 ​

Python 示例 ​

TypeScript 示例 ​

响应示例 ​

错误处理 ​

实用场景 ​

OnPage解析

计费说明

请求说明

请求参数

请求示例

响应说明

顶层响应字段

任务字段

结果字段

`items` 字段

`page_content` 页面

页面头部与底部

表格

行单格字段

页面主题

`main_topic`

`secondary_topic`

评分、商品与评论

`ratings`

`offers`

`comments`

联系方式

`contacts`

Markdown

curl 示例

Python 示例

TypeScript 示例

响应示例

错误处理

实用场景