SeerMarTech API 文档

主题

趋势合并数据（实时） ​

接口说明 ​

该接口用于实时获取趋势合并数据。除了指定时间范围的热度趋势外，还会返回：

  • 指定地区的热度分布
  • 各的人群画像拆分数据
  • 多之间的对比值

支持查询以下数据类型：

  • web：Google Search
  • news：Google News
  • ecommerce：Google Shopping

接口会对 keywords 数组中的每个分别返回结果数据。

算法说明 ​

本接口基于与网页、新闻、购物商品列表之间的，以及这些本身的热度进行建模，同时结合匿名化的用户网络行为数据，输出热度趋势结果。

历史数据范围 ​

  • web 类型：最早可查询到 2004-01-01
  • 类型：最早可查询到 2008-01-01

请求方式 ​

POST https://api.seermartech.cn/v3/keywords_data/dataforseo_trends/merged_data/live

计费与频率限制 ​

  • 按请求计费，与 keywords 数组中数量无
  • 单次请求最多可提交 5 个
  • 每分钟最多可发送 2000 次 API 调用
  • 最多支持 30 个并发请求
  • 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准
  • 参考价约 ¥0.0800 / 次

请求体格式 ​

所有 POST 数据使用 JSON（UTF-8 编码），并以 JSON 数组形式提交：

json
[
 {
 "keywords": ["rugby", "cricket"],
 "date_from": "2023-01-01",
 "date_to": "2024-01-01",
 "type": "web",
 "location_name": "United States"
 }
]

请求参数 ​

字段名类型说明
keywordsarray填。数组，最多可传 5 个。建议使用符号和特殊字符（如 UTF 特殊符号、emoji）。如使用非拉丁字符，通常会返回这些字符使用国家/地区的数据。
location_namestring可选。搜索地区完整名称。不传则返回结果。传该字段时无需再传 location_code。地区列表可通过 /v3/keywords_data/dataforseo_trends/locations 获取。注意：返回的数据对应的是该地区所属国家。示例：United Kingdom
location_codeinteger可选。搜索地区编码。不传则返回结果。传该字段时无需再传 location_name。地区列表可通过 /v3/keywords_data/dataforseo_trends/locations 获取。注意：返回的数据对应的是该编码所属国家。示例：2840
typestring可选。趋势数据类型。默认值：web。可选值：web、news、ecommerce
date_fromstring可选。时间范围起始日期，格式：yyyy-mm-dd。未传时，默认使用“去年今天对应的月日”。web 最小值：2004-01-01；类型最小值：2008-01-01。示例：2019-01-15
date_tostring可选。时间范围结束日期，格式：yyyy-mm-dd。未传时，默认使用当天日期。示例：2019-01-15
time_rangestring可选。预设时间范围。如果传了 date_from 或 date_to，该字段会被忽略。可选值：past_4_hours、past_day、past_7_days、past_30_days、past_90_days、past_12_months、past_5_years
tagstring可选。自定义任务标识，最大长度 255。可用于结果对账和业务追踪，返回时会出现在响应的 data 对象中。

响应结构 ​

接口返回 JSON 编码数据，顶层 tasks 数组。

顶层字段 ​

字段名类型说明
versionstring当前 API 版本
status_codeinteger通用状态码。完整错误码见 /v3/appendix/errors
status_messagestring通用状态信息
timestring执行耗时，单位秒
costfloat本次请求总费用，单位 USD
tasks_countintegertasks 数组中的任务数量
tasks_errorinteger返回错误的任务数量
tasksarray任务结果数组

tasks[] 字段 ​

字段名类型说明
idstring任务唯一标识，UUID 格式
status_codeinteger任务状态码，范围通常为 10000-60000
status_messagestring任务状态信息
timestring任务执行耗时，单位秒
costfloat任务费用，单位 USD
result_countintegerresult 数组数量
patharrayURL 路径
dataobject回显请求参数
resultarray结果数组

result[] 字段 ​

字段名类型说明
keywordsarray请求中的数组
typearray请求中的趋势类型
location_codeinteger请求中的地区编码；无数据时为 null
language_codestring请求中的语言编码；无数据时为 null
datetimestring获取结果的时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00
items_countintegeritems 数组中的数量
itemsarray趋势合并数据结果

items素说明 ​

items 中通常以下 3 类：

  • dataforseo_trends_graph
  • subregion_interests
  • demography

返回指定时间范围的热度趋势曲线。

字段名类型说明
positioninteger素顺序位置，如 1、2、3
typestring固定值：dataforseo_trends_graph
keywordsarray该图表所基于的数组
dataarray各时间点的趋势数据
averagesarray整个时间范围的平均热度值
字段名类型说明
date_fromstring当前时间片起始日期，UTC 格式：yyyy-mm-dd
date_tostring当前时间片结束日期，UTC 格式：yyyy-mm-dd
timestampintegerUnix 时间戳
valuesarray该时间点的相对热度值。若指定了多个，则会按所有中的最高值进行归一化后求平均。100 表示峰值热度，50 表示热度约为峰值的一半，0 表示数据不足。

subregion_interests素 ​

返回各在国家/地区下不同子区域的热度分布，以及多之间的地域对比。

字段名类型说明
positioninteger素顺序位置
typestring固定值：subregion_interests
keywordsarray该地域分析所基于的数组
interestsarray各在子区域维度下的热度结果
interests_comparisonobject多地域热度对比；若只传一个，则为 null

interests[] ​

字段名类型说明
keywordstring当前
valuesarray该在不同国家或区域的相对热度值

interests[].values[] ​

字段名类型说明
geo_idstring地理位置标识，可用于与地区参数匹。示例：US-NY
geo_namestring地理位置名称。示例：Andorra
valueinteger指定区域的相对热度值。算法会找出该在所有区域中的最高热度，并将记为 100，区域按比例换算。50 表示约为最高区域的一半，0 表示数据不足。

interests_comparison ​

用于比较多个在不同区域中的相对受欢迎程度。

interests_comparison.items[] ​

字段名类型说明
geo_idstring地理位置标识
geo_namestring地理位置名称
valuesarray当前区域多个的相对热度值。数组顺序与请求中的 keywords 顺序一致。每个区域会以该区域中热度最高的为 100 进行归一化。

interests_comparison.absolute_items[] ​

字段名类型说明
geo_idstring地理位置标识
geo_namestring地理位置名称
valuesarray跨区域计算后的相对热度值。数组顺序与 keywords 一致。算法会在“所有 × 所有区域”范围找到最高值并记为 100，值按比例换算。

demography素 ​

返回每个在年龄和性别维度上的热度分布，以及多在人群维度下的对比结果。

字段名类型说明
positioninteger素顺序位置
typestring固定值：demography
keywordsarray该人群分析所基于的数组
demographyobject每个的人群画像数据
demography_comparisonobject多人群对比；若只传一个，则为 null

demography.age[] ​

字段名类型说明
keywordstring当前
valuesarray年龄段及对应热度值

demography.age[].values[] ​

字段名类型说明
typestring年龄段，可选值：18-24、25-34、35-44、45-54、55-64
valueinteger当前年龄段的相对热度值。该在所有年龄段中的最高值记为 100，余按比例换算；0 表示数据不足。

demography.gender[] ​

字段名类型说明
keywordstring当前
valuesarray性别维度及对应热度值

demography.gender[].values[] ​

字段名类型说明
typestring性别类别，可选值：female、male
valueinteger当前性别类别的相对热度值。该在所有性别中的最高值记为 100，余按比例换算；0 表示数据不足。

demography_comparison ​

用于比较多个在不同年龄和性别人群中的热度差异。

demography_comparison.age ​

键名为年龄段，例如：

  • 18-24
  • 25-34
  • 35-44
  • 45-54
  • 55-64

每个年龄段对应一个数组，数组顺序与请求中的 keywords 顺序一致。表示该年龄段下多个的相对热度对比。

demography_comparison.gender ​

以下字段：

  • female
  • male

每个字段值为数组，数组顺序与请求中的 keywords 顺序一致。表示该性别人群下多个的相对热度对比。

计算方式为：统计某年龄段或某性别下所有的总热度，再将各换算为相对比例；100 表示最高值，0 表示数据不足。

请求示例 ​

cURL ​

bash
curl --location --request POST "https://api.seermartech.cn/v3/keywords_data/dataforseo_trends/merged_data/live" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "location_name": "United States",
 "date_from": "2023-01-01",
 "date_to": "2024-01-01",
 "type": "web",
 "keywords": ["rugby", "cricket"]
 }
]'

Python ​

python
import requests

url = "https://api.seermartech.cn/v3/keywords_data/dataforseo_trends/merged_data/live"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
payload = [
 {
 "location_name": "United States",
 "date_from": "2023-01-01",
 "date_to": "2024-01-01",
 "type": "web",
 "keywords": ["rugby", "cricket"]
 }
]

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

TypeScript ​

typescript
import axios from "axios";

const payload = [
 {
 location_name: "United States",
 date_from: "2023-01-01",
 date_to: "2024-01-01",
 type: "web",
 keywords: ["rugby", "cricket"]
 }
];

axios.post(
 "https://api.seermartech.cn/v3/keywords_data/dataforseo_trends/merged_data/live",
 payload,
 {
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 }
 }
).then((response) => {
 // 输出返回结果
 console.log(response.data);
}).catch((error) => {
 console.error(error);
});

响应示例 ​

以下为精简后的响应结构示例：

json
{
 "version": "0.1.20231117",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.6291 sec.",
 "cost": 0.005,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "keywords_data",
 "function": "merged_data",
 "se": "dataforseo_trends",
 "keywords": ["rugby", "cricket"],
 "date_from": "2023-01-01",
 "date_to": "2024-01-01",
 "type": "web",
 "location_name": "United States"
 },
 "result": [
 {
 "type": "trends",
 "location_code": 2840,
 "language_code": null,
 "datetime": "2024-03-12 12:01:58 +00:00",
 "items_count": 3,
 "items": [
 {
 "position": 1,
 "type": "dataforseo_trends_graph",
 "keywords": ["rugby", "cricket"],
 "data": [
 {
 "date_from": "2023-01-01",
 "date_to": "2023-01-07",
 "timestamp": 1672531200,
 "values": [67, 100]
 }
 ],
 "averages": [54, 89]
 },
 {
 "position": 2,
 "type": "subregion_interests",
 "keywords": ["rugby", "cricket"],
 "interests": [
 {
 "keyword": "rugby",
 "values": [
 {
 "geo_id": null,
 "geo_name": "California",
 "value": 84
 }
 ]
 },
 {
 "keyword": "cricket",
 "values": [
 {
 "geo_id": null,
 "geo_name": "California",
 "value": 100
 }
 ]
 }
 ],
 "interests_comparison": {
 "items": [
 {
 "geo_id": null,
 "geo_name": "California",
 "values": [84, 100]
 }
 ],
 "absolute_items": [
 {
 "geo_id": null,
 "geo_name": "California",
 "values": [52, 100]
 }
 ]
 }
 },
 {
 "position": 3,
 "type": "demography",
 "keywords": ["rugby", "cricket"],
 "demography": {
 "age": [
 {
 "keyword": "rugby",
 "values": [
 { "type": "18-24", "value": 61 },
 { "type": "25-34", "value": 100 }
 ]
 },
 {
 "keyword": "cricket",
 "values": [
 { "type": "18-24", "value": 75 },
 { "type": "25-34", "value": 100 }
 ]
 }
 ],
 "gender": [
 {
 "keyword": "rugby",
 "values": [
 { "type": "female", "value": 43 },
 { "type": "male", "value": 100 }
 ]
 },
 {
 "keyword": "cricket",
 "values": [
 { "type": "female", "value": 58 },
 { "type": "male", "value": 100 }
 ]
 }
 ]
 },
 "demography_comparison": {
 "age": {
 "18-24": [45, 55],
 "25-34": [50, 50]
 },
 "gender": {
 "female": [43, 57],
 "male": [49, 51]
 }
 }
 }
 ]
 }
 ]
 }
 ]
}

错误处理 ​

建议对以下层级同时做状态校验：

  1. 顶层 status_code
  2. tasks[].status_code
  3. 业务结果是否存在于 result 和 items 中

常见判断方式：

  • 20000：请求成功
  • 状态码：根据 /v3/appendix/errors 进行处理

建议在系统中做好以下异常场景处理：

  • 参数缺失或格式错误
  • 日期范围出可用历史区间
  • keywords 数量 5
  • 并发或请求频率限
  • 某些地区、人群维度下返回 0 或 null，表示数据不足

使用建议 ​

  • 对多对比场景，优保持语义接近，便于解读相对热度
  • 若需要稳定的趋势时间序列，建议显式传 date_from 与 date_to
  • 若需要国家级或区域级洞察，建议结合 /v3/keywords_data/dataforseo_trends/locations 确认可用地区参数
  • 若只短期变化，可使用 time_range；若需要精确控制分析窗口，请使用 date_from / date_to

实用场景 ​

  • 对比品牌词热度：比较多个品牌词在一段时间的趋势变化，识别市场度，为品牌投放和策略提供依据。
  • 定位区域需求差异：分析在不同州、省或地区的热度分布，帮助制定本地化 SEO、区域广告和落地页策略。
  • 识别人群偏好：基于年龄和性别拆分查看热度，选题、受众细分和产品定位优化。
  • 监测季节性波动：按周或按月跟踪热度变化，发现旺季、淡季和热点窗口，优化发布时间与预算安排。
  • 评估竞争：通过 interests_comparison 和 demography_comparison 比较多个在地域与人群维度下的相对表现，支持选词和专题布局决策。

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

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