主题
按任务 ID 获取 Google Trends Explore 结果
本接口用于根据任务 ID 获取 Google Trends Explore 数据结果。
接口说明
- 请求方式：
GET - 接口地址：
https://api.seermartech.cn/v3/keywords_data/google_trends/explore/task_get/$id
该接口返回此前已创建任务的结果数据。计费发生在创建任务时，获取结果本身在任务创建后的 30 天。 扣费以响应头 X-SeerMarTech-Charge-CNY 为准。
计费说明
- 在提交 Explore 任务时扣费
- 任务结果可在 30 天重复获取，不额外收费
- 本接口获取结果通常返回
cost: 0
请求参数
路径参数
| 字段名 | 类型 | 说明 |
|---|---|---|
id | string | 任务唯一标识符，UUID 格式；可在任务创建后 30 天用于随时获取结果 |
沙盒测试
你可以使用以下沙盒地址获取带有模拟数据的完整响应结构：
https://api.seermartech.cn/v3/keywords_data/google_trends/explore/task_get/00000000-0000-0000-0000-000000000000
说明：
- 沙盒响应会返回该端点支持的所有结果项
- 字段结构与正式环境一致，但为模拟数据
- 使用沙盒接口不会产生费用
认证方式
请求头统一使用：
Authorization: Bearer smt_live_YOUR_KEY
请求示例
curl
bash
id="03251338-0696-0170-0000-0d5c6ec12dd2"
curl --location --request GET "https://api.seermartech.cn/v3/keywords_data/google_trends/explore/task_get/${id}" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json"Python
python
import requests
task_id = "02231934-2604-0066-2000-570459f04879"
url = f"https://api.seermartech.cn/v3/keywords_data/google_trends/explore/task_get/{task_id}"
headers = {
"Authorization": "Bearer smt_live_YOUR_KEY",
"Content-Type": "application/json"
}
response = requests.get(url, headers=headers)
print(response.status_code)
print(response.json)TypeScript
typescript
import axios from "axios";
const taskId = "02231934-2604-0066-2000-570459f04879";
axios({
method: "get",
url: `https://api.seermartech.cn/v3/keywords_data/google_trends/explore/task_get/${taskId}`,
headers: {
Authorization: "Bearer smt_live_YOUR_KEY",
"Content-Type": "application/json",
},
})
.then((response) => {
// 输出结果数据
console.log(response.data);
})
.catch((error) => {
console.error(error);
});响应结构
接口返回 JSON 数据，顶层 tasks 数组。
顶层字段
| 字段名 | 类型 | 说明 |
|---|---|---|
version | string | 当前 API 版本 |
status_code | integer | 通用状态码 |
status_message | string | 通用状态信息 |
time | string | 执行耗时，单位秒 |
cost | float | 本次请求总成本，单位 USD |
tasks_count | integer | tasks 数组中的任务数量 |
tasks_error | integer | 返回错误的任务数量 |
tasks | array | 任务结果数组 |
建议在接时设计完善的异常处理与错误码处理机制。
tasks[] 字段
| 字段名 | 类型 | 说明 |
|---|---|---|
id | string | 任务 ID，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 | 结果数组 |
tasks[].result[] 字段
| 字段名 | 类型 | 说明 |
|---|---|---|
keywords | array | POST 请求中提交的数组 |
location_code | integer | POST 请求中的地区代码；若无数据则为 null |
language_code | string | POST 请求中的语言代码；若无数据则为 null |
check_url | string | Google Trends 对应结果直达链接，可用于人工核验 |
datetime | string | 结果抓取时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00 |
items_count | integer | items 数组中的结果项数量 |
items | array | Google Trends 页面中的结果项 |
items[] 支持的类型
Google Trends Explore 结果中的 items 可能以下类型。
1. google_trends_graph
表示趋势折线图数据。
| 字段名 | 类型 | 说明 |
|---|---|---|
position | integer | 素在页面中的位置，如 1、2、3 |
type | string | 固定为 google_trends_graph |
title | string | 图表标题 |
keywords | array | ；该图表基于这些生成 |
data | array | 指定参数下的趋势时间序列数据 |
averages | array | 整个时间范围的平均热度值 |
google_trends_graph.data[]
| 字段名 | 类型 | 说明 |
|---|---|---|
date_from | string | 当前时间段开始日期，UTC 格式：yyyy-mm-dd |
date_to | string | 当前时间段结束日期，UTC 格式：yyyy-mm-dd |
timestamp | integer | Unix 时间戳 |
missing_data | boolean | 是否缺失数据；若为 true，说明 Google Trends 图表该段数据缺失，界面中通常显示为虚线 |
values | array | 指定时间点的相对热度值 |
说明：
values表示在该时间范围的相对热度100表示峰值热度50表示热度约为峰值的一半0表示数据不足- 如果一次提交了多个，
values会按所有中的最高值进行归一化并返回相对平均值
2. google_trends_map
表示地区热度分布数据。
| 字段名 | 类型 | 说明 |
|---|---|---|
position | integer | 素在页面中的位置 |
type | string | 固定为 google_trends_map |
title | string | 地图模块标题 |
keywords | array | ；该地图数据基于这些生成 |
data | array | 地区维度趋势数据 |
google_trends_map.data[]
| 字段名 | 类型 | 说明 |
|---|---|---|
geo_id | string | Google Trends 地区标识符，可用于与请求中的地区参数匹，例如 US-NY |
geo_name | string | Google Trends 地区名称 |
values | array | 该地区的相对热度值 |
max_value_index | integer | 可比中的最大值索引；如果提交了多个，可用来判断该地区由哪个词占优；若只提交一个，则通常为 null |
说明：
values表示指定地区中的相对热度100表示该地区的峰值热度50表示热度约为峰值的一半0表示数据不足- 如果提交了多个，
values会按所有中的最高值进行归一化并返回相对平均值
3. google_trends_topics_list
表示主题列表。
| 字段名 | 类型 | 说明 |
|---|---|---|
position | integer | 素在页面中的位置 |
type | string | 固定为 google_trends_topics_list |
title | string | 模块标题 |
keywords | array | |
data | object | 主题数据对象 |
google_trends_topics_list.data.top[]
| 字段名 | 类型 | 说明 |
|---|---|---|
topic_id | string | Google Trends 主题唯一标识 |
topic_title | string | 主题名称 |
topic_type | string | 主题类型 |
value | string | 搜索热度值，采用相对评分；100 为最高热度，50 为一半 |
google_trends_topics_list.data.rising[]
| 字段名 | 类型 | 说明 |
|---|---|---|
topic_id | string | Google Trends 主题唯一标识 |
topic_title | string | 主题名称 |
topic_type | string | 主题类型 |
value | string | 热度增，按百分比返回，但不带 % 符号 |
4. google_trends_queries_list
表示查询词列表。
| 字段名 | 类型 | 说明 |
|---|---|---|
position | integer | 素在页面中的位置 |
type | string | 固定为 google_trends_queries_list |
title | string | 模块标题 |
keywords | array | |
data | object | 查询词数据 |
google_trends_queries_list.data.top[]
| 字段名 | 类型 | 说明 |
|---|---|---|
query | string | 查询词 |
value | string | 搜索热度值，采用相对评分；100 为最高热度，50 为一半 |
google_trends_queries_list.data.rising[]
| 字段名 | 类型 | 说明 |
|---|---|---|
query | string | 新查询词 |
value | string | 搜索热度值或增长值，以返回为准 |
响应示例
json
{
"version": "0.1.20220420",
"status_code": 20000,
"status_message": "Ok.",
"time": "0.2249 sec.",
"cost": 0,
"tasks_count": 1,
"tasks_error": 0,
"tasks": [
{
"id": "03251338-0696-0170-0000-0d5c6ec12dd2",
"status_code": 20000,
"status_message": "Ok.",
"time": "0.1023 sec.",
"cost": 0,
"result_count": 1,
"path": [
"v3",
"keywords_data",
"google_trends",
"explore",
"task_get",
"03251338-0696-0170-0000-0d5c6ec12dd2"
],
"data": {
"api": "keywords_data",
"function": "explore",
"se": "google_trends",
"date_from": "2019-01-01",
"date_to": "2020-01-01",
"keywords": [
"seo api",
"rank api"
]
},
"result": [
{
"type": "trends",
"location_code": 0,
"language_code": "en",
"check_url": "https://trends.google.com/trends/explore?hl=en&date=2019-01-01%202020-01-01&q=seo%20api%2Crank%20api",
"datetime": "2022-04-21 18:22:05 +00:00",
"items_count": 6,
"items": [
{
"position": 1,
"type": "google_trends_graph",
"title": "Interest over time",
"keywords": [
"seo api",
"rank api"
],
"data": [
{
"date_from": "2019-01-13",
"date_to": "2019-01-19",
"timestamp": 1547337600,
"missing_data": false,
"values": [73, 100]
}
],
"averages": [64, 82]
},
{
"position": 2,
"type": "google_trends_map",
"title": "Compared breakdown by region",
"keywords": [
"seo api",
"rank api"
],
"data": [
{
"geo_id": "VN",
"geo_name": "Vietnam",
"values": [54, 88],
"max_value_index": 1
},
{
"geo_id": "EG",
"geo_name": "Egypt",
"values": [92, 45],
"max_value_index": 0
}
]
},
{
"position": 4,
"type": "google_trends_queries_list",
"title": "Related queries",
"keywords": [
"seo api",
"rank api"
],
"data": {
"top": [
{
"query": "seo ranking api",
"value": "100"
}
],
"rising": [
{
"query": "best rank api",
"value": "250"
}
]
}
}
]
}
]
}
]
}状态码与错误处理
- 顶层
status_code表示整个请求的处理状态 tasks[].status_code表示单个任务的处理状态- 任务状态码通常位于
10000–60000范围 - 当
tasks[].status_code >= 40000或result为空时，建议按失败处理 - 实接时，请同时检查：
- HTTP 状态码
- 顶层
status_code - 任务级
tasks[].status_code tasks_errorresult_count是否大于 0
使用建议
通常推荐按以下流程使用：
- 提交 Google Trends Explore 任务
- 通过对应的 ready 接口查询已完成任务
- 再使用本接口按
id获取结果 - 在 30 天可重复获取结果用于重跑、复核或补数
实用场景
- 拉取趋势曲线：获取在指定时间范围的热度变化，用于判断季节性波动、活动周期和发布时间窗口。
- 比较多个热度：同时查看多个词的相对趋势与地区分布，用于品牌词、竞品词和主题词优级排序。
- 定位高热地区：基于
google_trends_map找出更高的国家或区域，为 SEO、本地化和投放市场选择提供依据。 - 挖掘搜索词：利用
google_trends_queries_list中的top与rising数据，发现新增需求词、长尾词和热点话题。 - 识别选题方向：结合主题与上升查询词，提前发现行业新趋势，栏目策划、专题页建设和扩展。