趋势探索（实时）

接口说明

该接口用于获取热度趋势数据，可查看以下场景下的流行度变化：

• Google Search
• Google News
• Google Shopping

接口会对 keywords 数组中的每个返回趋势信息。单次请求中，keywords 最多可提交 5 个。

说明：

• 该接口按请求次数计费，与 keywords 数组中多少个无。
• web 类型的历史数据最早可追溯到 2004-01-01
• 类型的历史数据最早可追溯到 2008-01-01

请求方式

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

计费与调用限制

• 按每次请求计费
• 参考价约 ¥0.0160 / 次
• 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准
• 每分钟最多 2000 次 API 调用
• 同时并发请求上限为 30

趋势数据说明

本接口基于与网页、新闻、商品列表的，以及这些本身的流行度来估算热度；同时会结合匿名化的用户网络行为数据进行综合计算。

返回值中的热度是相对值，不是绝对搜索量：

• 100 表示该在给定时间范围达到峰值热度
• 50 表示热度约为峰值的一半
• 0 表示数据不足

如果一次请求中提交了多个，返回的 values 会基于这些的最高值进行归一化处理，表现为综合趋势结果。

---

请求参数

POST 请求体为 JSON 数组格式：

[
 {
 "keywords": ["iphone 14", "samsung s23"],
 "location_code": 2840
 }
]

任务字段说明

字段名	类型	填	说明
keywords	array	是	数组，最多可传 5 个
location_name	string	否	搜索引擎地区完整名称。不传则返回数据；如果传了该字段，则无需再传 location_code。例如：United Kingdom
location_code	integer	否	搜索引擎地区代码。不传则返回数据；如果传了该字段，则无需再传 location_name。例如：2840
type	string	否	趋势类型。默认 web。可选值：web、news、ecommerce
date_from	string	否	时间范围起始日期，格式：yyyy-mm-dd。web 类型最小值为 2004-01-01，类型最小值为 2008-01-01。例如：2019-01-15
date_to	string	否	时间范围结束日期，格式：yyyy-mm-dd。默认今天。例如：2019-01-15
time_range	string	否	预设时间范围。如果指定了 date_from 或 date_to，该字段会被忽略。可选值：past_4_hours、past_day、past_7_days、past_30_days、past_90_days、past_12_months、past_5_years
tag	string	否	自定义任务标识，最长 255 个字符。可用于将请求与响应结果进行，返回时会出现在响应的 data 对象中

地区列表获取

如需获取可用地区及 location_name / location_code，可调用：

/v3/keywords_data/dataforseo_trends/locations

注意：指定 location_name 或 location_code 后，返回的数据将对应所属国家/地区。

---

响应结构

服务端会返回 JSON 数据，顶层 tasks 数组。

顶层字段

字段名	类型	说明
version	string	当前 API 版本
status_code	integer	通用状态码，错误码列表见 /v3/appendix/errors
status_message	string	通用提示信息
time	string	执行耗时，单位秒
cost	float	本次请求总费用，单位 USD
tasks_count	integer	tasks 数组中的任务数量
tasks_error	integer	返回错误的任务数量
tasks	array	任务结果数组

tasks[] 字段

字段名	类型	说明
id	string	任务唯一标识，UUID 格式
status_code	integer	任务状态码，范围通常为 10000-60000
status_message	string	任务提示信息
time	string	任务执行耗时
cost	float	任务费用，单位 USD
result_count	integer	result 数组数量
path	array	URL 路径
data	object	与提交时相同的请求参数
result	array	结果数组

result[] 字段

字段名	类型	说明
keywords	array	请求中提交的数组
type	array / string	请求中的趋势类型
location_code	integer	请求中的地区代码；无数据时为 null
language_code	string	请求中的语言代码；无数据时为 null
datetime	string	结果返回时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00
items_count	integer	items 数组中的结果数量
items	array	热度及数据

items[] 字段

该接口主要返回 dataforseo_trends_graph 类型。

字段名	类型	说明
position	integer	素位置，例如 1、2、3
type	string	素类型，固定为 dataforseo_trends_graph
keywords	array	数组；该图表数据基于这些生成
data	array	指定参数下的趋势时间序列数据
averages	array	整个时间范围的平均热度值

items[].data[] 字段

字段名	类型	说明
date_from	string	当前时间片段起始日期，UTC 格式：yyyy-mm-dd
date_to	string	当前时间片段结束日期，UTC 格式：yyyy-mm-dd
timestamp	integer	Unix 时间戳
values	array	指定时间点的相对热度值

---

请求示例

cURL

curl --location --request POST "https://api.seermartech.cn/v3/keywords_data/dataforseo_trends/explore/live" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "location_code": 2840,
 "keywords": [
 "iphone 14",
 "samsung s23"
 ]
 }
]'

Python

import requests

url = "https://api.seermartech.cn/v3/keywords_data/dataforseo_trends/explore/live"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
data = [
 {
 "location_code": 2840,
 "keywords": [
 "iphone 14",
 "samsung s23"
 ]
 }
]

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

TypeScript

import axios from "axios";

const postData = [
 {
 location_code: 2840,
 keywords: ["iphone 14", "samsung s23"]
 }
];

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

---

响应示例

{
 "version": "0.1.20231117",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "7.9401 sec.",
 "cost": 0.001,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "keywords_data",
 "function": "explore",
 "se": "dataforseo_trends",
 "keywords": [
 "iphone 14",
 "samsung s23"
 ],
 "location_code": 2840
 },
 "result": [
 {
 "type": "trends",
 "location_code": 2840,
 "language_code": null,
 "datetime": "2024-01-10 11:18:54 +00:00",
 "items_count": 1,
 "items": [
 {
 "position": 1,
 "type": "dataforseo_trends_graph",
 "keywords": [
 "iphone 14",
 "samsung s23"
 ],
 "data": [
 {
 "date_from": "2023-01-22",
 "date_to": "2023-01-28",
 "timestamp": 1674345600,
 "values": [72]
 },
 {
 "date_from": "2023-01-29",
 "date_to": "2023-02-04",
 "timestamp": 1674950400,
 "values": [69]
 },
 {
 "date_from": "2023-02-05",
 "date_to": "2023-02-11",
 "timestamp": 1675555200,
 "values": [64]
 },
 {
 "date_from": "2023-12-31",
 "date_to": "2024-01-10",
 "timestamp": 1703980800,
 "values": [81]
 }
 ],
 "averages": [71]
 }
 ]
 }
 ]
 }
 ]
}

---

错误处理

请基于 status_code 和 status_message 设计异常处理逻辑，以下层级：

• 顶层请求状态
• tasks[]单任务状态
• 业务结果是否为空

错误码与提示信息可参考：

• /v3/appendix/errors

常见处理建议：

• 当顶层 status_code 非成功值时，直接视为请求失败
• 当 tasks_error > 0 时，逐个检查 tasks[] 中的错误任务
• 当 items_count = 0 时，表示当前条件下无可用趋势数据
• 当返回 location_code: null 时，通常表示请求使用的是范围数据

使用建议

• 对于多对比，建议将强词放在同一请求中，便于观察综合热度变化
• 如果需要严格控制时间范围，优使用 date_from 和 date_to
• 如果只需快速获取近期趋势，可使用 time_range
• date_from / date_to 与 time_range 同时传时，以前为准
• 单次最多 5 个，出请拆分请求

实用场景

• 对比品牌词热度变化，评估不同品牌或产品在指定国家的度走势，为市场投放和选题提供依据
• 监控季节性波动，识别节假日、促销节点或行业旺季，优化 SEO发布时间
• 分析新闻趋势词热度，通过 news 类型观察事件型传播周期，营销和舆跟踪
• 挖掘电商搜索，使用 ecommerce 类型评估商品词趋势变化，支持选品、活动策划和商品页优化
• 验证策略效果，在发布前后对比目标趋势变化，判断话题选择是否贴合用户点