SeerMarTech API 文档

主题

AI 优化：LLM 提及历史数据（实时） ​

POST /v3/ai_optimization/llm_mentions/historical/live

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

/v3/ai_optimization/llm_mentions/historical/live

本接口按月返回请求中 target 数组所指定或域名的 LLM 提及历史指标。每个月返回该目标的 mentions 总提及次数和 ai_search_volume AI 搜索量指标。

返回结果取决于请求中指定的平台、位置和语言：

  • google：Google AI Overview
  • chat_gpt：ChatGPT

历史数据最早可查询至 2025-08-01。

接口信息 ​

  • 请求方法：POST
  • 请求地址：https://api.seermartech.cn/v3/ai_optimization/llm_mentions/historical/live
  • 请求格式：JSON，UTF-8 编码
  • 单次请求任务数：每次调用只能 1 个任务 平台限流以认证说明中的 30/60/120 次/分钟规则为准/分钟
  • 最长执行时间：当前最长约 120 秒

扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数 ​

请求体是 JSON 数组：

json
[
  {
    "target": [
      {
        "domain": "en.wikipedia.org",
        "search_filter": "exclude",
        "search_scope": ["any"],
        "include_subdomains": false
      },
      {
        "keyword": "bmw",
        "search_filter": "include",
        "search_scope": ["answer"],
        "match_type": "partial_match"
      }
    ],
    "date_from": "2025-08-01",
    "date_to": "2025-12-01",
    "location_code": 2840,
    "language_code": "en",
    "platform": "google",
    "tag": "brand-history-001"
  }
]

> target 中至少需要一个 search_filter 为 include 的域名实体或实体。

任务参数 ​

参数类型填说明
targetarray是目标实体数组，最多 10 个实体。每个实体只能一个 domain 或一个 keyword。
date_fromstring否查询起始日期，格式为 yyyy-mm-dd，最早支持 2025-08-01。
date_tostring否查询结束日期，格式为 yyyy-mm-dd。date_from 不能晚于 date_to。
location_namestring否搜索位置的完整名称。使用此参数时无需传 location_code。
location_codeinteger否搜索位置代码。默认值为 2840。使用此参数时无需传 location_name。
language_namestring否搜索语言的完整名称。使用此参数时无需传 language_code。
language_codestring否搜索语言代码。默认值为 en。使用此参数时无需传 language_name。
platformstring否目标平台，可选值：chat_gpt、google。未指定时返回两个平台的数据。
tagstring否自定义任务标识，最长 255 个字符。该值会原样返回在响应的 data 对象中。

位置和语言的可选值可通过以下接口查询：

/v3/ai_optimization/llm_mentions/locations_and_languages

平台限制 ​

  • chat_gpt 支持 United States 位置。
  • chat_gpt 支持 English 语言。
  • 使用代码时，chat_gpt 支持：
    • location_code: 2840
    • language_code: en
  • 当域名实体的 search_scope 设置为 search_results 时支持查询 chat_gpt 数据。

target 参数 ​

域名实体 ​

域名实体用于分析某个域名在 LLM 回答或来源中的提及。

json
{
  "domain": "en.wikipedia.org",
  "search_filter": "exclude",
  "search_scope": ["any"],
  "include_subdomains": false
}
参数类型填说明
domainstring条件填目标域名。未指定 keyword 时填，最长 63 个字符。域名不得 https:// 或 www.。
search_filterstring否域名过滤方式，可选 include、exclude，默认值为 include。
search_scopearray否域名搜索范围，可选 any、sources、search_results，默认值为 any。
include_subdomainsboolean否是否目标域名的子域名。true 表示，默认值为 false。

search_scope 取值说明：

  • any：在所有支持范围搜索。
  • sources：在来源中搜索。
  • search_results：在搜索结果中搜索适用于 chat_gpt。

实体 ​

实体用于分析指定在 LLM 回答及中的提及。

json
{
  "keyword": "bmw",
  "search_filter": "include",
  "search_scope": ["answer"],
  "match_type": "partial_match"
}
参数类型填说明
keywordstring条件填目标。未指定 domain 时填，最长 250 个字符。
search_filterstring否过滤方式，可选 include、exclude，默认值为 include。
search_scopearray否搜索范围，可选 any、question、answer、brand_entities、fan_out_queries，默认值为 any。
match_typestring否匹方式，可选 word_match、partial_match，默认值为 word_match。

match_type 取值说明：

  • word_match：词匹。会匹附加词的完整词组。例如搜索 light，可匹 light bulb、light switch。
  • partial_match：子字符串匹。只要指定字符序列即可匹，即使该序列位于更长单词。例如搜索 light，可匹 lighting、highlight。

认证方式 ​

请求时使用 Bearer Token：

bash
curl --location --request POST \
  "https://api.seermartech.cn/v3/ai_optimization/llm_mentions/historical/live" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "target": [
        {
          "domain": "en.wikipedia.org",
          "search_filter": "exclude",
          "search_scope": ["any"]
        },
        {
          "keyword": "bmw",
          "search_filter": "include",
          "search_scope": ["answer"],
          "match_type": "partial_match"
        }
      ],
      "date_from": "2025-08-01",
      "date_to": "2025-12-01",
      "location_code": 2840,
      "language_code": "en",
      "platform": "google"
    }
  ]'

Python 示例 ​

python
import requests

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

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

post_data = [
    {
        "language_code": "en",
        "location_code": 2840,
        "platform": "google",
        "target": [
            {
                "domain": "en.wikipedia.org",
                "search_filter": "exclude",
                "search_scope": ["any"],
            },
            {
                "keyword": "bmw",
                "search_scope": ["answer"],
                "match_type": "partial_match",
            },
        ],
        "date_from": "2025-08-01",
        "date_to": "2025-12-01",
    }
]

response = requests.post(url, headers=headers, json=post_data, timeout=120)
response.raise_for_status()

result = response.json()
print(result)

TypeScript 示例 ​

typescript
import axios from "axios";

const response = await axios.post(
  "https://api.seermartech.cn/v3/ai_optimization/llm_mentions/historical/live",
  [
    {
      language_code: "en",
      location_code: 2840,
      platform: "google",
      target: [
        {
          domain: "en.wikipedia.org",
          search_filter: "exclude",
          search_scope: ["any"],
        },
        {
          keyword: "bmw",
          search_scope: ["answer"],
          match_type: "partial_match",
        },
      ],
      date_from: "2025-08-01",
      date_to: "2025-12-01",
    },
  ],
  {
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
    timeout: 120000,
  }
);

console.log(response.data);

响应结构 ​

接口返回 JSON 数据 tasks 数组。

json
{
  "version": "0.1.20251208",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "1.9593 sec.",
  "cost": 0.101,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "1.8421 sec.",
      "cost": 0.101,
      "result_count": 1,
      "path": [
        "v3",
        "ai_optimization",
        "llm_mentions",
        "historical",
        "live"
      ],
      "data": {
        "language_code": "en",
        "location_code": 2840,
        "platform": "google",
        "target": [
          {
            "keyword": "bmw",
            "search_filter": "include",
            "search_scope": ["answer"],
            "match_type": "partial_match"
          }
        ],
        "date_from": "2025-08-01",
        "date_to": "2025-12-01"
      },
      "result": [
        {
          "items_count": 2,
          "items": [
            {
              "year": 2025,
              "month": 8,
              "metrics": {
                "mentions": 120,
                "ai_search_volume": 860
              }
            },
            {
              "year": 2025,
              "month": 9,
              "metrics": {
                "mentions": 145,
                "ai_search_volume": 910
              }
            }
          ]
        }
      ]
    }
  ]
}

响应字段 ​

顶层字段 ​

字段类型说明
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查询结果数组。

发生异常或错误时，应根据 status_code 和 status_message 进行错误处理。

result 与 items 字段 ​

字段类型说明
items_countintegeritems 数组中返回的数量。
itemsarrayLLM 提及历史指标数组。每个对象对应一个自然月。
yearinteger年份。
monthinteger月份，取值范围为 1 至 12。
metricsobject指定月份的聚合提及指标。
metrics.mentionsinteger该月目标被 LLM 提及的总次数。
metrics.ai_search_volumeinteger该月所有目标提及对应的 AI 搜索量总值。

实用场景 ​

  • 对比品牌按月的 LLM 提及次数，识别品牌在 AI 搜索结果中的增长或下滑趋势。
  • 跟踪竞品域名在 AI 来源和搜索结果中的出现，评估竞争品牌的 AI 可见度。
  • 分析的月度 ai_search_volume 变化，优安排高潜力主题的生产和 SEO 优化。
  • 区分问题、答案和品牌实体中的提及，定位品牌被 AI 识别和引用的场景。
  • 结合不同平台、位置和语言进行历史对比，评估同一品牌在 Google AI Overview 与 ChatGPT 中的表现差异。

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

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