批量查询新增与流失引荐域名

POST /v3/backlinks/bulk_new_lost_referring_domains/live

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

/v3/backlinks/bulk_new_lost_referring_domains/live

用于批量查询指定域名、子域名或网页在指定时间范围新增和流失的引荐域名数量。

当 targets 中传域名时，接口统计的是该根域名及子域名的数据。例如，传 example.com 后，结果会覆盖 example.com、app.example.com 等子域名。

历史数据最长支持查询最近 365 天。

请求地址

text

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

计费说明

每次成功提交请求都会产生相应费用。原始文档未提供固定单价，扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求限制：

所有 POST 数据使用 UTF-8 编码的 JSON 格式。
每个 Live API 请求只能一个任务对象。
targets 最多支持 1000 个域名、子域名或网页。平台限流以认证说明中的 30/60/120 次/分钟规则为准。
同时进行的请求数最多为 30 个。

请求参数

请求体是 JSON 数组，数组中一个任务对象。

参数	类型	填	说明
`targets`	array	是	要查询新增与流失引荐域名的域名、子域名或网页列表，最多 1000 个。域名或子域名不能 `https://` 和 `www.`；网页使用协议的完整 URL。
`date_from`	string	否	统计起始日期，用于判断引荐域名是新增还是流失。格式为 `yyyy-mm-dd`。
`tag`	string	否	用户自定义任务标识，最长 255 个字符。该值会原样返回在响应的 `data` 对象中，可用于请求与结果。

`targets` 参数格式

域名：example.com
子域名：blog.example.com
网页：https://example.com/article/

`date_from` 判断规则

指定日期之后首次出现在索引中的引荐域名，会计为新增引荐域名。
指定日期之前存在、但在指定日期之后未再发现的引荐域名，会计为流失引荐域名。
默认值为当前日期前一个月。
最早可设置为当前日期前一年。
例如当前日期为 2023-10-13：
- 默认值为 2023-09-13
- 最早可用日期为 2022-10-13

请求示例

json

[
  {
    "targets": [
      "example.com",
      "blog.example.com",
      "https://example.com/products/"
    ],
    "date_from": "2023-09-01",
    "tag": "monthly-backlink-review"
  }
]

响应结构

接口返回 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` 字段

字段	类型	说明
`items_count`	integer	`items` 数组中的结果数量
`items`	array	引荐域名统计结果
`target`	string	请求中提交的目标域名、子域名或网页
`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": "10.7157 sec.",
  "cost": 0.0203,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "10.5000 sec.",
      "cost": 0.0203,
      "result_count": 1,
      "path": [
        "v3",
        "backlinks",
        "bulk_new_lost_referring_domains",
        "live"
      ],
      "data": {
        "api": "backlinks",
        "function": "bulk_new_lost_referring_domains",
        "targets": [
          "example.com",
          "blog.example.com",
          "https://example.com/products/"
        ],
        "date_from": "2023-09-01",
        "tag": "monthly-backlink-review"
      },
      "result": [
        {
          "items_count": 3,
          "items": [
            {
              "target": "example.com",
              "new_referring_domains": 128,
              "lost_referring_domains": 76,
              "new_referring_main_domains": 101,
              "lost_referring_main_domains": 64
            },
            {
              "target": "blog.example.com",
              "new_referring_domains": 42,
              "lost_referring_domains": 18,
              "new_referring_main_domains": 35,
              "lost_referring_main_domains": 16
            },
            {
              "target": "https://example.com/products/",
              "new_referring_domains": 9,
              "lost_referring_domains": 4,
              "new_referring_main_domains": 8,
              "lost_referring_main_domains": 4
            }
          ]
        }
      ]
    }
  ]
}

错误处理

建议根据请求级和任务级状态码分别处理异常：

检查顶层 status_code，确认请求是否被成功接收。
检查 tasks_error，确认是否存在执行失败的任务。
检查每个任务的 status_code 和 status_message，定位失败原因。
生产环境应实现重试、限流和错误记录机制。

代码示例

cURL

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/backlinks/bulk_new_lost_referring_domains/live" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "targets": [
        "example.com",
        "blog.example.com",
        "https://example.com/products/"
      ],
      "date_from": "2023-09-01",
      "tag": "monthly-backlink-review"
    }
  ]'

PHP

php

<?php

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

$postData = [
    [
        'targets' => [
            'example.com',
            'blog.example.com',
            'https://example.com/products/'
        ],
        'date_from' => '2023-09-01',
        'tag' => 'monthly-backlink-review'
    ]
];

$ch = curl_init($apiUrl);

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_SLASHES)
]);

$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 = [
  {
    targets: [
      "example.com",
      "blog.example.com",
      "https://example.com/products/"
    ],
    date_from: "2023-09-01",
    tag: "monthly-backlink-review"
  }
];

axios({
  method: "post",
  url: "https://api.seermartech.cn/v3/backlinks/bulk_new_lost_referring_domains/live",
  headers: {
    Authorization: "Bearer smt_live_YOUR_KEY",
    "Content-Type": "application/json"
  },
  data: postData
})
  .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/bulk_new_lost_referring_domains/live"

post_data = [
    {
        "targets": [
            "example.com",
            "blog.example.com",
            "https://example.com/products/"
        ],
        "date_from": "2023-09-01",
        "tag": "monthly-backlink-review"
    }
]

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.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

public class BacklinkDemo
{
    public static async Task QueryNewLostReferringDomains()
    {
        using var httpClient = new HttpClient();

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

        var postData = new[]
        {
            new
            {
                targets = new[]
                {
                    "example.com",
                    "blog.example.com",
                    "https://example.com/products/"
                },
                date_from = "2023-09-01",
                tag = "monthly-backlink-review"
            }
        };

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

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

        var result = await response.Content.ReadAsStringAsync();

        if (response.IsSuccessStatusCode)
        {
            // 处理成功结果
            Console.WriteLine(result);
        }
        else
        {
            // 处理 HTTP 异常
            Console.WriteLine($"HTTP 错误：{response.StatusCode}");
            Console.WriteLine(result);
        }
    }
}

实用场景

监控重点项目的新增引荐域名，及时发现获得的外部链接资源，评估推广和活动带来的 SEO 增长。
识别流失引荐域名，定位外链减少的目标页面或网站，支持外链恢复、站点迁移检查和链接质量维护。
批量对比竞品的外链变化，分析竞品在指定时间段获得或失去的引荐域名，为链接建设策略提供依据。
评估页面级外链表现，比较不同落地页新增与流失的引荐域名数量，优化布局和推广重点。
建立定期外链监控报表，结合 date_from 和 tag 按月或按周追踪域名级、主域名级的引荐变化趋势。

批量查询新增与流失引荐域名 ​

请求地址 ​

计费说明 ​

请求参数 ​

targets 参数格式 ​

date_from 判断规则 ​

请求示例 ​

响应结构 ​

顶层字段 ​

tasks 任务字段 ​

result 字段 ​

响应示例 ​

错误处理 ​

代码示例 ​

cURL ​

PHP ​

TypeScript ​

Python ​

C# ​

实用场景 ​