页面密度

POST /v3/on_page/keyword_density

接口说明

POST /v3/on_page/keyword_density

本接口用于获取指定网站或网页中的密度与出现频次。你可以按长度筛选，并对返回结果进行过滤和排序。

使用本接口前，请确保在创建任务时将 calculate_keyword_density 参数设置为 true。任务创建完成后，使用任务 ID 查询密度结果。

计费说明

本接口当前不额外收取查询费用，任务结果可在任务创建后的 30 天获取。响应中的 cost 通常为 0。

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

请求格式

所有 POST 请求均须使用 UTF-8 编码的 JSON 格式，请求体为 JSON 数组：

json

[
  {
    "id": "07131248-1535-0216-1000-17384017ad04",
    "keyword_length": 2
  }
]

请求参数

参数	类型	填	说明
`id`	string	是	任务 ID。该 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	否	结果排序规则。最多设置 3 条排序规则，可使用与 `filters` 相同的字段和运算符
`tag`	string	否	自定义任务标识，最长 255 个字符。可用于任务与结果，指定的值会原样返回在响应的 `data` 对象中

`filters` 过滤条件

支持以下运算符：

regex
not_regex
=
<>
in
not_in
like
not_like

使用 like 和 not_like 时，可以使用 % 匹任意长度的字符串空字符串。

过滤条件示例：

json

[
  ["frequency", ">", 5],
  "and",
  ["keyword", "like", "%seo%"]
]

完整的过滤字段与条件说明，请参考过滤器和阈值文档。

`order_by` 排序规则

排序方向支持：

asc：升序
desc：降序

排序规则通常以字段名和排序方向组成，例如：

json

[
  "frequency,desc",
  "density,desc"
]

单个请求最多设置 3 条排序规则，多条规则之间使用逗号分隔。

请求示例

cURL

bash

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,
      "limit": 100,
      "filters": [
        ["frequency", ">", 5]
      ],
      "order_by": [
        "frequency,desc"
      ],
      "tag": "homepage-bigrams"
    }
  ]'

Python

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]
        ],
    }
]

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

if response.status_code == 200:
    result = response.json()
    print(result)
else:
    print("HTTP 错误：", response.status_code, response.text)

TypeScript

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",
    ],
  },
];

axios({
  method: "post",
  url: "https://api.seermartech.cn/v3/on_page/keyword_density",
  headers: {
    Authorization: "Bearer smt_live_YOUR_KEY",
    "Content-Type": "application/json",
  },
  data: payload,
})
  .then((response) => {
    // 处理接口返回结果
    console.log(response.data);
  })
  .catch((error) => {
    console.error("请求失败：", error.response?.data || error.message);
  });

响应结构

接口返回 JSON 数据 tasks 数组。

json

{
  "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.2000 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,
        "limit": 100,
        "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": 1
          },
          "total_items_count": 2,
          "items_count": 2,
          "items": [
            {
              "keyword": "technical seo",
              "frequency": 8,
              "density": 12
            },
            {
              "keyword": "seo audit",
              "frequency": 6,
              "density": 9
            }
          ]
        }
      ]
    }
  ]
}

响应字段

顶层字段

字段	类型	说明
`version`	string	当前 API 版本
`status_code`	integer	局状态码。`20000` 表示请求成功，状态码请根据错误码处理
`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	抓取会话的详细状态
`total_items_count`	integer	符合指定 `keyword_length` 和 `filters` 条件的总数
`items_count`	integer	当前 `items` 数组中的数量
`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	密度，按该的 `frequency` 除以指定长度下的总数计算

状态码与错误处理

请根据响应中的 status_code 和 status_message 判断请求是否成功。建议在业务系统中处理以下：

顶层 status_code 非 20000
单个任务的 status_code 非 20000
crawl_progress 为 in_progress，表示抓取尚未完成
tasks_error 大于 0
请求时、认证失败或参数校验失败

完整错误码请参考错误码文档。

实用场景

识别页面核心：统计目标页面中不同长度的出现频次与密度，提炼页面主题和重点。
检查优化效果：对比优化前后的频率和密度，评估 SEO调整是否真正提升了主题性。
发现堆砌风险：筛选高频并检查密度，及时降低过度重复带来的质量和搜索引擎风险。
对比网站与单页主题覆盖：分别分析整个网站和指定网页，定位站点级主题与页面级主题之间的偏差。
构建竞品分析报告：抓取竞品网站的高频词组并按频次排序，为规划、标题设计和链接布局提供依据。

页面密度 ​

接口说明 ​

计费说明 ​

请求格式 ​

请求参数 ​

filters 过滤条件 ​

order_by 排序规则 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应结构 ​

响应字段 ​

顶层字段 ​

tasks 任务字段 ​

result 结果字段 ​

crawl_status 字段 ​

items 字段 ​

状态码与错误处理 ​

实用场景 ​

页面密度

接口说明

计费说明

请求格式

请求参数

`filters` 过滤条件

`order_by` 排序规则

请求示例

cURL

Python

TypeScript

响应结构

响应字段

顶层字段

`tasks` 任务字段

`result` 结果字段

`crawl_status` 字段

`items` 字段

状态码与错误处理

实用场景