OnPage 结构化数据验证（Microdata）

POST /v3/on_page/microdata

本接口使用 POST /v3/on_page/microdata，用于获取指定页面中的 JSON-LD 与 Microdata 结构化数据，并返回详细的验证结果。使用前，需要在 OnPage API 的任务创建请求中将 validate_micromarkup 设置为 true，再通过任务创建接口返回的任务 ID 和页面 URL 请求本接口。

接口信息

请求方法：POST
请求路径：/v3/on_page/microdata
完整地址：https://api.seermartech.cn/v3/on_page/microdata
请求格式：JSON
字符编码：UTF-8
认证方式：Bearer Token

计费说明

根据接口规则，本功能不会产生额外费用，任务结果可在任务完成后的 30 天获取。

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

请求参数

所有请求参数放在 JSON 数组中，每个数组代表一个任务。

参数名	类型	填	说明
`id`	string	是	任务 ID。通过 OnPage 任务创建接口 `/v3/on_page/task_post/` 的响应获取。示例：`"07131248-1535-0216-1000-17384017ad04"`
`url`	string	是	验证的页面 URL。通过 OnPage Pages 接口 `/v3/on_page/pages/` 的响应获取。示例：`"https://example.com/about"`
`tag`	string	否	用户自定义的任务标识，最长 255 个字符。可用于识别任务并结果，提交的值会原样返回在响应的 `data` 对象中。

请求示例

json

[
  {
    "id": "02241700-1535-0216-0000-034137259bc1",
    "url": "https://example.com/about",
    "tag": "structured-data-check"
  }
]

响应结构

接口返回 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	爬取会话
`test_summary`	object	Microdata 验证汇总
`items_count`	integer	结果中的结构化数据项目数量
`items`	array	结构化数据项目列表

`crawl_status`

字段名	类型	说明
`max_crawl_pages`	integer	最大爬取页面数，即创建任务时设置的 `max_crawl_pages`
`pages_in_queue`	integer	当前排队爬取的页面数
`pages_crawled`	integer	已完成爬取的页面数

`test_summary`

字段名	类型	说明
`fatal`	integer	致命级 Microdata 错误数量
`error`	integer	严重级 Microdata 错误数量
`warning`	integer	Microdata 警告数量
`info`	integer	Microdata 信息提示数量

`items` 字段说明

每个项目描述一个检测到的结构化数据对象。

字段名	类型	说明
`json_ld`	object	JSON-LD 项目对象
`type`	string	项目类型，固定为 `json_ld`
`inspection_info`	object	结构化数据验证

`inspection_info`

字段名	类型	说明
`types`	array	父级结构化数据类型。完整类型列表请参考 Schema.org。
`fields`	array	当前结构化数据类型的字段列表

`fields`

字段名	类型	说明
`name`	string	字段名称
`types`	array	字段对应的 Microdata 子类型列表
`value`	array	页面中检测到的字段值
`test_results`	object	当前字段的验证结果
`fields`	array	嵌套字段列表

`test_results`

字段名	类型	说明
`level`	string	错误级别，可选值：`fatal`、`error`、`warning`、`info`
`message`	string	错误或提示信息

例如，缺少填字段时可能返回：

json

{
  "name": "name",
  "types": null,
  "value": null,
  "test_results": {
    "level": "warning",
    "message": "missing field 'name'"
  },
  "fields": null
}

请求示例

cURL

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/on_page/microdata" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "id": "02241700-1535-0216-0000-034137259bc1",
      "url": "https://example.com/about",
      "tag": "structured-data-check"
    }
  ]'

Python

python

import requests

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

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

post_data = [
    {
        "id": "02241700-1535-0216-0000-034137259bc1",
        "url": "https://example.com/about",
        "tag": "structured-data-check",
    }
]

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 response = await axios.post(
  "https://api.seermartech.cn/v3/on_page/microdata",
  [
    {
      id: "02241700-1535-0216-0000-034137259bc1",
      url: "https://example.com/about",
      tag: "structured-data-check",
    },
  ],
  {
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
  }
);

const result = response.data;

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

响应示例

以下为经过整理的响应结构示例，返回的 items 和 fields 数量取决于目标页面中的结构化数据。

json

{
  "version": "0.1.20221214",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.0344 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "02241700-1535-0216-0000-034137259bc1",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.0300 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "about"
      ],
      "data": {
        "api": "on_page",
        "function": "microdata",
        "url": "https://example.com/about",
        "target": "example.com",
        "max_crawl_pages": 10,
        "enable_content_parsing": true,
        "validate_micromarkup": true,
        "tag": "structured-data-check"
      },
      "result": [
        {
          "crawl_progress": "finished",
          "crawl_status": {
            "max_crawl_pages": 10,
            "pages_in_queue": 0,
            "pages_crawled": 1
          },
          "test_summary": {
            "fatal": 0,
            "error": 1,
            "warning": 2,
            "info": 0
          },
          "items_count": 1,
          "items": [
            {
              "type": "json_ld",
              "inspection_info": {
                "types": [
                  "LocalBusiness"
                ],
                "fields": [
                  {
                    "name": "name",
                    "types": null,
                    "value": null,
                    "test_results": {
                      "level": "warning",
                      "message": "missing field 'name'"
                    },
                    "fields": null
                  },
                  {
                    "name": "telephone",
                    "types": null,
                    "value": "+8613800000000",
                    "test_results": null,
                    "fields": null
                  },
                  {
                    "name": "priceRange",
                    "types": null,
                    "value": "$$$",
                    "test_results": null,
                    "fields": null
                  }
                ]
              }
            }
          ]
        }
      ]
    }
  ]
}

状态码与异常处理

响应中的 status_code 和 tasks[].status_code 分别表示请求级和任务级处理结果。建议客户端同时检查：

HTTP 状态码；
顶层 status_code；
每个任务的 status_code；
tasks_error 是否大于 0；
test_summary 中的结构化数据错误数量。

当 crawl_progress 为 in_progress 时，表示爬取尚未结束，应根据业务需要稍后重新获取结果。错误码和说明请参考错误码文档。

实用场景

批量检查页面结构化数据：扫描产品页、文章页和本地商家页中的 JSON-LD 与 Microdata，及时发现标记缺失或格式异常，提升富媒体搜索结果的展示稳定性。
定位填字段错误：识别 name、image、telephone、priceRange 等字段的缺失问题，为 SEO 技术修复提供明确依据。
验证模板改版效果：在网站模板上线前后对比 test_summary 和 fields 结果，确认结构化数据改动没有引新的错误。
构建结构化数据质量报表：按页面、数据类型和错误级别汇总 fatal、error、warning 与 info 数量，为 SEO 项目管理和质量验收提供指标。
监控重点落地页：定期检查高流量页面的结构化数据爬取状态与字段值，及时发现页面发布、渲染或更新导致的标记失效。

OnPage 结构化数据验证（Microdata） ​

接口信息 ​

计费说明 ​

请求参数 ​

请求示例 ​

响应结构 ​

顶层响应字段 ​

tasks 任务字段 ​

result 字段说明 ​

crawl_status ​

test_summary ​

items 字段说明 ​

inspection_info ​

fields ​

test_results ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应示例 ​

状态码与异常处理 ​

实用场景 ​

OnPage 结构化数据验证（Microdata）

接口信息

计费说明

请求参数

请求示例

响应结构

顶层响应字段

`tasks` 任务字段

`result` 字段说明

`crawl_status`

`test_summary`

`items` 字段说明

`inspection_info`

`fields`

`test_results`

请求示例

cURL

Python

TypeScript

响应示例

状态码与异常处理

实用场景