SeerMarTech API 文档

主题

AI 优化：LLM 提及次数时间序列差值（实时） ​

POST /v3/ai_optimization/llm_mentions/timeseries_delta/live

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

/v3/ai_optimization/llm_mentions/timeseries_delta/live

实时获取两个指定日期之间，目标或域名在 LLM 回复中的提及次数及 AI 搜索量差值。查询结果取决于目标实体、平台、地区、语言及时间分组方式。

历史数据最早支持 2025-08-01。每次调用只能提交 1 个任务，每个任务最多 10 个目标实体。任务最长执行时间约为 120 秒。

计费说明 ​

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

响应中的 cost 字段（平台原始 USD 成本兼容字段）为任务成本参考信息，建议以人民币计费响应头作为最终扣费依据。

请求参数 ​

所有 POST 请求均须使用 UTF-8 编码的 JSON 格式，请求体是数组：

json
[
  {
    "target": [
      {
        "domain": "example.com",
        "search_filter": "include",
        "search_scope": ["any"],
        "include_subdomains": false
      }
    ],
    "platform": "google",
    "date_from": "2025-08-01",
    "date_to": "2025-12-01",
    "group_range": "month",
    "location_code": 2840,
    "language_code": "en",
    "tag": "monthly-domain-delta"
  }
]

顶层任务参数 ​

参数类型填说明
targetarray是目标实体数组，最多 10 个实体。每个实体只能一个 domain 或一个 keyword。请求至少需要一个 search_filter 为 include 的域名或实体。
date_fromstring是时间范围起始日期，格式为 yyyy-mm-dd，最早支持 2025-08-01。
date_tostring是时间范围结束日期，格式为 yyyy-mm-dd。该值不能早于 date_from。
group_rangestring是时间序列分组方式，可选值：day、week、month、year。
location_namestring否搜索地区名。设置后无需设置 location_code。未设置时默认使用 location_code=2840。
location_codeinteger否搜索地区代码。设置后无需设置 location_name，默认值为 2840。
language_namestring否搜索语言名。设置后无需设置 language_code。未设置时默认使用 language_code=en。
language_codestring否搜索语言代码。设置后无需设置 language_name，默认值为 en。
platformstring否目标平台，可选值：google、chat_gpt。默认值为 google。未指定时，可能返回两个平台的数据。
tagstring否用户自定义任务标识，最长 255 个字符。该值会原样返回在响应的 data 对象中。

可通过以下接口获取可用的地区和语言：

/v3/ai_optimization/llm_mentions/locations_and_languages

> chat_gpt 平台目前支持美国地区（United States 或 2840）和英语（English 或 en）。

target 参数 ​

target 是由域名实体或实体组成的数组，最多 10 个对象。

域名实体 ​

域名实体示例：

json
{
  "domain": "example.com",
  "search_filter": "include",
  "search_scope": ["any"],
  "include_subdomains": false
}
参数类型填说明
domainstring条件填目标域名。未设置 keyword 时填，最长 63 个字符。请勿 https:// 或 www.。
search_filterstring否域名筛选方式：include 或 exclude。默认值为 include。
search_scopearray否域名搜索范围，可选值：any、sources、search_results。默认值为 any。使用 search_results 时 chat_gpt 平台提供数据。
include_subdomainsboolean否是否将目标域名的子域名纳搜索。默认值为 false。

实体 ​

实体示例：

json
{
  "keyword": "新能源汽车",
  "search_filter": "include",
  "search_scope": ["any"],
  "match_type": "word_match"
}
参数类型填说明
keywordstring条件填目标。未设置 domain 时填，最长 250 个字符。
search_filterstring否筛选方式：include 或 exclude。默认值为 include。
search_scopearray否搜索范围，可选值：any、question、answer、brand_entities、fan_out_queries。默认值为 any。
match_typestring否匹方式，默认值为 word_match。

match_type 支持以下取值：

  • word_match：词语匹，可匹前后或短语带有词语的结果。例如搜索 light，可匹 light bulb、light switch。
  • partial_match：子字符串匹，可匹指定字符序列的结果，即使该序列位于更长单词。例如搜索 light，可匹 lighting、highlight。

地区与语言参数 ​

location_name 与 location_code 二选一；language_name 与 language_code 二选一。

参数类型默认值说明
location_namestring—搜索地区名。
location_codeinteger2840搜索地区代码。
language_namestring—搜索语言名。
language_codestringen搜索语言代码。

请求示例 ​

cURL ​

bash
curl --location --request POST \
  "https://api.seermartech.cn/v3/ai_optimization/llm_mentions/timeseries_delta/live" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "target": [
        {
          "domain": "example.com",
          "search_filter": "include",
          "search_scope": ["any"]
        },
        {
          "keyword": "新能源汽车",
          "search_scope": ["answer"],
          "match_type": "partial_match"
        }
      ],
      "platform": "google",
      "location_code": 2840,
      "language_code": "en",
      "date_from": "2025-08-01",
      "date_to": "2025-12-01",
      "group_range": "month",
      "tag": "monthly-delta"
    }
  ]'

Python ​

python
import requests

url = "https://api.seermartech.cn/v3/ai_optimization/llm_mentions/timeseries_delta/live"

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

payload = [
    {
        "target": [
            {
                "domain": "example.com",
                "search_filter": "include",
                "search_scope": ["any"],
            },
            {
                "keyword": "新能源汽车",
                "search_scope": ["answer"],
                "match_type": "partial_match",
            },
        ],
        "platform": "google",
        "location_code": 2840,
        "language_code": "en",
        "date_from": "2025-08-01",
        "date_to": "2025-12-01",
        "group_range": "month",
        "tag": "monthly-delta",
    }
]

response = requests.post(url, headers=headers, json=payload, timeout=150)
response.raise_for_status()
result = response.json()

if result.get("status_code") == 20000:
    print(result)
else:
    print(result.get("status_message"))

TypeScript ​

typescript
import axios from "axios";

const response = await axios.post(
  "https://api.seermartech.cn/v3/ai_optimization/llm_mentions/timeseries_delta/live",
  [
    {
      target: [
        {
          domain: "example.com",
          search_filter: "include",
          search_scope: ["any"],
        },
        {
          keyword: "新能源汽车",
          search_scope: ["answer"],
          match_type: "partial_match",
        },
      ],
      platform: "google",
      location_code: 2840,
      language_code: "en",
      date_from: "2025-08-01",
      date_to: "2025-12-01",
      group_range: "month",
      tag: "monthly-delta",
    },
  ],
  {
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
    timeout: 150000,
  }
);

console.log(response.data);

响应说明 ​

接口返回 JSON 数据，核心结构如下：

json
{
  "version": "0.1.20260527",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "2.1770 sec.",
  "cost": 0.101,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "2.1770 sec.",
      "cost": 0.101,
      "result_count": 1,
      "path": [
        "v3",
        "ai_optimization",
        "llm_mentions",
        "timeseries_delta",
        "live"
      ],
      "data": {
        "api": "ai_optimization",
        "function": "timeseries_delta",
        "target": [
          {
            "keyword": "新能源汽车",
            "search_filter": "include"
          }
        ],
        "platform": "google",
        "language_code": "en",
        "location_code": 2840,
        "date_from": "2025-08-01",
        "date_to": "2025-12-01",
        "group_range": "month"
      },
      "result": [
        {
          "items_count": 4,
          "items": [
            {
              "date": "2025-09-01",
              "delta_mentions": 12,
              "delta_ai_search_volume": 180
            }
          ]
        }
      ]
    }
  ]
}

顶层响应字段 ​

字段类型说明
versionstring当前 API 版本。
status_codeinteger局状态码。20000 表示请求成功。
status_messagestring局状态信息。
timestring请求执行耗时，单位为秒。
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
tasks_countintegertasks 数组中的任务总数。
tasks_errorintegertasks 数组中执行失败的任务数。
tasksarray任务结果数组。

tasks 字段 ​

字段类型说明
idstring任务唯一标识，UUID 格式。
status_codeinteger任务状态码，通常在 10000 至 60000 范围。
status_messagestring任务状态信息。
timestring任务执行耗时。
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
result_countintegerresult 数组中的数量。
patharray请求 API 的路径组成部分。
dataobject与提交任务时使用的参数基本一致。
resultarray任务结果数组。

result 与 items 字段 ​

字段类型说明
items_countintegeritems 数组中返回的数据条数。
itemsarrayLLM 提及次数时间序列差值数据。
datestring数据对应日期，格式为 yyyy-mm-dd。
delta_mentionsintegerLLM 提及次数差值，即当前时间点与前一个时间点之间的 mentions 差值。
delta_ai_search_volumeintegerAI 搜索量差值，即当前时间点与前一个时间点之间的 ai_search_volume 差值。

错误处理 ​

建议同时检查以下状态字段：

  • HTTP 状态码；
  • 顶层 status_code；
  • 任务级 tasks[].status_code；
  • 对应的 status_message；
  • tasks_error 是否大于 0。

完整错误码请参考：

/v3/appendix/errors

实用场景 ​

  • 监测品牌提及变化：按周或按月比较品牌域名在 AI 回复中的提及增减，评估品牌在生成式搜索中的趋势。
  • 分析热度波动：比较目标的 AI 搜索量差值，识别需求增长或下降的时间节点。
  • 评估优化效果：在发布或 SEO 调整前后对比 LLM 提及次数，判断优化是否提升了 AI 结果中的品牌可见度。
  • 定位平台差异：分别查询 google 与 chat_gpt 的时间序列差值，比较不同 AI 平台对同一品牌或的覆盖变化。
  • 筛选答案来源表现：结合 search_scope 与域名筛选条件，分析目标网站在 AI 来源或搜索结果中的提及变化，为和权威性建设提供依据。

统一入口：官网 · LLM API · 控制台

© 2026 SeerMarTech · GEO · SEO 营销数据 API