content_analysis/search/live

POST /v3/content_analysis/search/live

#分析搜索（实时）

POST /v3/content_analysis/search/live
完整请求地址：https://api.seermartech.cn/v3/content_analysis/search/live

本接口根据目标返回详细的引用数据引用页面、域名权重、页面类型、摘要、感倾向、质量和评分等信息。

计费说明

本接口按请求计费。参考价约 ¥0.14 / 次，扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求说明

请求方法：POST
请求体格式：JSON 数组，字符编码为 UTF-8
每次实时调用只能提交 1 个任务，因此请求体数组最多 1 个对象平台限流以认证说明中的 30/60/120 次/分钟规则为准
同时进行的请求数量最多为 30 个
可通过 limit、filters 和 order_by 控制返回数量、筛选条件和排序规则

请求头

http

Authorization: Bearer smt_live_YOUR_KEY
Content-Type: application/json

请求参数

请求体是 JSON 数组：

json

[
  {
    "keyword": "logitech",
    "limit": 10
  }
]

任务参数

参数	类型	填	说明
`keyword`	string	是	目标。使用 UTF-8 编码，服务端会将转换为小写。若要匹完整短语而不是独立，请使用双引号，并在 JSON 中进行转义，例如：`"\"tesla palo alto\""`。
`keyword_fields`	object	否	按出现的字段筛选数据。支持的字段：`title`、`main_title`、`previous_title`、`snippet`。可同时指定多个字段。精确短语匹规则同 `keyword`。
`page_type`	array[string]	否	按页面类型筛选。可选值：`ecommerce`、`news`、`blogs`、`message-boards`、`organization`。
`search_mode`	string	否	结果分组方式。`as_is`：返回目标的引用；`one_per_domain`：每个域名返回一条引用。默认值：`as_is`。
`limit`	integer	否	返回的最大引用数量。默认值：`100`，最大值：`1000`。
`filters`	array	否	结果筛选条件。最多设置 8 个筛选条件。多个条件之间使用逻辑运算符 `and` 或 `or`。
`order_by`	array[string]	否	结果排序规则。排序字段可使用与 `filters` 相同的字段值。排序方向为 `asc` 或 `desc`，格式为 `字段,方向`。单次请求最多设置 3 条排序规则。
`offset`	integer	否	返回结果数组的偏移量。默认值：`0`。例如设置为 `10` 时，跳过前 10 条结果。建议在获取不 10,000 条结果时使用。
`offset_token`	string	否	用于分页获取后续结果的令牌。该值由上一次响应中的同名字段提供。适用于获取 10,000 条结果时请求时。指定此参数后，除 `limit` 外的请求参数将不再生效。每个后续任务的 `offset_token` 都是唯一的。
`rank_scale`	string	否	指定 `domain_rank` 和 `url_rank` 的评分范围。`one_hundred`：0–100；`one_thousand`：0–1000。默认值：`one_thousand`。
`tag`	string	否	自定义任务标识，用于将任务与结果。最大长度为 255 个字符。响应中会在 `data` 对象返回该值。

`keyword_fields` 示例

json

{
  "keyword_fields": {
    "snippet": "\"logitech mouse\"",
    "main_title": "sale"
  }
}

`filters` 示例

筛选条件通常由“字段、运算符、值”组成，多个条件可组合使用：

json

{
  "filters": [
    [
      "main_domain",
      "=",
      "example.com"
    ],
    "and",
    [
      "content_info.content_type",
      "=",
      "page_content"
    ]
  ]
}

支持的运算符：

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

使用 like 或 not_like 时，可使用 % 匹任意长度的字符串空字符串。

`order_by` 示例

json

{
  "order_by": [
    "score,desc",
    "domain_rank,desc"
  ]
}

请求示例

curl

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/content_analysis/search/live" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "keyword": "logitech",
      "keyword_fields": {
        "snippet": "logitech"
      },
      "page_type": [
        "ecommerce",
        "news",
        "blogs",
        "message-boards",
        "organization"
      ],
      "search_mode": "as_is",
      "filters": [
        [
          "main_domain",
          "=",
          "reviewfinder.ca"
        ]
      ],
      "order_by": [
        "content_info.sentiment_connotations.anger,desc"
      ],
      "limit": 10
    }
  ]'

Python

python

import requests

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

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

payload = [
    {
        "keyword": "logitech",
        "keyword_fields": {
            "snippet": "logitech"
        },
        "page_type": [
            "ecommerce",
            "news",
            "blogs",
            "message-boards",
            "organization"
        ],
        "search_mode": "as_is",
        "filters": [
            ["main_domain", "=", "reviewfinder.ca"]
        ],
        "order_by": [
            "content_info.sentiment_connotations.anger,desc"
        ],
        "limit": 10
    }
]

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

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

TypeScript

typescript

import axios from "axios";

const payload = [
  {
    keyword: "logitech",
    keyword_fields: {
      snippet: "logitech",
    },
    page_type: [
      "ecommerce",
      "news",
      "blogs",
      "message-boards",
      "organization",
    ],
    search_mode: "as_is",
    filters: [
      ["main_domain", "=", "reviewfinder.ca"],
    ],
    order_by: [
      "content_info.sentiment_connotations.anger,desc",
    ],
    limit: 10,
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/content_analysis/search/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 对象 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	任务结果数组。

任务字段

字段	类型	说明
`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	请求 URL 路径。
`data`	object	请求任务中使用的参数。
`result`	array	任务结果数组。

`result` 字段

字段	类型	说明
`offset_token`	string	后续分页令牌。可将作为下一次请求的 `offset_token` 获取后续结果。
`total_count`	integer	与请求条件匹的结果总数。
`items_count`	integer	本次 `items` 数组返回的结果数量。
`items`	array	引用及数据。

`items` 字段

字段	类型	说明
`type`	string	数据类型，固定为 `content_analysis_search`。
`url`	string	发现引用的页面 URL。
`domain`	string	页面所属域名。
`main_domain`	string	主域名。
`url_rank`	integer	URL 权重，基于该 URL 的反向链接数据计算。评分范围由 `rank_scale` 决定。
`spam_score`	string	URL 的反向链接垃圾分数。
`domain_rank`	string	域名权重，基于该域名的反向链接数据计算。
`fetch_time`	string	爬虫访问页面的时间，UTC 格式：`yyyy-mm-dd hh-mm-ss +00:00`。
`country`	string	域名注册国家或地区代码。
`language`	string	域名主要语言。
`score`	string	引用显著性评分。综合 `url_rank`、`domain_rank` 以及在标题、主标题、URL 和摘要中的出现计算，数值越高表示引用价值越高。
`page_category`	array	页面所属的产品或服务类别。
`page_types`	array	页面类型。
`ratings`	array	页面中通过结构化数据识别出的评分信息。
`social_metrics`	array	与页面的社交媒体互动指标。
`content_info`	object	当前 URL 中引用的详细信息。
`group_date`	string	引用分组日期。通常表示发布日期，或爬虫首次访问页面的时间。可用于按日期聚合并分析引用趋势。

`content_info` 字段

字段	类型	说明
`content_type`	string	类型，例如 `page_content`、`comment`。
`title`	string	当前结果的标题。
`main_title`	string	页面标题。
`previous_title`	string	上一个区块的标题。
`level`	integer	标题层级，对应 HTML 的 `h1`–`h6`，取值范围为 1–6。
`author`	string	。
`snippet`	string	摘要。
`snippet_length`	integer	摘要字符数。
`social_metrics`	array	当前的社交媒体互动指标。
`highlighted_text`	string	摘要中与的高亮文本。
`language`	string	语言。
`sentiment_connotations`	object	绪倾向及概率值。支持：`anger`、`happiness`、`love`、`sadness`、`share`、`fun`。
`connotation_types`	object	感极性及概率值。支持：`positive`、`negative`、`neutral`。
`text_category`	array	文本所属类别。
`date_published`	string	发布时间，UTC 格式：`yyyy-mm-dd hh-mm-ss +00:00`。
`content_quality_score`	integer	质量分数，根据字数、句子数和字符数计算。
`semantic_location`	string	引用所在的 HTML 语义区域，例如 `article`、`header`。
`rating`	object	当前的评分信息。

`rating` 字段

字段	类型	说明
`name`	string	评分名称，可为 `Max5`、`Percents` 或 `CustomMax`。
`rating_value`	integer	当前评分值。
`max_rating_value`	integer	根据 `name` 指定的最大评分值。
`rating_count`	integer	评分票数。
`relative_rating`	float	相对评分。

响应示例

json

{
  "version": "0.1.20220913",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.5305 sec.",
  "cost": 0.0203,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.5300 sec.",
      "cost": 0.0203,
      "result_count": 1,
      "path": [
        "v3",
        "content_analysis",
        "search",
        "live"
      ],
      "data": {
        "api": "content_analysis",
        "function": "search",
        "keyword": "logitech",
        "keyword_fields": {
          "snippet": "logitech"
        },
        "search_mode": "as_is",
        "limit": 10
      },
      "result": [
        {
          "offset_token": "eyJvZmZzZXQiOjEwfQ==",
          "total_count": 125,
          "items_count": 1,
          "items": [
            {
              "type": "content_analysis_search",
              "url": "https://example.com/review/logitech",
              "domain": "example.com",
              "main_domain": "example.com",
              "url_rank": 64,
              "spam_score": "0",
              "domain_rank": "493",
              "fetch_time": "2022-07-31 20:16:34 +00:00",
              "country": "CA",
              "language": "en",
              "score": "5751.833",
              "page_category": [],
              "page_types": [
                "blogs"
              ],
              "ratings": null,
              "social_metrics": null,
              "content_info": {
                "content_type": "page_content",
                "title": "产品评测",
                "main_title": "产品对比与评测",
                "previous_title": "专家评价",
                "level": 2,
                "author": null,
                "snippet": "这是目标的页面摘要。",
                "snippet_length": 30,
                "social_metrics": null,
                "highlighted_text": null,
                "language": "en",
                "sentiment_connotations": {
                  "anger": null,
                  "happiness": 0.15,
                  "love": 0.18,
                  "sadness": 0.09,
                  "share": null,
                  "fun": 0.06
                },
                "connotation_types": {
                  "positive": 0.34,
                  "negative": 0.33,
                  "neutral": 0.33
                },
                "text_category": [],
                "date_published": null,
                "content_quality_score": 94,
                "semantic_location": "article",
                "rating": null
              },
              "group_date": "2021-09-13 05:05:18 +00:00"
            }
          ]
        }
      ]
    }
  ]
}

状态码与错误处理

请根据顶层 status_code 和任务级 status_code 判断请求是否成功。20000 表示成功，状态码表示请求或任务处理异常。建议客户端同时检查：

HTTP 状态码
顶层 status_code
每个任务的 status_code
status_message
tasks_error

错误码可参考：/v3/appendix/errors

实用场景

定位引用页面：查找目标在新闻、博客、电商和组织网站中的引用位置，评估品牌或产品的覆盖范围。
筛选竞争对手：按域名、页面类型、标题或摘要筛选引用结果，快速整理竞争对手的布局和排名页面。
分析品牌舆倾向：读取 sentiment_connotations 和 connotation_types，识别的正面、负面和中性绪分布。
评估质量与引用价值：结合 score、url_rank、domain_rank 和 content_quality_score，筛选更 SEO 价值的外部引用页面。
追踪引用趋势：使用 group_date 对引用结果按日期聚合，监测品牌、产品或主题在不同时间段的变化。

content_analysis/search/live ​

计费说明 ​

请求说明 ​

请求头 ​

请求参数 ​

任务参数 ​

keyword_fields 示例 ​

filters 示例 ​

order_by 示例 ​

请求示例 ​

curl ​

Python ​

TypeScript ​

响应结构 ​

顶层字段 ​

任务字段 ​

result 字段 ​

items 字段 ​

content_info 字段 ​

rating 字段 ​

响应示例 ​

状态码与错误处理 ​

实用场景 ​

content_analysis/search/live

计费说明

请求说明

请求头

请求参数

任务参数

`keyword_fields` 示例

`filters` 示例

`order_by` 示例

请求示例

curl

Python

TypeScript

响应结构

顶层字段

任务字段

`result` 字段

`items` 字段

`content_info` 字段

`rating` 字段

响应示例

状态码与错误处理

实用场景