设置 Google Trends Explore 任务

POST /v3/keywords_data/google_trends/explore/task_post

接口说明

POST /v3/keywords_data/google_trends/explore/task_post

本接口用于创建 Google Trends「探索」任务，获取在 Google 搜索、Google 新闻、Google 图片、Google 购物和 YouTube 等渠道中的热度趋势数据。

这是标准的异步数据获取方式：提交任务后，系统将在后台采集数据。任务完成后，可根据任务 id 查询结果，也可以通过 postback_url 或 pingback_url 接收通知。执行时间取决于系统负载。

如果业务需要即时返回结果，可使用 Live 方法，该方式无需分别调用任务创建和结果查询接口。

数据时间范围

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

使用限制

由于 Google Trends 服务容量及限制，所有 Google Trends 接口及所有用户合计每日最多处理约 500,000 次请求。建议将请求分散到多个工作日，以减少数据采集错误并保持稳定访问。

单个 POST 请求最多 100 个任务；每分钟最多可发送 2,000 次 API 请求。单次 100 个任务的部分将返回错误码 40006。

每个任务的 keywords 数组最多 5 个。费用按任务请求计算，与单个数组中 1 个还是 5 个无。

计费说明

提交任务时计费，查询已完成任务通常不会重复收取任务创建费用。

响应中的 cost 字段（平台原始 USD 成本兼容字段）为容字段。原始示例中的任务成本为 0.15，按 1 美约合 7.2人民币粗略折算，参考价约 ¥1.08 / 任务。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求格式

请求体使用 UTF-8 编码的 JSON 数组：

json

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

一个请求中的每个数组代表一个独立任务。

结果通知

任务完成后，可使用以下任一方式接收结果：

使用任务 id 调用对应的结果查询接口； -置 postback_url，系统将通过 POST 请求发送结果，使用 gzip 压缩； -置 pingback_url，系统将通过 GET 请求发送完成通知。

如果接收服务器在 10 秒未返回响应，连接将因时中断，任务会转移至 tasks_ready 列表。错误码和错误消息取决于接收服务器的。

postback_url 和 pingback_url 支持以下变量：

$id：任务 ID
$tag：经过 URL 编码的任务标签

URL 中的特殊字符会进行 URL 编码，例如 # 会编码为 %23。

请求参数

参数	类型	填	说明
`keywords`	array	是	要分析的数组。最多 5 个；每个最多 100 个字符，长度大于 1。中的逗号会被移除并忽略。不能由以下特殊字符组合构成：`< > \| " - + = ~ ! : * ( ) { }`。如果需要获取 `google_trends_topics_list` 或 `google_trends_queries_list`，最多只能传 1 个。
`location_name`	string 或 array	否	搜索引擎位置的完整名称。不传时返回数据。与 `location_code` 不能同时使用。也可以传数组，为不同分别指定位置。可通过 `/v3/keywords_data/google_trends/locations` 获取可用位置。示例：`United Kingdom`。
`location_code`	integer 或 array	否	搜索引擎位置代码。不传时返回数据。与 `location_name` 不能同时使用。也可以传数组，为不同分别指定位置。可通过 `/v3/keywords_data/google_trends/locations` 获取可用位置代码。示例：`2840`。
`language_name`	string	否	搜索引擎语言的完整名称。默认值为 `English`。与 `language_code` 不能同时使用。可通过 `/v3/keywords_data/google_trends/languages` 获取可用语言。
`language_code`	string	否	搜索引擎语言代码。默认值为 `en`。与 `language_name` 不能同时使用。可通过 `/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`，则创建任务时忽略此参数。所有类型支持：`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	否	返回的数据项目类型。可选值：`google_trends_graph`、`google_trends_map`、`google_trends_topics_list`、`google_trends_queries_list`。默认值为 `["google_trends_graph"]`。为提高执行速度，建议一次只指定一种项目类型。获取主题列表或查询列表时，`keywords` 最多只能 1 个。
`postback_url`	string	否	任务完成后，系统向该地址发送结果的 POST 请求，使用 gzip 压缩。支持 `$id` 和 `$tag` 变量。示例：`https://your-server.com/postbackscript?id=$id&tag=$tag`。
`pingback_url`	string	否	任务完成后，系统向该地址发送 GET 请求进行通知。支持 `$id` 和 `$tag` 变量。示例：`https://your-server.com/pingscript?id=$id&tag=$tag`。
`tag`	string	否	自定义任务标识，最多 255 个字符。可用于任务与业务记录。提交后可在响应的 `data` 对象中获取。

请求示例

curl

bash

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

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",
}

payload = [
    {
        "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",
        "postback_url": "https://your-server.com/postbackscript",
    },
]

response = requests.post(url, headers=headers, json=payload, timeout=30)
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: "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",
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/keywords_data/google_trends/explore/task_post",
    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 数组。任务创建成功时，任务的 result 通常为 null，需要在任务完成后通过任务 ID 获取结果，或回调通知。

顶层响应字段

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	请求级状态码。完整错误码列表请参考错误码文档。
`status_message`	string	请求级状态信息。
`time`	string	请求执行时间，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务总数。
`tasks_error`	integer	`tasks` 数组中返回错误的任务数量。
`tasks`	array	已创建任务列表。

`tasks` 数组中的任务字段

字段	类型	说明
`id`	string	系统生成的唯一任务标识，采用 UUID 格式。
`status_code`	integer	任务级状态码，通常位于 `10000` 至 `60000` 范围。
`status_message`	string	任务级状态信息。
`time`	string	任务执行时间，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`result_count`	integer	`result` 数组中的数量。任务刚创建时通常为 `0`。
`path`	array	请求 URL 路径信息。
`data`	object	创建任务时提交的参数。
`result`	array 或 null	任务结果。创建任务时通常为 `null`。

响应示例

json

{
  "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": " ಮರ",
      "status_code": 20100,
      "status_message": "Task Created.",
      "time": "0.0123 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"]
      },
      "result": null
    }
  ]
}

> id 应为系统生成的 UUID。上例中的 id 用于展示字段结构，开发时请使用接口返回的真实任务 ID。

错误处理

建议客户端同时检查以下状态字段：

status_code：判断请求或任务是否成功；
status_message：获取可读的状态说明；
tasks_error：判断批量任务中是否存在失败任务；
tasks[].status_code：定位任务的处理结果。

当单次请求 100 个任务时，出部分将返回错误码 40006。完整错误码及状态说明请参考 /v3/appendix/errors。

实用场景

监测核心的长期热度：按周或按月获取趋势，识别季节性需求并优化发布计划。
比较不同搜索渠道的用户：分别查询 web、news、youtube、images 和 froogle 数据，为渠道化 SEO 和分发提供依据。
分析地区化搜索需求：为不同不同 location_name 或 location_code，制定国家、地区或市场级 SEO 策略。
发现主题与热门查询：使用 google_trends_topics_list 和 google_trends_queries_list 扩展集合，支持选题和聚类。
跟踪行业事件带来的搜索波动：设置自定义时间范围和分类代码，评估新闻事件、产品发布或营销活动对搜索热度的影响。

设置 Google Trends Explore 任务 ​

接口说明 ​

数据时间范围 ​

使用限制 ​

计费说明 ​

请求格式 ​

结果通知 ​

请求参数 ​

请求示例 ​

curl ​

Python ​

TypeScript ​

响应说明 ​

顶层响应字段 ​

tasks 数组中的任务字段 ​

响应示例 ​

错误处理 ​

实用场景 ​