趋势合并数据实时接口

POST /v3/keywords_data/dataforseo_trends/merged_data/live

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

/v3/keywords_data/dataforseo_trends/merged_data/live

用于实时获取趋势合并数据。除指定时间范围的热度外，还可获取按国家或地区划分的热度数据，以及按年龄和性别划分的人群热度数据，并支持多个之间的对比。

支持以下数据类型：

web：网页搜索趋势
news：新闻趋势
ecommerce：电商趋势

每个请求最多提交 5 个。无论一次请求 1 个还是多个，均按请求次数计费。

历史数据可用范围：

web 类型：自 2004-01-01 起
news 和 ecommerce 类型：自 2008-01-01 起

计费与请求限制

参考价约 ¥0.0360 / 次。每次请求一个实时任务，扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求要求：

请求体使用 UTF-8 编码的 JSON。
请求体格式为 JSON 数组，例如 [{ ... }]。
每个实时 API 请求只能一个任务。平台限流以认证说明中的 30/60/120 次/分钟规则为准。
同时处理的请求数最多为 30 个。

请求地址

text

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

请求头

http

Authorization: Bearer smt_live_YOUR_KEY
Content-Type: application/json

请求参数

参数	类型	填	说明
`keywords`	array[string]	是	要分析的列表，最多 5 个。建议使用符号、特殊字符、表符号等。非拉丁字符将返回使用国家或地区对应的数据。
`location_name`	string	否	搜索引擎位置的完整名称，例如 `United Kingdom`。不传时返回数据。与 `location_code` 二选一。
`location_code`	integer	否	搜索引擎位置代码，例如 `2840`。不传时返回数据。与 `location_name` 二选一。
`type`	string	否	趋势数据类型。可选值：`web`、`news`、`ecommerce`。默认值为 `web`。
`date_from`	string	否	时间范围起始日期，格式为 `yyyy-mm-dd`。未指定时，默认使用前一年当前日期对应的日期。`web` 类型最早支持 `2004-01-01`，类型最早支持 `2008-01-01`。
`date_to`	string	否	时间范围结束日期，格式为 `yyyy-mm-dd`。未指定时，默认使用当天日期。
`time_range`	string	否	预设时间范围。如果同时传 `date_from` 或 `date_to`，则忽略此参数。
`tag`	string	否	自定义任务标识，最多 255 个字符。可用于请求与响应，指定的值会原样返回在响应的 `data` 对象中。

`time_range` 可选值

text

past_4_hours
past_day
past_7_days
past_30_days
past_90_days
past_12_months
past_5_years

位置参数说明

可通过以下接口获取可用位置及 location_name、location_code、geo_id 和 geo_name：

text

GET https://api.seermartech.cn/v3/keywords_data/dataforseo_trends/locations

如果指定 location_name 或 location_code，返回数据将对应所属国家或地区。例如：

location_name: "United Kingdom"：返回英国范围的数据
location_code: 2840：返回对应位置所属国家或地区的数据

请求示例

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 '[
    {
      "keywords": ["rugby", "cricket"],
      "date_from": "2023-01-01",
      "date_to": "2024-01-01",
      "type": "web",
      "location_name": "United States",
      "tag": "sports-trend-example"
    }
  ]'

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)
result = response.json()

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        "请求失败，状态码：%s，消息：%s"
        % (result.get("status_code"), result.get("status_message"))
    )

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.response?.data || error.message);
  });

响应结构

接口返回 JSON 对象 tasks 数组任务处理结果。

json

{
  "version": "0.1.20231117",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.6291 sec.",
  "cost": 0.036,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "任务 UUID",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.6291 sec.",
      "cost": 0.036,
      "result_count": 1,
      "path": [
        "v3",
        "keywords_data",
        "dataforseo_trends",
        "merged_data",
        "live"
      ],
      "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": []
        }
      ]
    }
  ]
}

> cost 为任务成本参考字段；扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

顶层响应字段

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	响应状态码。成功通常为 `20000`。完整错误码请参考 `/v3/appendix/errors`。
`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	请求 API 的路径分段。
`data`	object	本次请求中提交的参数。
`result`	array	任务返回的数据数组。

结果字段

字段	类型	说明
`type`	string	结果类型，通常为 `trends`。
`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`素类型

items 通常以下三类数据：

dataforseo_trends_graph
subregion_interests
demography

`dataforseo_trends_graph`

用于返回指定时间范围的热度变化。

字段	类型	说明
`position`	integer	素在 `items` 数组中的位置，例如 `1`、`2`、`3`。
`type`	string	固定为 `dataforseo_trends_graph`。
`keywords`	array	当前数据的。
`data`	array	指定参数对应的趋势数据。
`averages`	array	整个时间范围的平均热度。

data 数组：

字段	类型	说明
`date_from`	string	当前数据点对应时间段的起始日期，格式为 `yyyy-mm-dd`。
`date_to`	string	当前数据点对应时间段的结束日期，格式为 `yyyy-mm-dd`。
`timestamp`	integer	Unix 时间戳。
`values`	array	当前时间点的相对热度。

热度值说明：

100 表示该在比较范围达到最高热度。
50 表示热度约为最高值的一半。
0 表示该没有足够的数据。
当请求多个时，values 会所有中的最高值进行归一化。

`subregion_interests`

用于返回在国家、州、省或地区范围的热度分布和间对比。

字段	类型	说明
`position`	integer	素在 `items` 数组中的位置。
`type`	string	固定为 `subregion_interests`。
`keywords`	array	当前地区数据的。
`interests`	array	每个的地区热度数据。
`interests_comparison`	object	多个之间的地区热度对比。指定一个时为 `null`。

`interests`

字段	类型	说明
`keyword`	string	当前。
`values`	array	该在各国家或地区的热度值。
`values[].geo_id`	string	地区标识，例如 `US-NY`。
`values[].geo_name`	string	地区名称，例如 `Andorra`。
`values[].value`	integer	该地区在指定时间范围的相对热度。

value 的计算方式：

在所有地区中确定该的最高热度，并将设为 100。
地区的值按最高热度的百分比计算。
100 表示最高热度，50 表示约为最高热度的一半，0 表示数据不足。

`interests_comparison.items`

用于比较每个地区不同的热度。

字段	类型	说明
`geo_id`	string	地区标识。
`geo_name`	string	地区名称。
`values`	array	当前地区各的相对热度值。

values 数组与请求中的 keywords 一一对应：第一个值对应第一个，第二个值对应第二个，以此类推。

计算方式：

在每个地区确定所有中的最高值，并设为 100。
的值表示相对于该地区最高热度的百分比。
0 表示数据不足。

`interests_comparison.absolute_items`

用于比较各在所有地区范围的整体热度。

字段	类型	说明
`geo_id`	string	地区标识。
`geo_name`	string	地区名称。
`values`	array	各相对于所有地区、所有最高值的热度。

计算方式：

在所有和所有地区中确定最高热度，并设为 100。
值表示对应在对应地区的热度相对于局最高值的百分比。
数组顺序与请求中的 keywords 顺序一致。

`demography`

用于返回每个按年龄和性别划分的热度数据。

字段	类型	说明
`position`	integer	素在 `items` 数组中的位置。
`type`	string	固定为 `demography`。
`keywords`	array	当前人口统计数据的。
`demography`	object	每个按年龄和性别划分的热度。
`demography_comparison`	object	多个之间的人口统计热度对比。指定一个时为 `null`。

`demography.age`

字段	类型	说明
`keyword`	string	当前。
`values`	array	各年龄段及对应的热度值。
`values[].type`	string	年龄段，可选：`18-24`、`25-34`、`35-44`、`45-54`、`55-64`。
`values[].value`	integer	该年龄段的相对热度。

年龄热度值的计算方式：

在该的所有年龄段中确定最高热度，并设为 100。
年龄段的值按最高热度的百分比计算。
0 表示数据不足。

`demography.gender`

字段	类型	说明
`keyword`	string	当前。
`values`	array	各性别类别及对应的热度值。
`values[].type`	string	性别类别，可选：`female`、`male`。
`values[].value`	integer	该性别类别的相对热度。

性别热度值的计算方式：

在该的所有性别类别中确定最高热度，并设为 100。
类别的值按最高热度的百分比计算。
0 表示数据不足。

`demography_comparison.age`

对象键表示年龄段：

text

每个年龄段对应一个数组，数组值与请求中的 keywords 顺序一致，用于比较各在该年龄段的热度。

计算方式：

在每个年龄段汇总所有的热度。
将各热度换算为该年龄段总热度的百分比。
100 表示该年龄段相对最高的，0 表示数据不足。

`demography_comparison.gender`

以下两个字段：

female
male

每个字段对应一个数组，数组值与请求中的 keywords 顺序一致，用于比较各在指定性别类别中的热度。

计算方式：

在每个性别类别汇总所有的热度。
将各热度换算为该类别总热度的百分比。
100 表示该性别类别相对最高的，0 表示数据不足。

热度值解读

本接口中的热度值为相对值，不代表绝对搜索量或访问量。通常应结合以下规则进行解读：

100：当前比较范围的最高热度。
50：约为最高热度的一半。
0：没有足够数据，不能直接理解为没有搜索。
不同比较维度的 100 基准可能不同，比较时应确认所属的数据集：
- 时间趋势：以时间范围的最高值为基准。
- 地区：以该在所有地区中的最高值为基准。
- 地区对比：以某一地区所有的最高值为基准。 -地区对比：以所有地区、所有中的最高值为基准。
- 年龄或性别：以当前在对应人口类别中的最高值为基准。

错误处理

请根据以下字段判断请求是否成功：

json

{
  "status_code": 20000,
  "status_message": "Ok."
}

同时建议检查：

顶层 status_code
每个任务的 status_code
tasks_error
result 是否存在
location_code 或 language_code 是否为 null
数据数组是否为空

完整响应码请参考：

text

/v3/appendix/errors

实用场景

追踪季节性趋势：分析产品词或行业词在过去数月或数年中的热度变化，安排发布、促销活动和 SEO 资源。
比较不同的增长潜力：在同一时间范围和地区比较多个，确定优创建的落地页、专题页或主题。
识别地区市场机会：查看在州、省或城市等子区域的热度分布，为本地 SEO、区域投放和市场拓展选择重点地区。
制定人群定向策略：根据年龄和性别维度的热度差异，调整表达、产品卖点和广告创意。
监测新闻、电商与网页搜索需求：分别调用 news、ecommerce 和 web 类型，区分媒体度、购物意图与常规搜索需求，选题和转化漏斗分析。

趋势合并数据实时接口 ​

计费与请求限制 ​

请求地址 ​

请求头 ​

请求参数 ​

time_range 可选值 ​

位置参数说明 ​

请求示例 ​

curl ​

Python ​

TypeScript ​

响应结构 ​

顶层响应字段 ​

任务字段 ​

结果字段 ​

items素类型 ​

dataforseo_trends_graph ​

subregion_interests ​

interests ​

interests_comparison.items ​

interests_comparison.absolute_items ​

demography ​

demography.age ​

demography.gender ​

demography_comparison.age ​

demography_comparison.gender ​

热度值解读 ​

错误处理 ​

实用场景 ​

趋势合并数据实时接口

计费与请求限制

请求地址

请求头

请求参数

`time_range` 可选值

位置参数说明

请求示例

curl

Python

TypeScript

响应结构

顶层响应字段

任务字段

结果字段

`items`素类型

`dataforseo_trends_graph`

`subregion_interests`

`interests`

`interests_comparison.items`

`interests_comparison.absolute_items`

`demography`

`demography.age`

`demography.gender`

`demography_comparison.age`

`demography_comparison.gender`

热度值解读

错误处理

实用场景