LLM 提及热门页面实时查询（旧版）

GET /v3/ai_optimization/llm_mentions/locations_and_languages

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

/v3/ai_optimization/llm_mentions/top_pages/live

> 接口说明 > > 此接口为旧版路径，建议新接使用： > > /v3/ai_optimization/llm_mentions/top_mentioned_pages/live/ > > 旧路径目前仍会继续支持，暂未停用时间。

本接口根据指定的 target，聚合返回大语言模型（LLM）回答中最常被提及的页面及提及指标。结果会受到以下条件影响：

平台：google（Google AI Overview）或 chat_gpt（ChatGPT）
搜索地区
搜索语言
链接来源范围
初始数据集筛选条件

单次请求只能提交 1 个任务。平台限流以认证说明中的 30/60/120 次/分钟规则为准接口请求，单个任务的执行时间目前最长约为 120 秒。

请求地址

http

POST https://api.seermartech.cn/v3/ai_optimization/llm_mentions/top_pages/live

认证方式

请求头使用 Bearer Token：

http

Authorization: Bearer smt_live_YOUR_KEY
Content-Type: application/json

计费说明

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

请求参数

请求体为 UTF-8 编码的 JSON 数组：

json

[
  {
    "target": [
      {
        "keyword": "bmw",
        "search_scope": ["answer"]
      }
    ],
    "language_code": "en",
    "location_code": 2840,
    "platform": "google"
  }
]

任务级参数

参数	类型	填	说明
`target`	array	是	目标实体数组，最多 10 个实体。每个实体只能一个 `domain` 或一个 `keyword`，并可附带筛选参数。
`location_name`	string	否	搜索地区的完整名称。使用此参数时无需传 `location_code`。
`location_code`	integer	否	搜索地区代码。使用此参数时无需传 `location_name`。默认值为 `2840`。
`language_name`	string	否	搜索语言的完整名称。使用此参数时无需传 `language_code`。
`language_code`	string	否	搜索语言代码。默认值为 `en`。
`platform`	string	否	目标平台，可选 `google`、`chat_gpt`。默认值为 `google`。
`links_scope`	string	否	用于提取页面并聚合数据的链接范围，可选 `sources`、`search_results`。默认值为 `sources`。
`initial_dataset_filters`	array	否	聚合前应用于原始提及数据的筛选表达式，最多 8 个条件。
`items_list_limit`	integer	否	`items` 数组最多返回的页面数量，取值范围为 `1`–`10`，默认值为 `5`。
`internal_list_limit`	integer	否	部数组最多返回的数量，适用于 `sources_domain` 和 `search_results_domain`，取值范围为 `1`–`10`，默认值为 `5`。
`tag`	string	否	用户自定义任务标识，最长 255 个字符。该值会原样返回在响应任务的 `data` 对象中。

地区与语言限制

可通过以下接口查询可用的地区和语言：

/v3/ai_optimization/llm_mentions/locations_and_languages

使用 chat_gpt 平台时：

地区只能使用 United States，地区代码为 2840
语言只能使用 English，语言代码为 en

location_name 与 location_code 二选一；language_name 与 language_code 二选一。如果同时传同组参数，建议保留名称参数或代码参数中的一个。

`target` 参数

target 是目标实体数组，最多 10 个对象。每个对象以下两种实体之一：

domain：分析某个域名在 LLM 回答中的表现
keyword：分析某个在 LLM 回答中的表现

域名实体

域名实体示例：

json

{
  "domain": "en.wikipedia.org",
  "search_filter": "exclude",
  "search_scope": ["sources"],
  "include_subdomains": false
}

参数	类型	填	说明
`domain`	string	是*	目标域名。不应 `https://` 或 `www.`，最长 63 个字符。未提供 `keyword` 时填写。
`search_filter`	string	否	域名筛选方式：`include`、`exclude`。默认值为 `include`。
`search_scope`	array	否	域名出现范围，可选 `any`、`sources`、`search_results`。默认值为 `any`。
`include_subdomains`	boolean	否	是否目标域名的子域名。默认值为 `false`。

实体

实体示例：

json

{
  "keyword": "bmw",
  "search_filter": "include",
  "search_scope": ["question"],
  "match_type": "partial_match"
}

参数	类型	填	说明
`keyword`	string	是*	目标，最长 250 个字符。未提供 `domain` 时填写。
`search_filter`	string	否	筛选方式：`include`、`exclude`。默认值为 `include`。
`search_scope`	array	否	出现范围，可选 `any`、`question`、`answer`、`brand_entities`、`fan_out_queries`。默认值为 `any`。
`match_type`	string	否	匹方式：`word_match`、`partial_match`。默认值为 `word_match`。

match_type 的含义：

word_match：匹与种子的词组，也前后或中间出现词。
partial_match：匹中出现的或片段。

中的编码字符会被解码：

%## 格式的编码会被解码
+ 会被解码为空格
如需传递 %，请编码为 %25
如需传递 +，请编码为 %2B

初始数据集筛选

initial_dataset_filters 用于在聚合前筛选原始 LLM 提及数据，从而限制参与统计的记录数量。

每个筛选条件通常由以下结构组成：

json

[
  "字段名",
  "运算符",
  "比较值"
]

多个条件之间需要指定逻辑 and 或 or。支持的运算符：

text

=、<>、in、not_in、like、not_like、ilike、not_ilike、match、not_match

like 和 not_like 支持使用 % 匹零个或多个字符。

示例：

json

"initial_dataset_filters": [
  ["ai_search_volume", ">", 10]
]

curl 示例

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/ai_optimization/llm_mentions/top_pages/live" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "language_code": "en",
      "location_code": 2840,
      "platform": "google",
      "target": [
        {
          "keyword": "bmw",
          "search_scope": ["answer"]
        },
        {
          "keyword": "auto",
          "search_scope": ["question"],
          "match_type": "partial_match"
        }
      ],
      "links_scope": "sources",
      "initial_dataset_filters": [
        ["ai_search_volume", ">", 10]
      ],
      "items_list_limit": 3,
      "internal_list_limit": 2
    }
  ]'

Python 示例

python

import requests

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

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

post_data = [
    {
        "language_code": "en",
        "location_code": 2840,
        "platform": "google",
        "target": [
            {
                "keyword": "bmw",
                "search_scope": ["answer"],
            },
            {
                "keyword": "auto",
                "search_scope": ["question"],
                "match_type": "partial_match",
            },
        ],
        "links_scope": "sources",
        "initial_dataset_filters": [
            ["ai_search_volume", ">", 10],
        ],
        "items_list_limit": 3,
        "internal_list_limit": 2,
    }
]

response = requests.post(url, headers=headers, json=post_data)
result = response.json()

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        f"请求失败：{result.get('status_code')} "
        f"{result.get('status_message')}"
    )

TypeScript 示例

typescript

import axios from "axios";

const response = await axios.post(
  "https://api.seermartech.cn/v3/ai_optimization/llm_mentions/top_pages/live",
  [
    {
      language_code: "en",
      location_code: 2840,
      platform: "google",
      target: [
        {
          keyword: "bmw",
          search_scope: ["answer"],
        },
        {
          keyword: "auto",
          search_scope: ["question"],
          match_type: "partial_match",
        },
      ],
      links_scope: "sources",
      initial_dataset_filters: [
        ["ai_search_volume", ">", 10],
      ],
      items_list_limit: 3,
      internal_list_limit: 2,
    },
  ],
  {
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
  }
);

const result = response.data;

if (result.status_code === 20000) {
  console.log(result);
} else {
  console.error(result.status_code, result.status_message);
}

响应结构

接口返回 JSON 对象 tasks 数组：

json

{
  "version": "0.1.20251208",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "18.5294 sec.",
  "cost": 0.101,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "任务 UUID",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "18.5294 sec.",
      "cost": 0.101,
      "result_count": 1,
      "path": [
        "v3",
        "ai_optimization",
        "llm_mentions",
        "top_pages",
        "live"
      ],
      "data": {
        "api": "ai_optimization",
        "function": "top_pages",
        "language_code": "en",
        "location_code": 2840,
        "platform": "google",
        "target": [
          {
            "keyword": "bmw",
            "search_scope": ["answer"]
          }
        ],
        "links_scope": "sources",
        "items_list_limit": 3,
        "internal_list_limit": 2
      },
      "result": [
        {
          "total": {
            "location": [],
            "language": [],
            "platform": [],
            "sources_domain": [],
            "search_results_domain": null,
            "brand_entities_title": null,
            "brand_entities_category": null
          },
          "items": [
            {
              "key": "https://example.com/page-a",
              "location": [],
              "language": [],
              "platform": [],
              "sources_domain": [],
              "search_results_domain": null,
              "brand_entities_title": null,
              "brand_entities_category": null
            }
          ]
        }
      ]
    }
  ]
}

响应顶层字段

字段	类型	说明
`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	当前请求的 API 路径。
`data`	object	本次 POST 请求中提交的任务参数。
`result`	array	查询结果数组。

`result` 字段

每个结果对象：

字段	类型	说明
`total`	object	所有热门页面的聚合 LLM 提及指标汇总。
`items`	array	各热门页面的详细提及指标。

`total` 与页面指标字段

total 对象和 items 中的每个页面对象均可以下分组数组：

字段	类型	说明
`location`	array	按地理位置分组的提及指标。
`language`	array	按语言分组的提及指标。
`platform`	array	按 AI 平台分组的提及指标。
`sources_domain`	array	LLM 回答中作为引用来源出现的热门域名。
`search_results_domain`	array/null	与 LLM 查询、出现在搜索结果中的热门域名。
`brand_entities_title`	array/null	与目标的品牌实体标题。
`brand_entities_category`	array/null	与目标的品牌实体类别。

：

total 中的数组表示跨所有热门页面的聚合数据。
items 中的数组表示当前页面自身的指标。
sources_domain 与 search_results_domain 的返回数量受 internal_list_limit 限制。
items 返回数量受 items_list_limit 限制。
某些分组在当前平台或数据集中没有结果时，可能返回空数组或 null。

分组字段

上述分组数组中的每个对象通常以下字段：

字段	类型	说明
`type`	string	素类型，通常为 `group_element`。
`key`	string	分组标识。对于域名分组通常为域名，对于页面列表则为页面 URL。
`mentions`	integer	LLM 提及次数，即目标或域名与该分组标识时被提及的次数。
`ai_search_volume`	integer	当前的 AI 搜索量指标。
`impressions`	integer/null	AI 展示量指标。该字段已弃用，通常返回 `null`。

`items` 页面字段

字段	类型	说明
`key`	string	被发现的页面 URL，该页面曾出现在指定目标对应的 LLM 提及数据中。
`location`	array	该页面按地理位置分组的提及指标。
`language`	array	该页面按语言分组的提及指标。
`platform`	array	该页面按 AI 平台分组的提及指标。
`sources_domain`	array	与该页面、被 LLM 回答引用的来源域名。
`search_results_domain`	array/null	与该页面、出现在 LLM 查询搜索结果中的域名。
`brand_entities_title`	array/null	与该页面的品牌实体标题。
`brand_entities_category`	array/null	与该页面的品牌实体类别。

状态码处理

建议客户端同时检查：

HTTP 状态码
顶层 status_code
tasks[].status_code
tasks[].status_message

当 status_code 不等于 20000 时，应记录错误信息并根据业务需要重试或结束任务处理。

实用场景

识别高频引用页面：找出目标在 AI 回答中最常引用的页面，指导团队分析页面结构并制定越策略。
对比品牌与竞品：通过 domain 或 keyword 同时查询多个目标，比较不同品牌在 LLM 回答中的提及次数和引用来源。
定位权威来源域名：分析 sources_domain，发现行业中持续影响 AI 回答的媒体、百科、评测站和专业网站。
筛选高价值 AI 查询数据：使用 initial_dataset_filters 按 ai_search_volume 等指标过滤原始数据，减少低价值结果并聚焦高潜力主题。
评估页面级 GEO 表现：结合 items、platform 和 language 分组指标，评估不同页面在 Google AI Overview 或 ChatGPT 中的可见度。

LLM 提及热门页面实时查询（旧版） ​

请求地址 ​

认证方式 ​

计费说明 ​

请求参数 ​

任务级参数 ​

地区与语言限制 ​

target 参数 ​

域名实体 ​

实体 ​

初始数据集筛选 ​

curl 示例 ​

Python 示例 ​

TypeScript 示例 ​

响应结构 ​

响应顶层字段 ​

tasks 字段 ​

result 字段 ​

total 与页面指标字段 ​

分组字段 ​

items 页面字段 ​

状态码处理 ​

实用场景 ​

LLM 提及热门页面实时查询（旧版）

请求地址

认证方式

计费说明

请求参数

任务级参数

地区与语言限制

`target` 参数

域名实体

实体

初始数据集筛选

curl 示例

Python 示例

TypeScript 示例

响应结构

响应顶层字段

`tasks` 字段

`result` 字段

`total` 与页面指标字段

分组字段

`items` 页面字段

状态码处理

实用场景