新增与丢失反向链接时间序列汇总

POST /v3/backlinks/timeseries_new_lost_summary/live

本接口使用 POST 方法，路径为：

/v3/backlinks/timeseries_new_lost_summary/live

用于查询指定域名在一段时间新增和丢失的反向链接、引用域名及主域名数量，并天、周、月或年进行聚合。历史数据最早可追溯至 2019-01-30，适合用于构建反向链接增长与流失趋势图。

请求说明

请求方式：POST
请求地址：https://api.seermartech.cn/v3/backlinks/timeseries_new_lost_summary/live
请求格式：JSON，UTF-8 编码
请求体是 JSON 数组
每次 Live 请求最多 1 个任务平台限流以认证说明中的 30/60/120 次/分钟规则为准
同时处理的请求数最多为 30 个

计费说明

本接口按请求计费。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数

请求体中的每个数组代表一个任务。

参数	类型	填	说明
`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	否	结果聚合粒度。可选值：`day`、`week`、`month`、`year`。默认值：`month`。
`include_subdomains`	boolean	否	是否将 `target` 的子域名纳查询。`false` 表示忽略子域名，默认值为 `true`。
`tag`	string	否	用户自定义任务标识，最长 255 个字符。可用于在响应结果中匹任务，传的值会原样返回在响应的 `data` 对象中。

`group_range` 聚合规则

day：返回 date_from 至 date_to（含首尾日期）之间每天的数据。
week、month、year：按完整的周、月或年聚合，并使用对应周期的最后一天作为 date。
如果某个日期、周、月或年份没有数据，对应数值将返回 0。

例如：

json

{
  "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

请求示例

curl

bash

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",
      "include_subdomains": true,
      "tag": "monthly-backlink-trend"
    }
  ]'

PHP

php

<?php

$apiUrl = 'https://api.seermartech.cn';
$endpoint = '/v3/backlinks/timeseries_new_lost_summary/live';

$postData = [
    [
        'target' => 'example.com',
        'date_from' => '2021-12-01',
        'date_to' => '2022-02-01',
        'group_range' => 'month'
    ]
];

$ch = curl_init($apiUrl . $endpoint);

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer smt_live_YOUR_KEY',
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => json_encode($postData, JSON_UNESCAPED_UNICODE)
]);

$response = curl_exec($ch);

if ($response === false) {
    throw new RuntimeException(curl_error($ch));
}

curl_close($ch);

$result = json_decode($response, true);
print_r($result);

TypeScript

typescript

import axios from "axios";

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

axios
  .post(
    "https://api.seermartech.cn/v3/backlinks/timeseries_new_lost_summary/live",
    postData,
    {
      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);
  });

Python

python

import requests

url = "https://api.seermartech.cn/v3/backlinks/timeseries_new_lost_summary/live"

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

response = requests.post(
    url,
    headers={
        "Authorization": "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
    },
    json=post_data,
)

result = response.json()

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        "请求失败。错误码：%s，错误信息：%s"
        % (result.get("status_code"), result.get("status_message"))
    )

C#

csharp

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

public class BacklinksExample
{
    public static async Task QueryAsync()
    {
        using var httpClient = new HttpClient();

        httpClient.DefaultRequestHeaders.Authorization =
            new AuthenticationHeaderValue("Bearer", "smt_live_YOUR_KEY");

        var postData = new[]
        {
            new
            {
                target = "example.com",
                date_from = "2021-12-01",
                date_to = "2022-02-01",
                group_range = "month"
            }
        };

        var content = new StringContent(
            JsonSerializer.Serialize(postData),
            Encoding.UTF8,
            "application/json"
        );

        var response = await httpClient.PostAsync(
            "https://api.seermartech.cn/v3/backlinks/timeseries_new_lost_summary/live",
            content
        );

        var result = await response.Content.ReadAsStringAsync();
        Console.WriteLine(result);
    }
}

响应结构

接口返回 JSON 数据 tasks 数组。

顶层字段

字段	类型	说明
`version`	string	当前 API 版本
`status_code`	integer	通用响应状态码。`20000` 表示请求成功。完整错误码请参考错误码文档。
`status_message`	string	通用状态说明
`time`	string	请求执行耗时，例如 `0.9756 sec.`
`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` 字段

字段	类型	说明
`target`	string	请求中的 `target`
`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	目标域名丢失的引用主域名数量

响应示例

json

{
  "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": " ದ4f7b5b0-8f8b-4c2f-9c9b-123456789abc",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.8123 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": 125,
              "lost_backlinks": 48,
              "new_referring_domains": 32,
              "lost_referring_domains": 14,
              "new_referring_main_domains": 29,
              "lost_referring_main_domains": 12
            },
            {
              "type": "backlinks_timeseries_new_lost_summary",
              "date": "2022-01-31 00:00:00 +00:00",
              "new_backlinks": 168,
              "lost_backlinks": 53,
              "new_referring_domains": 41,
              "lost_referring_domains": 17,
              "new_referring_main_domains": 37,
              "lost_referring_main_domains": 15
            },
            {
              "type": "backlinks_timeseries_new_lost_summary",
              "date": "2022-02-28 00:00:00 +00:00",
              "new_backlinks": 143,
              "lost_backlinks": 61,
              "new_referring_domains": 35,
              "lost_referring_domains": 19,
              "new_referring_main_domains": 31,
              "lost_referring_main_domains": 16
            }
          ]
        }
      ]
    }
  ]
}

> 注意：返回的 items 数量和指标值会根据目标域名、日期范围、索引数据及聚合方式变化。建议客户端根据 status_code 和 status_message 处理异常。

实用场景

绘制域名反向链接新增与丢失趋势图，帮助 SEO 团队判断外链建设效果和流失风险。
监测核心竞品的引用域名变化，识别竞品近期获得外链的渠道和推广动作。
对比不同月份的新增与丢失引用主域名数量，评估营销或数字活动的长期影响。
定位反向链接异常流失的时间段，排查页面下线、重定向错误或合作渠道失效问题。
汇总多个站点的周度或月度外链变化数据，为 SEO 报告和客户运营决策提供量化依据。

新增与丢失反向链接时间序列汇总 ​

请求说明 ​

计费说明 ​

请求参数 ​

group_range 聚合规则 ​

请求示例 ​

curl ​

PHP ​

TypeScript ​

Python ​

C# ​

响应结构 ​

顶层字段 ​

tasks 数组中的字段 ​

result 字段 ​

items 数组中的字段 ​

响应示例 ​

实用场景 ​