新增与丢失外链时间序列汇总（实时）

接口说明

该接口用于获取指定域名在一段时间的：

• 新增外链数量
• 丢失外链数量
• 新增引荐域数量
• 丢失引荐域数量
• 新增主域数量
• 丢失主域数量

返回结果会你指定的时间粒度进行聚合，支持：

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

非常适合用于绘制外链增长/流失趋势图，以及监控引荐域变化。

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

接口地址

POST https://api.seermartech.cn/v3/backlinks/timeseries_new_lost_summary/live

计费与限流

• 按请求计费
• 参考价请以平台价格换算，扣费以响应头 X-SeerMarTech-Charge-CNY 为准
• 所有 POST 数据使用 JSON（UTF-8）
• 请求体格式为 JSON 数组：[{ ... }]
• 每分钟最多可发起 2000 次 API 调用
• 同时进行中的请求最大为 30 个

请求参数

以下为单个任务对象可用字段说明。

字段名	类型	填	说明
target	string	是	要查询的目标域名。不要 https:// 和 www.。例如：forbes.com
date_from	string	否	时间范围起始日期。用于判断新增与丢失的阈值日期：在该日期之后出现在索引中的外链和引荐域会被视为“新增”；该日期之前存在、但之后未再发现的会被视为“丢失”。最小值：2019-01-30；不得晚于 date_to。格式：yyyy-mm-dd
date_to	string	否	时间范围结束日期。默认使用当天日期。不得早于 date_from；最大值为当天。格式：yyyy-mm-dd
group_range	string	否	结果聚合粒度。默认值：month。可选值：day、week、month、year
include_subdomains	boolean	否	是否 target 的子域名。默认值：true；如设为 false，则忽略子域名数据
tag	string	否	自定义任务标识，最长 255 个字符。可用于请求与响应结果的，响应中的 data 对象会返回该值

group_range 的返回规则

group_range 会影响返回数据的时间边界：

• 当设置为 day 时，返回 date_from 到 date_to 之间的每一天，含起止日期
• 当设置为 week / month / year 时，返回完整周 / 月 / 年的数据，每个 item 的日期表示该周期的最后一天

例如：

[{
 "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	本次请求总费用
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	单任务费用
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	string	请求中的聚合粒度
total_count	integer	与请求的结果总数
items_count	integer	items 数组中的返回条数
items	array	时间序列数据列表

items[] 字段

字段名	类型	说明
type	string	固定值：backlinks_timeseries_new_lost_summary
date	string	当前数据点对应的时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00
new_backlinks	integer	新增外链数量
lost_backlinks	integer	丢失外链数量
new_referring_domains	integer	新增引荐域数量
lost_referring_domains	integer	丢失引荐域数量
new_referring_main_domains	integer	新增主域数量
lost_referring_main_domains	integer	丢失主域数量

请求示例

cURL

curl --location --request POST "https://api.seermartech.cn/v3/backlinks/timeseries_new_lost_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_new_lost_summary/live"
payload = [
 {
 "target": "example.com",
 "date_from": "2021-12-01",
 "date_to": "2022-02-01",
 "group_range": "month"
 }
]
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

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_new_lost_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.9756 sec.",
 "cost": 0.02009,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.9756 sec.",
 "cost": 0.02009,
 "result_count": 1,
 "path": [
 "v3",
 "backlinks",
 "timeseries_new_lost_summary",
 "live"
 ],
 "data": {
 "api": "backlinks",
 "function": "timeseries_new_lost_summary",
 "target": "example.com",
 "date_from": "2021-12-01",
 "date_to": "2022-02-01",
 "group_range": "month"
 },
 "result": [
 {
 "target": "example.com",
 "date_from": "2021-12-01",
 "date_to": "2022-02-01",
 "group_range": "month",
 "total_count": 3,
 "items_count": 3,
 "items": [
 {
 "type": "backlinks_timeseries_new_lost_summary",
 "date": "2021-12-31 00:00:00 +00:00",
 "new_backlinks": 120,
 "lost_backlinks": 15,
 "new_referring_domains": 18,
 "lost_referring_domains": 3,
 "new_referring_main_domains": 16,
 "lost_referring_main_domains": 2
 },
 {
 "type": "backlinks_timeseries_new_lost_summary",
 "date": "2022-01-31 00:00:00 +00:00",
 "new_backlinks": 98,
 "lost_backlinks": 20,
 "new_referring_domains": 14,
 "lost_referring_domains": 4,
 "new_referring_main_domains": 13,
 "lost_referring_main_domains": 3
 },
 {
 "type": "backlinks_timeseries_new_lost_summary",
 "date": "2022-02-28 00:00:00 +00:00",
 "new_backlinks": 76,
 "lost_backlinks": 12,
 "new_referring_domains": 10,
 "lost_referring_domains": 2,
 "new_referring_main_domains": 9,
 "lost_referring_main_domains": 1
 }
 ]
 }
 ]
 }
 ]
}

错误处理

• 顶层 status_code 表示整次请求的执行状态
• tasks[].status_code 表示单个任务的执行状态
• 建议同时检查：
• HTTP 状态码
• 顶层 status_code
• 任务级 tasks[].status_code

常见判断方式：

• 20000：请求成功
• 状态码：表示参数错误、认证失败、限流或异常

完整错误码请参考 /v3/appendix/errors。建议在业务系统中对异常状态建立统一重试、告警和日志记录机制。

使用建议

• 分析短期波动时，优使用 day 或 week
• 观察长期趋势时，建议使用 month 或 year
• 若只心主站，不希望统计博客、帮助中心等子域，请将 include_subdomains 设为 false
• 如需将请求结果与任务系统，可使用 tag 传递业务主键或批次号

实用场景

• 监控外链增长趋势：按日或按周跟踪新增/丢失外链，及时发现外链建设成效或异常流失
• 评估品牌传播效果：观察活动周期新增引荐域变化，判断 PR、投放或合作传播是否带来外部引用
• 识别外链风险波动：持续监测丢失外链和丢失引荐域的激增，帮助排查链接下线、页面失效或站点被移除的问题
• 对比主站与站表现：结合 include_subdomains 参数分别统计主域与含子域数据，评估不同站群结构的外链贡献
• 构建 SEO 趋势看板：将返回的时间序列数据接 BI 或监控面板，生成外链净增长、引荐域净增长等核心指标图表