页面密度

接口说明

/v3/on_page/keyword_density 用于获取指定网站或网页中的频次与密度数据。你可以按条件过滤结果，并对返回数据进行排序。

使用前提： 要使用本接口，在 /v3/on_page/task_post/ 创建任务时，将 calculate_keyword_density 设置为 true。

• 请求方法：POST
• 接口地址：https://api.seermartech.cn/v3/on_page/keyword_density

计费说明

调用本接口本身不会额外扣费。在任务完成后的 30 天，你可以获取该任务结果。

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

请求格式

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

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

请求参数

字段名	类型	说明
id	string	填。任务 ID。可从 /v3/on_page/task_post/ 的响应中获取。示例：07131248-1535-0216-1000-17384017ad04
keyword_length	integer	填。的单词数。可选值：1、2、3、4、5
url	string	可选。页面 URL。**如果不传该字段，将返回整个网站的结果；如果传该字段，则返回指定页面的数据。**须使用绝对 URL， http:// 或 https://
limit	integer	可选。返回的最大数量。默认值：100；最大值：1000
filters	array	可选。结果过滤条件数组。最多支持 8 个过滤条件。多个条件之间需使用逻辑运算符 and 或 or 连接
order_by	array	可选。结果排序规则。可使用与 filters 相同的字段进行排序
tag	string	可选。用户自定义任务标识，最长 255 个字符。可用于结果追踪与业务侧任务映射

filters 过滤规则

filters 支持以下操作符：

• regex
• not_regex
• =
• <>
• in
• not_in
• like
• not_like

说明：

• like 和 not_like 支持使用 % 匹任意长度字符串
• 多个条件之间需要显式写 and 或 or

示例：

[
 {
 "id": "09101923-1535-0216-0000-2389a8854b70",
 "url": "https://example.com/",
 "keyword_length": 2,
 "filters": [
 ["frequency", ">", 5],
 "and",
 ["keyword", "like", "%api%"]
 ]
 }
]

可过滤字段的完整范围请参考过滤规则文档。

order_by 排序规则

order_by 用于设置结果排序方式：

• asc：升序
• desc：降序

单个排序规则使用“字段名 + 排序方向”的形式；多个排序规则之间用逗号区分。 单次请求最多支持 3 条排序规则。

示例：

[
 {
 "id": "09101923-1535-0216-0000-2389a8854b70",
 "keyword_length": 2,
 "order_by": [
 "frequency,desc",
 "density,desc"
 ]
 }
]

响应结构

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

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	抓取会话
total_items_count	integer	符合 keyword_length 与 filters 条件的总数
items_count	integer	当前结果中的项目数
items	array	明细列表

crawl_status 字段

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

items 数组字段

字段名	类型	说明
keyword	string	返回的
frequency	integer	出现频次。若指定 url，则表示该网页中的出现次数；否则表示整个网站中的出现次数
density	integer	密度。按该出现频次占指定 keyword_length部总数的比例计算

请求示例

cURL

curl --location --request POST "https://api.seermartech.cn/v3/on_page/keyword_density" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "id": "09101923-1535-0216-0000-2389a8854b70",
 "url": "https://example.com/",
 "keyword_length": 2,
 "filters": [
 ["frequency", ">", 5]
 ],
 "order_by": [
 "frequency,desc"
 ],
 "limit": 100
 }
]'

Python

import requests

url = "https://api.seermartech.cn/v3/on_page/keyword_density"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
payload = [
 {
 "id": "09101923-1535-0216-0000-2389a8854b70",
 "url": "https://example.com/",
 "keyword_length": 2,
 "filters": [
 ["frequency", ">", 5]
 ],
 "order_by": [
 "frequency,desc"
 ],
 "limit": 100
 }
]

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

TypeScript

import axios from "axios";

const payload = [
 {
 id: "09101923-1535-0216-0000-2389a8854b70",
 url: "https://example.com/",
 keyword_length: 2,
 filters: [
 ["frequency", ">", 5]
 ],
 order_by: [
 "frequency,desc"
 ],
 limit: 100
 }
];

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

响应示例

{
 "version": "0.1.20210907",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.2239 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "09101923-1535-0216-0000-2389a8854b70",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.1201 sec.",
 "cost": 0,
 "result_count": 1,
 "path": [
 "v3",
 "on_page",
 "keyword_density"
 ],
 "data": {
 "api": "on_page",
 "function": "keyword_density",
 "url": "https://example.com/",
 "keyword_length": 2,
 "order_by": [
 "frequency,desc"
 ],
 "filters": [
 ["frequency", ">", 5]
 ],
 "target": "example.com",
 "max_crawl_pages": 10,
 "calculate_keyword_density": true
 },
 "result": [
 {
 "crawl_progress": "finished",
 "crawl_status": {
 "max_crawl_pages": 10,
 "pages_in_queue": 0,
 "pages_crawled": 10
 },
 "total_items_count": 24,
 "items_count": 3,
 "items": [
 {
 "keyword": "seo tools",
 "frequency": 12,
 "density": 4
 },
 {
 "keyword": "keyword research",
 "frequency": 9,
 "density": 3
 },
 {
 "keyword": "rank tracking",
 "frequency": 6,
 "density": 2
 }
 ]
 }
 ]
 }
 ]
}

状态码与错误处理

请根据 status_code 和 status_message 处理接口结果。

• 顶层 status_code：表示整个请求是否成功
• tasks[].status_code：表示单个任务是否成功
• 建议同时校验这两个层级的状态码
• 错误码完整列表可参考 /v3/appendix/errors

建议： 在生产环境中建立统一的异常处理机制，用于处理参数错误、任务不存在、抓取未完成、权限异常、额限制等。

使用说明补

1. 本接口依赖已创建的 On-Page 抓取任务；
2. 只有在 /v3/on_page/task_post/ 中开启 calculate_keyword_density=true 时，才能获取密度结果；
3. 如未指定 url，返回值基于整个网站；
4. 如指定 url，返回值基于该页面；
5. 若抓取尚未完成，可通过 crawl_progress 判断当前状态。

实用场景

• 分析页面词频结构：识别指定页面的高频词与高密度词，评估页面主题是否足够聚焦。
• 排查过度优化风险：筛选某些词频异常偏高的，及时发现可能影响搜索表现的堆砌问题。
• 对比站点与单页差异：分别请求站与单页数据，判断核心词是否只集中在少数页面，结构优化。
• 挖掘主题覆盖空白：按不同 keyword_length 查看 1-5 词短语的分布，识别长尾主题覆盖不足的位置。
• 监控改版效果：在页面更新前后对比频次与密度变化，评估文案调整是否更贴近目标主题。