on_page/links

POST /v3/on_page/links

接口说明

POST /v3/on_page/links

本接口用于获取目标网站中检测到的链接和外部链接，并支持按页面、目标页面、链接属性及链接方向进行筛选。

支持的链接类型：

anchor：指向网页特定位置的锚点链接
image：指向图片资源的链接
canonical：指向规范页面的链接
meta：通过 meta http-equiv="refresh" 设置的链接
alternate：通过 <link rel="alternate"> 指向替代版本页面的链接
redirect：重定向状态的链接

本接口需要使用通过 /v3/on_page/task_post 创建任务后返回的任务 ID 查询结果。

计费说明

使用此功能不额外扣费。任务结果可在创建任务后的 30 天获取。

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

请求格式

请求体使用 UTF-8 编码的 JSON 数组：

json

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

请求参数

参数	类型	填	说明
`id`	string	是	任务 ID。由 `/v3/on_page/task_post` 接口返回，格式为 UUID，例如 `07131248-1535-0216-1000-17384017ad04`。
`page_from`	string	否	来源页面的相对 URL。设置后返回指定页面中检测到的链接。此字段只能填写相对 URL。
`page_to`	string	否	目标页面的相对 URL。设置后返回指向指定页面的链接。此字段只能填写相对 URL。
`limit`	integer	否	单次返回的最大链接数量。默认值为 `100`，最大值为 `1000`。
`offset`	integer	否	结果数组的偏移量。默认值为 `0`，最大值为 `2000000`。例如设置为 `10` 时，跳过前 10 条结果。
`filters`	array	否	结果过滤条件。最多设置 8 个过滤条件，条件之间使用 `and` 或 `or` 连接。
`search_after_token`	string	否	用于获取后续结果的分页令牌。当单次请求需要获取 20,000 条结果时，可使用该参数时。该值由上一次响应返回。使用时，除 `search_after_token` 外的参数与上一次请求保持一致。每个后续任务的令牌均唯一性。
`tag`	string	否	用户自定义的任务标识，最长 255 个字符。该值会原样出现在响应的 `data` 对象中，可用于任务和结果。

过滤条件

支持以下运算符：

regex
not_regex
=
<>
in
not_in
like
not_like

like 和 not_like 支持使用 % 匹任意长度的字符串空字符串。

示例：

json

[
  {
    "id": "07131248-1535-0216-1000-17384017ad04",
    "filters": [
      ["dofollow", "=", true],
      "and",
      ["direction", "=", "external"]
    ],
    "limit": 10
  }
]

响应结构

接口返回 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	请求路径信息。
`data`	object	创建任务或查询任务时提交的参数。
`result`	array	任务结果数组。

`result` 字段

字段	类型	说明
`crawl_progress`	string	抓取进度。可选值：`in_progress`、`finished`。
`crawl_status`	object	抓取会话。
`search_after_token`	string	后续分页令牌。请求结果过多时，可将该值用于下一次请求。
`items`	array	链接结果数组。

`crawl_status` 字段

字段	类型	说明
`max_crawl_pages`	integer	最大抓取页面数，对应创建任务时设置的 `max_crawl_pages`。
`pages_in_queue`	integer	当前仍在抓取队列中的页面数。
`pages_crawled`	integer	已抓取页面数。
`total_items_count`	integer	数据库中符合条件的链接总数。
`items_count`	integer	当前结果数组中的链接数量。

链接结果字段

不同链接类型会返回相应的对象字段。以下通用字段适用于 anchor、image、canonical、meta、alternate 和 redirect 类型。

字段	类型	说明
`type`	string	链接类型。可能为 `anchor`、`image`、`canonical`、`meta`、`alternate` 或 `redirect`。
`domain_from`	string	来源域名，即发现该链接的域名。
`domain_to`	string	目标域名，即链接指向的域名。
`page_from`	string	来源页面的相对 URL。
`page_to`	string	目标页面的相对 URL。
`link_from`	string	来源页面的绝对 URL。
`link_to`	string	目标页面或资源的绝对 URL。
`page_from_scheme`	string	来源页面的 URL 协议，例如 `http` 或 `https`。
`page_to_scheme`	string	目标页面的 URL 协议。
`direction`	string	链接方向。可选值：`internal`、`external`。
`is_broken`	boolean	是否为失效链接。若链接指向失效页面或资源，则为 `true`。
`is_link_relation_conflict`	boolean	链接是否存在冲突。若指向同一 `link_to` 的链接中同时存在 `nofollow` 和 dofollow 链接，则为 `true`。
`page_to_status_code`	integer	目标页面或资源返回的 HTTP 状态码。
`dofollow`	boolean	是否为 dofollow 链接。值为 `true` 表示该链接未设置 `rel="nofollow"`。

`link_attribute`

字段	类型	说明
`link_attribute`	array	外部链接的 HTML 属性列表，表示 `page_from` 页面中 `link_to` 链接附加的属性。

`anchor_link` 特有字段

字段	类型	说明
`text`	string	锚文本。

anchor_link 对象的 type 固定为 anchor。

`image_link` 特有字段

字段	类型	说明
`text`	string	图片链接文本。
`image_alt`	string	图片的替代文本，即 `alt` 属性值。
`image_src`	string	图片资源 URL。

image_link 对象的 type 固定为 image。

`link_tag_link` 特有说明

link_tag_link 表示通过 HTML <link> 标签发现的链接，通用链接字段。

type 为 link，可用于表示规范链接、替代版本链接等 <link> 标签。

`canonical_link`

canonical_link 表示规范链接，通用链接字段 type 固定为 canonical。

`meta_link`

meta_link 表示通过 meta http-equiv="refresh" 发现的链接，通用链接字段 type 固定为 meta。

`alternate_link` 特有字段

字段	类型	说明
`is_valid_hreflang`	boolean	`hreflang`置是否有效。
`hreflang`	string	`hreflang` 属性值，语言代码以及可选的国家/地区代码，例如 `en-US`、`fr`。

alternate_link 对象的 type 固定为 alternate。

`redirect_link`

redirect_link 表示 HTTP 3xx 重定向链接，通用链接字段 type 固定为 redirect。

请求示例

cURL

bash

curl --location --request POST "https://api.seermartech.cn/v3/on_page/links" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "id": "07281559-0695-0216-0000-c269be8b7592",
      "page_from": "/apis/google-trends-api",
      "filters": [
        ["dofollow", "=", true],
        "and",
        ["direction", "=", "external"]
      ],
      "limit": 10
    }
  ]'

Python

python

import requests

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

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

payload = [
    {
        "id": "07281559-0695-0216-0000-c269be8b7592",
        "page_from": "/apis/google-trends-api",
        "filters": [
            ["dofollow", "=", True],
            "and",
            ["direction", "=", "external"],
        ],
        "limit": 10,
    }
]

response = requests.post(url, headers=headers, json=payload)
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 payload = [
  {
    id: "07281559-0695-0216-0000-c269be8b7592",
    page_from: "/apis/google-trends-api",
    filters: [
      ["dofollow", "=", true],
      "and",
      ["direction", "=", "external"],
    ],
    limit: 10,
  },
];

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

响应示例

json

{
  "version": "0.1.20201117",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.1513 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "07281559-0695-0216-0000-c269be8b7592",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.1200 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "on_page",
        "links"
      ],
      "data": {
        "api": "on_page",
        "function": "links",
        "page_from": "/apis/google-trends-api",
        "limit": 10
      },
      "result": [
        {
          "crawl_progress": "finished",
          "crawl_status": {
            "max_crawl_pages": 100,
            "pages_in_queue": 0,
            "pages_crawled": 1,
            "total_items_count": 1,
            "items_count": 1
          },
          "items": [
            {
              "anchor_link": {
                "type": "anchor",
                "domain_from": "example.com",
                "domain_to": "example.com",
                "page_from": "/apis/google-trends-api",
                "page_to": "/docs",
                "link_from": "https://example.com/apis/google-trends-api",
                "link_to": "https://example.com/docs",
                "link_attribute": [],
                "dofollow": true,
                "page_from_scheme": "https",
                "page_to_scheme": "https",
                "direction": "internal",
                "is_broken": false,
                "text": "API 文档",
                "is_link_relation_conflict": false,
                "page_to_status_code": 200
              }
            }
          ]
        }
      ]
    }
  ]
}

错误处理

请根据顶层 status_code 和任务级 status_code 判断请求是否成功，并结合对应的 status_message 进行错误处理。建议客户端对网络时、任务执行失败、结果为空和分页令牌失效等进行单独处理。

实用场景

检查站链接：识别页面之间的链接，评估网站信息架构和权重传递是否合理。
定位失效链接：筛选 is_broken=true 的链接，批量发现 404 页面、失效资源和错误跳转，降低抓取与用户访问损失。
审查外链属性：结合 direction、dofollow 和 link_attribute 分析外部链接，检查赞助、用户生成及 nofollow置。
验证多语言实现：通过 alternate_link 的 hreflang 和 is_valid_hreflang 检查化页面的语言映射，减少区域页面错。
排查规范化与重定向问题：分析 canonical、meta 和 redirect 类型链接，发现规范链接错误、刷新跳转及不的 3xx 链路。

on_page/links ​

接口说明 ​

计费说明 ​

请求格式 ​

请求参数 ​

过滤条件 ​

响应结构 ​

顶层响应字段 ​

tasks 数组中的字段 ​

result 字段 ​

crawl_status 字段 ​

链接结果字段 ​

link_attribute ​

anchor_link 特有字段 ​

image_link 特有字段 ​

link_tag_link 特有说明 ​

canonical_link ​

meta_link ​

alternate_link 特有字段 ​

redirect_link ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应示例 ​

错误处理 ​

实用场景 ​

on_page/links

接口说明

计费说明

请求格式

请求参数

过滤条件

响应结构

顶层响应字段

`tasks` 数组中的字段

`result` 字段

`crawl_status` 字段

链接结果字段

`link_attribute`

`anchor_link` 特有字段

`image_link` 特有字段

`link_tag_link` 特有说明

`canonical_link`

`meta_link`

`alternate_link` 特有字段

`redirect_link`

请求示例

cURL

Python

TypeScript

响应示例

错误处理

实用场景