创建 Google Trends Explore 任务

/v3/keywords_data/google_trends/explore/task_post 用于创建 Google Trends「Explore」数据采集任务。通过本接口，你可以获取在 Google Trends Explore 中的热度趋势数据，并支持以下搜索类型：

• Google Search（web）
• Google News（news）
• Google Images（images）
• Google Shopping（froogle）
• YouTube（youtube）

这是标准异步模式接口：创建任务，再在任务完成后获取结果。若你的业务不要求实时返回，推荐优使用该方式，通常更稳定，也更适合批量处理。任务执行时间取决于系统负载。

如果你需要实时结果，可改用实时接口：/v3/keywords_data/google_trends/explore/live/。

接口地址

POST https://api.seermartech.cn/v3/keywords_data/google_trends/explore/task_post

计费说明

本接口在创建任务时扣费。

参考价需以参考单价换算；但当前原文未给出明确单次 USD 单价，因此扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

限流与使用限制

由于 Google Trends 服务本身存在容量限制及访问约束，本平台在所有 Google Trends API 端点、所有用户范围，每日总请求量受限为 500,000 次。建议将请求分散到多天执行，以降低采集失败风险并提升稳定性。

此外：

• 每分钟最多可发送 2000 次 API 调用
• 每次 POST 最多可 100 个任务
• 如果单次 POST 中任务数 100，出部分会返回错误 40006
• 单个 keywords 数组中最多可传 5 个
• 无论 keywords 中传 1 个还是 5 个，均按每次请求计费

历史数据范围

• web 类型最早支持：2004-01-01
• 类型（news、youtube、images、froogle）最早支持：2008-01-01

结果获取方式

创建任务后，你可以通过以下方式获取结果：

1. 使用任务唯一标识 id 查询已完成任务结果
2. 在创建任务时指定 postback_url，任务完成后由本平台主动推送结果
3. 在创建任务时指定 pingback_url，任务完成后由本平台发送完成通知

注意：

• 如果你的服务端在 10 秒未响应 回调请求，连接会时中止
• 此类任务会被转移到 tasks_ready 列表，后续可自行获取结果
• 错误码和错误信息取决于你的服务端

请求体格式

所有 POST 数据使用 JSON（UTF-8 编码）提交。

请求体格式为JSON 数组：

[
 {
 "keywords": ["seo api"],
 "location_name": "United States",
 "date_from": "2019-01-01",
 "date_to": "2020-01-01"
 }
]

---

请求参数

顶层任务对象字段

字段名	类型	说明
keywords	array	填。列表。最多 5 个；单个最长 100 个字符；最少长度大于 1。中的逗号（,）会被移除并忽略。不能由以下字符组合构成：`< >
location_name	string	可选。搜索地域名。不传则返回结果。若已传该字段，则无需再传 location_code。也支持传数组，为每个分别指定地域。示例：United Kingdom。可通过 /v3/keywords_data/google_trends/locations 获取可用地域列表。
location_code	integer	可选。搜索地域代码。不传则返回结果。若已传该字段，则无需再传 location_name。也支持传数组，为每个分别指定地域。示例：2840。可通过 /v3/keywords_data/google_trends/locations 获取可用地域列表。
language_name	string	可选。语言名。默认值：English。若已传该字段，则无需再传 language_code。示例：English。可通过 /v3/keywords_data/google_trends/languages 获取可用语言列表。
language_code	string	可选。语言代码。默认值：en。若已传该字段，则无需再传 language_name。示例：en。可通过 /v3/keywords_data/google_trends/languages 获取可用语言列表。
type	string	可选。Google Trends 数据类型。默认值：web。可选值：web、news、youtube、images、froogle。
category_code	integer	可选。Google Trends 搜索分类代码。默认值：0，表示所有分类。可通过 /v3/keywords_data/google_trends/categories 获取可用分类列表。
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，该字段会被忽略。所有 type 通用可选值：past_hour、past_4_hours、past_day、past_7_days、past_30_days、past_90_days、past_12_months、past_5_years。 web 可用：2004_present。 news、youtube、images、froogle 可用：2008_present。
item_types	array	可选。指定需要返回的数据项类型。为提升执行速度，建议一次只请求一种 item。可选值：google_trends_graph、google_trends_map、google_trends_topics_list、google_trends_queries_list。默认值：google_trends_graph。**注意：**获取 google_trends_topics_list 或 google_trends_queries_list 时，keywords 中最多只能有 1 个。
postback_url	string	可选。结果推送地址。任务完成后，本平台会以 gzip 压缩的 POST 请求将结果发送到该地址。支持使用 $id 变量和 URL 编码后的 $tag 变量。示例：http://your-server.com/postbackscript?id=$id。特殊字符会进行 URL 编码，例如 # 会被转为 %23。
pingback_url	string	可选。完成通知地址。任务完成后，本平台会以 GET 请求通知该地址。支持使用 $id 变量和 URL 编码后的 $tag 变量。示例：http://your-server.com/pingscript?id=$id&tag=$tag。特殊字符会进行 URL 编码，例如 # 会被转为 %23。
tag	string	可选。用户自定义任务标识，最长 255 个字符。可用于将任务与业务系统中的记录进行，提交后会在响应的 data 对象中返回。

---

响应说明

接口返回 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	请求路径
data	object	与提交时相同的任务参数
result	array	结果数组。对于任务创建接口，此处为 null

---

请求示例

cURL

curl --location --request POST "https://api.seermartech.cn/v3/keywords_data/google_trends/explore/task_post" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "location_name": "United States",
 "date_from": "2019-01-01",
 "date_to": "2020-01-01",
 "keywords": ["seo api"]
 },
 {
 "location_name": "United States",
 "date_from": "2019-01-01",
 "date_to": "2020-01-01",
 "type": "youtube",
 "category_code": 3,
 "keywords": ["seo api", "rank api"],
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 },
 {
 "location_name": "United States",
 "date_from": "2019-01-01",
 "date_to": "2020-01-01",
 "type": "youtube",
 "category_code": 3,
 "keywords": ["seo api", "rank api"],
 "postback_url": "https://your-server.com/postbackscript"
 }
]'

Python

import requests

url = "https://api.seermartech.cn/v3/keywords_data/google_trends/explore/task_post"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

data = [
 {
 "location_name": "United States",
 "date_from": "2019-01-01",
 "date_to": "2020-01-01",
 "keywords": ["seo api"]
 },
 {
 "location_name": "United States",
 "date_from": "2019-01-01",
 "date_to": "2020-01-01",
 "type": "youtube",
 "category_code": 3,
 "keywords": ["seo api", "rank api"],
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 },
 {
 "location_name": "United States",
 "date_from": "2019-01-01",
 "date_to": "2020-01-01",
 "type": "youtube",
 "category_code": 3,
 "keywords": ["seo api", "rank api"],
 "postback_url": "https://your-server.com/postbackscript"
 }
]

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

TypeScript

import axios from "axios";

const postData = [
 {
 location_name: "United States",
 date_from: "2019-01-01",
 date_to: "2020-01-01",
 keywords: ["seo api"]
 },
 {
 location_name: "United States",
 date_from: "2019-01-01",
 date_to: "2020-01-01",
 type: "youtube",
 category_code: 3,
 keywords: ["seo api", "rank api"],
 tag: "some_string_123",
 pingback_url: "https://your-server.com/pingscript?id=$id&tag=$tag"
 },
 {
 location_name: "United States",
 date_from: "2019-01-01",
 date_to: "2020-01-01",
 type: "youtube",
 category_code: 3,
 keywords: ["seo api", "rank api"],
 postback_url: "https://your-server.com/postbackscript"
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/keywords_data/google_trends/explore/task_post",
 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.20200130",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0882 sec.",
 "cost": 0.15,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0312 sec.",
 "cost": 0.15,
 "result_count": 0,
 "path": [
 "v3",
 "keywords_data",
 "google_trends",
 "explore",
 "task_post"
 ],
 "data": {
 "api": "keywords_data",
 "function": "explore",
 "se": "google_trends",
 "location_name": "United States",
 "type": "youtube",
 "date_from": "2019-01-15",
 "date_to": "2020-01-01",
 "category_code": 3,
 "keywords": [
 "seo api",
 "rank api"
 ]
 },
 "result": null
 }
 ]
}

---

错误处理建议

建议在接时重点处理以下：

• 顶层 status_code 非 20000
• tasks 中存在任务级错误
• 单次 POST 创建任务数 100，触发 40006
• 回调地址时或不可访问，导致任务转 tasks_ready
• 日期范围早于当前 type 支持的最小历史时间
• 请求 google_trends_topics_list 或 google_trends_queries_list 时传了多个

完整错误码说明可参考 /v3/appendix/errors。

使用建议

• 如需提升成功率，建议将大批量 Google Trends 请求拆分到不同时间段执行
• 如只需要某一种结果项，建议通过 item_types 只请求单一类型，以缩短任务执行时间
• 如业务需要按对应不同国家/地区分析，可使用数组形式的 location_name 或 location_code
• 如果你只分析主题或查询，建议每次提交 1 个，以返回限制

实用场景

• 监控热度变化：按周或按月追踪核心 SEO 的搜索热度走势，判断时机。
• 比较多词趋势表现：将最多 5 个候选放同一任务中，对比热度强弱，为选题和落地页规划提供依据。
• 分析不同渠道差异：切换 web、youtube、news 等 type，识别用户在网页搜索、视频搜索和新闻场景中的差别。
• 定位地域搜索机会：结合 location_name 或 location_code，观察不同国家或地区的趋势表现，支持 SEO 与本地化投放。
• 追踪品类季节性波动：通过 category_code 和历史时间范围，识别行业在年度周期中的峰值与淡季，优化发布节奏。