反向链接时间序列汇总（实时）

POST /v3/backlinks/timeseries_summary/live

接口说明

该接口用于获取指定 target 域名在两个日期之间的反向链接概览数据，并按你指定的时间粒度进行汇总。可选粒度：

• day：按天
• week：按周
• month：按月
• year：按年

该接口特别适合用于绘制反向链接增长趋势图，例如：

• 每日外链增长趋势
• 每周引用域变化
• 每月链接建设效果复盘
• 年度外链资产变化分析

历史数据最早可追溯至 2019-01-30。

请求信息

POSThttps://api.seermartech.cn/v3/backlinks/timeseries_summary/live

计费说明

该接口按请求计费。

参考价请以参考单价换算，扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

若按示例响应估算，参考价约为 ¥0.3214 / 次

调用限制

• 每分钟最多可发送 2000 次 API 调用
• 同时并发请求上限为 30

请求体格式

所有 POST 数据均需使用 JSON（UTF-8 编码），并以数组形式提交：

[
 {
 "target": "forbes.com",
 "date_from": "2021-01-01",
 "date_to": "2021-01-15",
 "group_range": "month"
 }
]

---

请求参数

字段名	类型	说明
target	string	要查询的目标域名。填。域名中不要 https:// 和 www.。例如："forbes.com"
date_from	string	时间范围起始日期。可选。用于限定汇总数据的开始时间，最小值为 2019-01-30；不得晚于 date_to。格式：yyyy-mm-dd，例如："2021-01-01"
date_to	string	时间范围结束日期。可选。若不填写，默认使用当天日期。不得早于 date_from，最大值为当天日期。格式：yyyy-mm-dd，例如："2021-01-15"
group_range	string	结果聚合粒度。可选，默认值为 month。可选值：day、week、month、year
include_subdomains	boolean	是否 target 的子域名数据。可选。设为 false 时忽略子域名。默认值：true
rank_scale	string	定义 rank、domain_from_rank、page_from_rank 的展示刻度。可选。one_hundred 表示 0–100；one_thousand 表示 0–1000。默认值：one_thousand
tag	string	自定义任务标识。可选，最长 255 个字符。可用于在响应中识别和匹任务

group_range 的返回规则

当 group_range = day

接口会返回 date_from 到 date_to 之间（含边界）的每日数据。

当 group_range = week / month / year

接口会按完整周 / 完整月 / 完整年返回结果，每个结果项的 date 表示该周期的最后一天。

例如，请求：

[
 {
 "group_range": "month",
 "date_from": "2022-03-23",
 "date_to": "2022-05-13"
 }
]

返回的数据会覆盖：

• 2022-03-01 至 2022-05-31

并返回 3 个结果项，日期分别为：

• 2022-03-31
• 2022-04-30
• 2022-05-31

如果某个 day / week / month / year 没有数据，则对应值返回 0。

---

响应结构

接口返回 JSON 数据，顶层 tasks 数组。

顶层字段

字段名	类型	说明
version	string	当前 API 版本
status_code	integer	通用状态码。完整错误码见：/v3/appendix/errors
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[] 字段

字段名	类型	说明
target	string	请求中的目标域名
date_from	string	起始日期，UTC 格式：yyyy-mm-dd
date_to	string	结束日期，UTC 格式：yyyy-mm-dd
group_range	object	请求中的 group_range
total_count	integer	与请求的结果总数
items_count	integer	items 数组中的结果条数
items	array	汇总数据

items[] 字段

字段名	类型	说明
type	string	素类型，固定为 backlinks_timeseries_summary
date	string	数据存储时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00
rank	integer	该日期下目标域名的 rank 值
backlinks	integer	该日期下的反向链接数量
backlinks_nofollow	integer	该日期下的 nofollow 反向链接数量
referring_pages	integer	该日期下指向目标域名的引用页面数量
referring_domains	integer	该日期下的引用域名数量。该指标中子域名按独立域名计算
referring_domains_nofollow	integer	至少一条 nofollow 链接的引用域名数量
referring_main_domains	integer	该日期下的主域名级引用域数量
referring_main_domains_nofollow	integer	至少一条 nofollow 链接的主域名级引用域数量
referring_ips	integer	该日期下的引用 IP 数量
referring_subnets	integer	该日期下的引用子网数量
referring_pages_nofollow	integer	至少一条 nofollow 链接的引用页面数量

---

请求示例

cURL

curl --location --request POST "https://api.seermartech.cn/v3/backlinks/timeseries_summary/live" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "target": "example.com",
 "date_from": "2021-12-01",
 "date_to": "2022-02-01",
 "group_range": "month"
 }
]'

Python

import requests

url = "https://api.seermartech.cn/v3/backlinks/timeseries_summary/live"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
payload = [
 {
 "target": "example.com",
 "date_from": "2021-12-01",
 "date_to": "2022-02-01",
 "group_range": "month"
 }
]

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

TypeScript

import axios from "axios";

const payload = [
 {
 target: "example.com",
 date_from: "2021-12-01",
 date_to: "2022-02-01",
 group_range: "month"
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/backlinks/timeseries_summary/live",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 },
 data: payload
})
 .then((response) => {
 // 返回结果
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error);
 });

---

响应示例

{
 "version": "0.1.20230825",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0709 sec.",
 "cost": 0.02009,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "backlinks",
 "function": "timeseries_summary",
 "target": "example.com",
 "date_from": "2021-12-01",
 "date_to": "2022-02-01",
 "group_range": "month"
 },
 "result": []
 }
 ]
}

---

错误处理

建议在接时对通用状态码和任务状态码建立统一异常处理机制，重点以下字段：

• 顶层 status_code
• 顶层 status_message
• tasks[].status_code
• tasks[].status_message

完整错误码与说明请参考：

• /v3/appendix/errors

---

使用建议

• 查询日级趋势时，适合用于短期链接建设监控
• 查询周 / 月 / 年级趋势时，更适合经营分析、复盘和可视化报表
• 如果你更主站整体表现，可保持 include_subdomains=true
• 如果只分析主域自身外链，不希望子域干扰，建议设为 false
• 若需统一不同报表中的 rank 量纲，请显式指定 rank_scale

实用场景

• 监控外链增长趋势：按日或按周拉取 backlinks、referring_domains 变化，快速评估链接建设活动是否有效。
• 复盘月度 SEO 投放效果：按月汇总外链与引用域数据，判断营销、PR 投放或合作换链的长期收益。
• 识别异常波动：观察某段时间 backlinks_nofollow、referring_pages 是否突增突降，及时发现垃圾链接、链接丢失或采集异常。
• 对比主域与子域贡献：结合 include_subdomains 开分别查询，拆分主站与子站的外链资产表现。
• 构建趋势报表看板：将 items 中的时间序列数据接 BI 或看板，展示日、周、月、年维度的反向链接发展曲线。