content_analysis/category_trends/live

POST /v3/content_analysis/category_trends/live

#分析：类别趋势（实时）

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

/v3/content_analysis/category_trends/live

用于获取指定类别、页面类型和日期范围的引用趋势数据引用总量、排名、引用来源域名、感倾向、文本类别、页面类别、国家和语言分布等。

历史数据最早可查询至 2022-10-31。

计费说明

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

请求限制

所有 POST 请求体使用 UTF-8 编码的 JSON 格式。
请求体是 JSON 数组：[{ ... }]。
每次实时 API 请求最多 1 个任务。平台限流以认证说明中的 30/60/120 次/分钟规则为准。
同时发送的请求数最多为 30 个。
支持设置返回结果数量、筛选条件和排序方式。

请求参数

参数名	类型	填	说明
`category_code`	integer	是	目标类别代码。完整类别列表请参考 `/v3/content_analysis/categories/`。
`page_type`	array	否	按页面类型筛选数据。可选值：`ecommerce`、`news`、`blogs`、`message-boards`、`organization`。
`search_mode`	string	否	结果分组方式。<br>`as_is`：返回目标类别的引用数据。<br>`one_per_domain`：每个域名返回一条目标类别引用数据。<br>默认值：`as_is`。
`internal_list_limit`	integer	否	限制数组中的最大数量，适用于 `top_domains`、`text_categories`、`page_categories`、`countries`、`languages`。默认值：`1`，最大值：`20`。
`date_from`	string	是	查询时间范围的开始日期。最早支持 `2022-10-31`。格式为 `yyyy-mm-dd`，例如 `2022-10-31`。
`date_to`	string	否	查询时间范围的结束日期。未指定时默认使用当天日期。格式为 `yyyy-mm-dd`。
`date_group`	string	否	结果的时间分组方式。可选值：`day`、`week`、`month`。默认值：`month`。
`initial_dataset_filters`	array	否	初始数据集筛选条件，用于筛选搜索结果字段。最多支持 8 个筛选条件。条件之间指定逻辑运算符 `and` 或 `or`。
`rank_scale`	string	否	设置 `rank` 字段的计算和展示范围。<br>`one_hundred`：0–100。<br>`one_thousand`：0–1000。<br>默认值：`one_thousand`。
`tag`	string	否	自定义任务标识，最长 255 个字符。该值会原样返回在响应的 `data` 对象中，可用于请求与结果。

`initial_dataset_filters` 支持的运算符

支持以下运算符：

regex、not_regex、<、<=、>、>=、=、<>、in、not_in、like、not_like、has、has_not、match、not_match

使用 like 和 not_like 时，可使用 % 匹零个或多个字符。

筛选条件示例：

json

[
  ["page_type", "=", "news"],
  "and",
  ["country", "in", ["US", "GB"]]
]

筛选语法，请参考分析接口筛选条件说明。

请求示例

cURL

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/content_analysis/category_trends/live" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "category_code": 10994,
      "search_mode": "as_is",
      "date_from": "2022-10-31",
      "date_group": "month",
      "internal_list_limit": 10
    }
  ]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/content_analysis/category_trends/live"

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

payload = [
    {
        "category_code": 10994,
        "search_mode": "as_is",
        "date_from": "2022-10-31",
        "date_group": "month",
    }
]

response = requests.post(url, headers=headers, json=payload)
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 payload = [
  {
    category_code: 10994,
    search_mode: "as_is",
    date_from: "2022-10-31",
    date_group: "month",
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/content_analysis/category_trends/live",
    payload,
    {
      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 对象，核心结构如下：

json

{
  "version": "0.1.20220819",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "19.4363 sec.",
  "cost": 0.02009,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "19.4210 sec.",
      "cost": 0.02009,
      "result_count": 2,
      "path": [
        "v3",
        "content_analysis",
        "category_trends",
        "live"
      ],
      "data": {
        "category_code": 10994,
        "search_mode": "as_is",
        "date_from": "2022-10-31",
        "date_group": "month"
      },
      "result": [
        {
          "type": "content_analysis_trends",
          "date": "2022-10-31",
          "total_count": 1430023,
          "rank": 613,
          "top_domains": [
            {
              "domain": "example.com",
              "count": 12500
            }
          ],
          "sentiment_connotations": {
            "anger": 33,
            "fear": 12,
            "happiness": 32457,
            "love": 4976,
            "sadness": 290,
            "share": 33841,
            "neutral": 100,
            "fun": 1212
          },
          "connotation_types": {
            "positive": 390289,
            "negative": 135916,
            "neutral": 589516
          },
          "text_categories": [
            {
              "category": "Technology",
              "count": 112695
            }
          ],
          "page_categories": [
            {
              "category": "Computers",
              "count": 54264
            }
          ],
          "page_types": {
            "blogs": 622032,
            "organization": 118086,
            "news": 230980,
            "message-boards": 18590,
            "ecommerce": 96451
          },
          "countries": {
            "US": 86504,
            "GB": 16405,
            "DE": 30522
          },
          "languages": {
            "en": 712751,
            "de": 63841,
            "fr": 53833
          }
        }
      ]
    }
  ]
}

顶层响应字段

字段名	类型	说明
`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	请求中提交的任务参数。
`result`	array	趋势分析结果数组。

`result` 字段

字段名	类型	说明
`type`	string	结果类型，固定为 `content_analysis_trends`。
`date`	string	当前统计数据对应的日期。根据 `date_group` 返回日、周或月粒度。
`total_count`	integer	与请求条件匹的数据库结果总数。
`rank`	integer	目标类别引用 URL 的综合排名。该值为指定日期所有引用 URL 排名的归一化汇总值，范围由 `rank_scale` 决定。
`top_domains`	array	引用目标类别的主要域名及引用数量。数组数量受 `internal_list_limit` 限制。
`sentiment_connotations`	object	感反应及对应引用数量。可能的感标签：`anger`、`fear`、`happiness`、`love`、`sadness`、`share`、`neutral`、`fun`。
`connotation_types`	object	感极性及对应引用数量。可选类型：`positive`、`negative`、`neutral`。
`text_categories`	array	文本类别及每个类别的引用数量。完整类别列表请参考 `/v3/content_analysis/categories/`。
`page_categories`	array	页面类别及每个类别的引用数量。完整类别列表请参考 `/v3/content_analysis/categories/`。
`page_types`	object	页面类型及每种类型的引用数量。
`countries`	object	国家或地区代码及对应引用数量。完整国家和地区列表请参考 `/v3/content_analysis/locations/`。
`languages`	object	语言代码及对应引用数量。完整语言列表请参考 `/v3/content_analysis/languages/`。

`top_domains`素字段

字段名	类型	说明
`domain`	string	引用目标类别的域名。
`count`	integer	该域名产生的引用数量。

`text_categories` 与 `page_categories`素字段

字段名	类型	说明
`category`	string \| null	类别名称。无法识别类别时可能返回 `null`。
`count`	integer	该类别对应的引用数量。

错误处理

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

检查顶层 status_code，确认请求是否成功。
检查每个任务的 status_code，识别单个任务是否执行失败。
读取 status_message 获取错误说明。
结合 tasks_error 判断本次请求中是否存在失败任务。
对限流、网络时和服务端错误实现重试，并控制并发请求数量。

完整错误码请参考 /v3/appendix/errors。

实用场景

监测行业类别的引用趋势：按月或按周跟踪某一类别的引用量变化，识别行业热度和需求拐点。
定位高价值引用来源：分析 top_domains，筛选持续引用目标类别的媒体、博客和社区，为外链拓展与数字提供名单。
评估品牌或主题的舆倾向：结合 sentiment_connotations 和 connotation_types，观察正面、负面及中性引用的变化，声誉管理。
比较不同页面类型的传播效果：通过 page_types 对比新闻、博客、电商页面和论坛的引用数量，优化投放渠道。
分析市场与语言分布：利用 countries 和 languages 识别引用集中地区及主要语言市场，为化 SEO 和本地化规划提供依据。

content_analysis/category_trends/live ​

计费说明 ​

请求限制 ​

请求参数 ​

initial_dataset_filters 支持的运算符 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应结构 ​

顶层响应字段 ​

tasks 字段 ​

result 字段 ​

top_domains素字段 ​

text_categories 与 page_categories素字段 ​

错误处理 ​

实用场景 ​