趋势子区域（实时）

接口概述

该接口用于获取指定在不同国家/地区下的子区域热度分布，数据来源于平台趋势数据能力。可用于分析 Google Search、Google News、Google Shopping 场景下的受欢迎程度。

通过本接口，你可以：

• 查看某个在各子区域中的相对热度；
• 比较多个在同一地区哪个更热门；
• 比较多个在所有地区范围的整体热度分布。

注意：如果 keywords 中只传 1 个，响应中的 interests_comparison 将为 null。

趋势算法说明

本接口基于与网页、新闻、商品列表之间的，以及本身的热度进行建模，并结合匿名化用户行为数据生成趋势结果。

使用限制

• 单次请求的 keywords 数组最多支持 5 个
• 按请求次数计费，与数组中数量无
• 历史数据范围：
• web 类型：最早可到 2004-01-01
• 类型：最早可到 2008-01-01
• API 频率限制：
• 每分钟最多 2000 次调用
• 最多 30 个并发请求

请求地址

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

计费说明

该接口按请求计费。

• 参考价约 ¥0.0320 / 次
• 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准

请求体格式

所有 POST 数据均需使用 JSON（UTF-8 编码），请求体为 JSON 数组：

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

请求参数

字段名	类型	说明
keywords	array	填。数组，最多 5 个。建议使用符号和特殊字符（如 UTF 特殊符号、emoji）。如使用非拉丁字符，通常会返回这些字符使用国家/地区的数据。
location_name	string	可选。搜索引擎地域名。不传则返回结果。传了该字段时无需再传 location_code。可通过 /v3/keywords_data/dataforseo_trends/locations 获取可用地域列表。返回数据将对应此地域所属国家的数据。 例如：United Kingdom
location_code	integer	可选。搜索引擎地域编码。不传则返回结果。传了该字段时无需再传 location_name。可通过 /v3/keywords_data/dataforseo_trends/locations 获取可用地域编码。返回数据将对应此编码所属国家的数据。 例如：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 对象会回传该值。

返回结果说明

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

顶层字段

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

tasks[] 字段

字段名	类型	说明
id	string	任务唯一标识，UUID 格式
status_code	integer	任务状态码，范围通常为 10000-60000，完整列表参考 /v3/appendix/errors
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[] 中的 subregion_interests 结构

字段名	类型	说明
position	integer	素位置，从 1 开始递增
type	string	素类型，固定为 subregion_interests
keywords	array	列表，interests 与 interests_comparison 的数据都基于该数组
interests	array	每个在各子区域的热度数据
interests_comparison	object	多子区域热度对比；若只传 1 个则为 null

interests[]

字段名	类型	说明
keyword	string	当前
values	array	当前在不同国家/地区或子区域的相对热度数据

interests[].values[]

字段名	类型	说明
geo_id	string	地域标识，可与地域参数匹使用。可通过 /v3/keywords_data/dataforseo_trends/locations 获取。示例：US-NY
geo_name	string	地域名称，可与地域参数匹使用。示例：Andorra
value	integer	指定地区的相对热度值。算法会找出该在所有地区中的最高热度，并将记为 100，地区按比例折算。100 表示最高热度，50 表示热度约为最高值的一半，0 表示数据不足。

interests_comparison

用于比较多个在不同地区以及跨所有地区的热度差异。

interests_comparison.items[]

表示每个地区，各相对于该地区最高值的占比。

字段名	类型	说明
geo_id	string	地域标识
geo_name	string	地域名称
values	array	当前地区多个的相对热度值。数组顺序与请求中的 keywords 顺序一致。

values 的计算方式：

• 找出该地区所有指定中的最高热度，记为 100
• 按比例换算
• 100 表示该地区最热门的词
• 50 表示热度约为最高词的一半
• 0 表示数据不足

interests_comparison.absolute_items[]

表示跨所有地区整体，各热度相对于局最高值的占比。

字段名	类型	说明
geo_id	string	地域标识
geo_name	string	地域名称
values	array	当前地区多个相对于局最高值的热度百分比。数组顺序与请求中的 keywords 顺序一致。

values 的计算方式：

• 找出所有在所有地区中的局最高热度，记为 100
• 余值按比例折算
• 100 表示局峰值热度
• 50 表示约为局最高值的一半
• 0 表示数据不足

请求示例

cURL

curl --location --request POST "https://api.seermartech.cn/v3/keywords_data/dataforseo_trends/subregion_interests/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"
 }
]'

Python

import requests

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

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

TypeScript

import axios from "axios";

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

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/keywords_data/dataforseo_trends/subregion_interests/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": "0.9749 sec.",
 "cost": 0.002,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.9749 sec.",
 "cost": 0.002,
 "result_count": 1,
 "path": [
 "v3",
 "keywords_data",
 "dataforseo_trends",
 "subregion_interests",
 "live"
 ],
 "data": {
 "api": "keywords_data",
 "function": "subregion_interests",
 "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 11:53:18 +00:00",
 "items_count": 1,
 "items": [
 {
 "position": 1,
 "type": "subregion_interests",
 "keywords": ["rugby", "cricket"],
 "interests": [
 {
 "keyword": "rugby",
 "values": [
 {
 "geo_id": null,
 "geo_name": "Alabama",
 "value": 42
 },
 {
 "geo_id": null,
 "geo_name": "Alaska",
 "value": 18
 }
 ]
 },
 {
 "keyword": "cricket",
 "values": [
 {
 "geo_id": null,
 "geo_name": "Alabama",
 "value": 67
 },
 {
 "geo_id": null,
 "geo_name": "Alaska",
 "value": 21
 }
 ]
 }
 ],
 "interests_comparison": {
 "items": [
 {
 "geo_id": null,
 "geo_name": "Alabama",
 "values": [63, 100]
 },
 {
 "geo_id": null,
 "geo_name": "Alaska",
 "values": [86, 100]
 }
 ],
 "absolute_items": [
 {
 "geo_id": null,
 "geo_name": "Alabama",
 "values": [42, 67]
 },
 {
 "geo_id": null,
 "geo_name": "Alaska",
 "values": [18, 21]
 }
 ]
 }
 }
 ]
 }
 ]
 }
 ]
}

状态码与错误处理

• 顶层 status_code 表示整次请求状态
• tasks[].status_code 表示单个任务状态
• 建议同时检查：
• HTTP 状态码
• 顶层 status_code
• tasks_error
• tasks[].status_code

常见成功状态：

• 20000：成功

完整错误码与状态信息可参考：

• /v3/appendix/errors

建议在生产环境中建立完善的异常处理机制：

• 请求参数校验 -时与重试控制
• 并发限制控制
• 对空结果、null 地域字段、数据不足场景的容处理

结果解读建议

1. 单场景

当只传 1 个时：

• 查看 interests[].values[] 即可判断该词在不同子区域中的热度分布
• interests_comparison 不返回对比数据

2. 多地区对比

查看 interests_comparison.items[]：

• 用于比较某一地区多个谁更热门
• 同一区域最高值恒为 100

3. 多局对比

查看 interests_comparison.absolute_items[]：

• 用于比较多个在所有地区范围的相对强弱
• 可识别“局部强势词”和“局强势词”的差异

实用场景

• 识别区域热词分布：查看某个核心在不同州、省或子区域中的热度差异，帮助制定更精细的地域化 SEO策略。
• 比较竞品词区域优势：同时多个品牌词或品类词，判断它们在不同地区谁更强，市场和投放优级决策。
• 优化本地化落地页：根据各子区域的偏好，调整页面标题、文案和专题，提高本地搜索匹度。
• 发现区域需求偏移：通过一段时间范围的子区域热度变化，识别某些地区需求增长或衰退，为选题和商品布局提供依据。
• 支持区域投放与选品：结合 absolute_items 与 items，判断某是普遍热门还是在局部地区强相关势，从而优化广告预算和区域选品策略。