AI 数据：实时查询搜索量

POST /v3/ai_optimization/ai_keyword_data/keywords_search_volume/live

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

/v3/ai_optimization/ai_keyword_data/keywords_search_volume/live

用于查询指定在 AI 工中的预估搜索量。接口会返回每个最近一个月的 AI 搜索量，以及过去 12 个月的月度 AI 搜索量趋势。

AI 搜索量指标基于搜索结果页中「People Also Ask」的问题统计数据计算得出。

计费说明

本接口请求任务计费。参考价请以本平台报价为准，扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

调用限制：

每个请求只能 1 个任务。
每个任务最多提交 1000 个。平台限流以认证说明中的 30/60/120 次/分钟规则为准。
同时处理的请求数最多为 30 个。
请求体使用 UTF-8 编码的 JSON 格式。
POST 请求体是 JSON 数组，即使只提交一个任务也需要使用数组格式。

请求参数

参数名	类型	填	说明
`keywords`	array	是	查询的列表。最多 1000 个；单个最多 250 个字符。会被转换为小写格式。
`location_name`	string	条件填	地区完整名称。当未指定 `location_code` 时填。示例：`United Kingdom`。
`location_code`	integer	条件填	地区唯一标识。当未指定 `location_name` 时填。示例：`2840`。
`language_name`	string	条件填	语言完整名称。当未指定 `language_code` 时填。指定该参数后无需再指定 `language_code`。示例：`English`。
`language_code`	string	条件填	语言代码。当未指定 `language_name` 时填。指定该参数后无需再指定 `language_name`。示例：`en`。
`tag`	string	否	自定义任务标识，用于在请求与响应之间匹任务。最大长度为 255 个字符。该值会原样返回在响应的 `data` 对象中。

> location_name 与 location_code 至少填写一个；language_name 与 language_code 至少填写一个。

查询可用地区和语言

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

/v3/ai_optimization/ai_keyword_data/locations_and_languages

该接口可返回：

location_name
location_code
language_name
language_code

请求示例

cURL

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/ai_optimization/ai_keyword_data/keywords_search_volume/live" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "language_name": "English",
      "location_code": 2840,
      "keywords": [
        "iphone",
        "seo"
      ],
      "tag": "keyword-volume-demo"
    }
  ]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/ai_optimization/ai_keyword_data/keywords_search_volume/live"

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

post_data = [
    {
        "language_name": "English",
        "location_code": 2840,
        "keywords": [
            "iphone",
            "seo",
        ],
        "tag": "keyword-volume-demo",
    }
]

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 postData = [
  {
    language_name: "English",
    location_code: 2840,
    keywords: ["iphone", "seo"],
    tag: "keyword-volume-demo",
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/ai_optimization/ai_keyword_data/keywords_search_volume/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);
  });

响应结构

接口返回 JSON 对象 tasks 任务数组。

顶层字段

字段名	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	请求级状态码。`20000` 表示请求成功。完整错误码请参考错误码文档。
`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` 字段

字段名	类型	说明
`location_code`	integer	请求中使用的地区代码。
`language_code`	string	请求中使用的语言代码。
`items_count`	integer	`items` 数组中的结果数量。
`items`	array	含及 AI 搜索量数据的结果列表。

`items` 字段

字段名	类型	说明
`keyword`	string	查询的。
`ai_search_volume`	integer	该当前的 AI 搜索量率。
`ai_monthly_searches`	array	过去 12 个月的月度 AI 搜索量数据。

`ai_monthly_searches` 字段

ai_monthly_searches 是对象数组，每个对象代表某一月份的 AI 搜索量。

字段名	类型	说明
`year`	integer	年份。
`month`	integer	月份，取值范围为 1 至 12。
`ai_search_volume`	integer	对应月份的 AI 搜索量率。

响应示例

json

{
  "version": "0.1.20250526",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.3281 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": " ಕಾರ್ಯ示例任务ID",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.2010 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "ai_optimization",
        "ai_keyword_data",
        "keywords_search_volume",
        "live"
      ],
      "data": {
        "api": "ai_optimization",
        "function": "keywords_search_volume",
        "language_name": "English",
        "location_code": 2840,
        "keywords": [
          "iphone",
          "seo"
        ]
      },
      "result": [
        {
          "location_code": 2840,
          "language_code": "en",
          "items_count": 2,
          "items": [
            {
              "keyword": "iphone",
              "ai_search_volume": 21500,
              "ai_monthly_searches": [
                {
                  "year": 2025,
                  "month": 1,
                  "ai_search_volume": 19200
                },
                {
                  "year": 2025,
                  "month": 2,
                  "ai_search_volume": 21500
                }
              ]
            },
            {
              "keyword": "seo",
              "ai_search_volume": 13881,
              "ai_monthly_searches": [
                {
                  "year": 2025,
                  "month": 1,
                  "ai_search_volume": 12100
                },
                {
                  "year": 2025,
                  "month": 2,
                  "ai_search_volume": 13881
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

> 示例中的月度数据用于展示字段结构，返回的月份数量及数值以接口响应为准。

错误处理

建议根据以下字段处理异常：

通过顶层 status_code 判断请求是否成功。
通过任务级 status_code 判断任务是否成功。
通过 status_message 获取错误说明。
检查 tasks_error，确认是否存在失败任务。
对网络时、HTTP 错误和 JSON 解析失败进行重试或记录。
发生计费问题时，以响应头 X-SeerMarTech-Charge-CNY 作为扣费依据。

实用场景

筛选 AI 搜索需求较高的，优布局更容易获得 AI 工的主题，提升选题效率。
对比近 12 个月的 AI 搜索量趋势，识别增长型或衰退型主题，季度 SEO 规划。
按地区和语言评估需求，为多国家、多语言站点制定本地化策略。
批量评估列表，在发布或创建专题页前筛选更潜力的。
结合传统搜索量进行分层，区分传统搜索与 AI 搜索需求，优化资源和投放优级。

AI 数据：实时查询搜索量 ​

计费说明 ​

请求参数 ​

查询可用地区和语言 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应结构 ​

顶层字段 ​

tasks 字段 ​

result 字段 ​

items 字段 ​

ai_monthly_searches 字段 ​

响应示例 ​

错误处理 ​

实用场景 ​