页面微数据校验

接口说明

/v3/on_page/microdata 用于校验目标页面中的结构化数据，支持解析并验证 JSON-LD 与 Microdata 标记。

通过本接口，你可以获取：

• 指定页面上存在的微数据
• 每个结构化数据项的类型与字段
• 针对字段的校验结果
• 错误、警告、提示等验证信息汇总

使用前提：需在 /v3/on_page/task_post/ 创建 OnPage 任务，并将 validate_micromarkup 设置为 true。

请求地址

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

计费说明

该功能本身不单独收费。任务结果在后续 30 天可获取。

响应中的 cost 字段通常为 0，扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求格式

所有 POST 数据均使用 JSON（UTF-8 编码）提交，请求体格式为 JSON 数组：

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

请求参数

字段名	类型	填	说明
id	string	是	任务 ID。可在 /v3/on_page/task_post/ 的响应中获取。格式为 UUID。示例：07131248-1535-0216-1000-17384017ad04
url	string	是	页面 URL。可在 /v3/on_page/pages/ 的响应中获取。示例：https://example.com/apis
tag	string	否	自定义任务标识，最长 255 个字符。可用于结果匹，返回时会出现在响应的 data 对象中

响应结构

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

建议对 status_code 与 status_message 建立统一的异常处理机制。错误码可参考 /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	请求路径
data	object	回显请求参数
result	array	校验结果数组

result[] 字段

字段名	类型	说明
crawl_progress	string	抓取进度，可能值：in_progress、finished
crawl_status	object	抓取会话
test_summary	object	微数据校验结果汇总
items_count	integer	items 数组中的数据项数量
items	array	提取出的结构化数据项

crawl_status 字段

字段名	类型	说明
max_crawl_pages	integer	最大抓取页数，对应建任务时设置的 max_crawl_pages
pages_in_queue	integer	当前排队中的页面数
pages_crawled	integer	已抓取页面数

test_summary 字段

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

items[] 字段

当前文档示例中主要返回 json_ld 类型。

字段名	类型	说明
type	string	数据项类型，示例：json_ld
inspection_info	object	微数据校验

inspection_info 字段

字段名	类型	说明
types	array	父级微数据类型列表。可参考 schema.org 类型体系
fields	array	当前类型下的字段数组

fields[] 字段

字段名	类型	说明
name	string	字段名称
types	array	微数据子类型列表
value	array / string / null	页面上声明的字段值
test_results	object / null	当前字段的校验结果
fields	array / null	嵌套字段数组

test_results 字段

字段名	类型	说明
level	string	校验级别，可选值：fatal、error、warning、info
message	string	校验信息，说明发现的问题

调用示例

cURL

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/apis"
 }
]'

Python

import requests

url = "https://api.seermartech.cn/v3/on_page/microdata"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
data = [
 {
 "id": "02241700-1535-0216-0000-034137259bc1",
 "url": "https://example.com/apis"
 }
]

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

TypeScript

import axios from "axios";

const postArray = [
 {
 id: "02241700-1535-0216-0000-034137259bc1",
 url: "https://example.com/apis"
 }
];

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

响应示例

原始文档中的响应示例存在截断与省略，以下保留核心结构并整理为可读格式。

{
 "version": "0.1.20221214",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0344 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "on_page",
 "function": "microdata",
 "url": "https://example.com/apis",
 "target": "example.com",
 "max_crawl_pages": 10,
 "enable_content_parsing": true,
 "validate_micromarkup": true
 },
 "result": [
 {
 "items": [
 {
 "type": "json_ld",
 "inspection_info": {
 "fields": [
 {
 "name": "name",
 "types": null,
 "value": null,
 "test_results": {
 "level": "warning",
 "message": "missing field 'name'"
 },
 "fields": null
 }
 ]
 }
 },
 {
 "type": "json_ld",
 "inspection_info": {
 "fields": [
 {
 "name": "priceRange",
 "types": null,
 "value": "$$$",
 "test_results": null,
 "fields": null
 },
 {
 "name": "openingHours",
 "types": null,
 "value": "Monday,Tuesday,Wednesday,Thursday,Friday,Saturday,Sunday 09:00-17:00",
 "test_results": null,
 "fields": null
 },
 {
 "name": "telephone",
 "types": null,
 "value": "+3726027642",
 "test_results": null,
 "fields": null
 }
 ]
 }
 },
 {
 "type": "json_ld",
 "inspection_info": {
 "fields": [
 {
 "name": "potentialAction",
 "types": null,
 "value": null,
 "test_results": {
 "level": "error",
 "message": "missing field 'potentialAction'"
 },
 "fields": null
 }
 ]
 }
 }
 ]
 }
 ]
 }
 ]
}

使用说明

本接口不是独立发起抓取任务的，而是用于获取已经创建的 OnPage 任务中的微数据校验结果。标准流程如下：

1. 调用 /v3/on_page/task_post/ 创建任务
2. 在任务参数中设置 validate_micromarkup: true
3. 等页面抓取与解析完成
4. 调用 /v3/on_page/microdata 获取结构化数据与校验结果

错误处理建议

建议重点处理以下两层状态：

• 顶层 status_code：判断整个请求是否成功
• 任务级 tasks[].status_code：判断任务是否成功返回结果

同时，对字段级校验结果中的 test_results.level 进行分级处理：

• fatal：致命问题，通常表示结构化数据不可用
• error：严重问题，可能影响搜索引擎理解
• warning：建议修复，可能影响富结果完整性
• info：提示信息，可用于补优化

实用场景

• 校验页面结构化数据完整性：检查 JSON-LD 或 Microdata 是否缺少字段，减少富结果丢失风险。
• 定位 schema 标记错误：识别 missing field、类型不匹等问题，帮助开发和 SEO 团队快速修复页面标记。
• 批量巡检站点模板页：对文章页、产品页、本地门店页等模板进行统一校验，发现性标记缺陷。
• 评估富结果可用性：通过 fatal、error、warning 汇总结果，快速判断页面是否备搜索增强展示基础。
• 监控上线后的标记回归问题：在页面改版或 CMS 更新后复查结构化数据，因模板变更导致 schema 丢失。