SeerMarTech API 文档

主题

按任务 ID 获取 Google Trends 探索结果 ​

本接口用于获取指定任务的 Google Trends 探索结果。

请求方式与路径：

http
GET https://api.seermartech.cn/v3/keywords_data/google_trends/explore/task_get/$id

，$id 为创建探索任务时返回的任务 ID。

计费说明 ​

  • 创建任务时计费，获取已创建任务的结果不再单独计费。
  • 任务结果可在创建后的 30 天重复获取。
  • 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数 ​

请求参数通过 URL 路径传递。

参数类型说明
idstring任务唯一标识，UUID 格式。任务创建后 30 天可使用该 ID 获取结果。

响应说明 ​

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

顶层字段 ​

字段类型说明
versionstring当前 API 版本。
status_codeinteger通用响应状态码。成功通常为 20000。
status_messagestring通用状态说明。
timestring接口执行耗时，单位为秒。
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
tasks_countintegertasks 数组中的任务数量。
tasks_errorintegertasks 数组中返回错误的任务数量。
tasksarray任务结果数组。

tasks 数组中的字段 ​

字段类型说明
idstring任务唯一标识，UUID 格式。
status_codeinteger任务状态码，通常在 10000 至 60000 范围。
status_messagestring任务状态说明。
timestring任务执行耗时，单位为秒。
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
result_countintegerresult 数组中的数量。
patharray请求对应的 URL 路径信息。
dataobject创建任务时提交的参数。
resultarrayGoogle Trends 探索结果数组。

result 字段 ​

字段类型说明
keywordsarray创建任务时提交的列表。
location_codeinteger创建任务时提交的地区代码。无数据时为 null。
language_codestring创建任务时提交的语言代码。无数据时为 null。
check_urlstring对应的 Google Trends 结果页面地址，可用于人工核验结果。
datetimestring结果接收时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00。
items_countintegeritems 数组中的数量。
itemsarrayGoogle Trends 页面中的数据模块。

items 数据模块 ​

items 中的模块通过 type 区分。position 表示模块在 Google Trends 页面中的排列位置，通常从 1 开始。

趋势图模块 ​

模块对象字段名为 google_trends_graph_element_in_google_trends。

字段类型说明
positioninteger模块排列位置，例如 1、2、3。
typestring固定为 google_trends_graph。
titlestring模块标题。
keywordsarray当前趋势图对应的。
dataarray指定时间范围的趋势数据。
averagesarray整个时间范围的平均热度。

data 数组字段 ​

字段类型说明
date_fromstring当前时间区间开始日期，UTC 格式：yyyy-mm-dd。
date_tostring当前时间区间结束日期，UTC 格式：yyyy-mm-dd。
timestampinteger当前数据点的 Unix 时间戳。
missing_databoolean是否缺少数据。为 true 时，Google Trends 页面通常以点状线表示该区间。
valuesarray指定时间点的相对热度。

values 的取值范围通常为 0 至 100：

  • 100 表示该时间范围的最高热度；
  • 50 表示热度约为最高值的一半；
  • 0 表示数据不足，无法计算有效热度；
  • 当请求多个时，各热度会最高值进行归一化后计算。

地区对比地图模块 ​

模块对象名为 google_trends_map_element_in_google_trends。

字段类型说明
positioninteger模块排列位置。
typestring固定为 google_trends_map。
titlestring模块标题。
keywordsarray当前地图对应的。
dataarray各地区的趋势数据。

地区数据字段 ​

字段类型说明
geo_idstringGoogle Trends 地区标识，例如 US-NY。可用于与请求中的地区参数匹。
geo_namestring地区名称。
valuesarray当前地区在指定时间范围的相对热度。
max_value_indexinteger | null可比较中的最高值索引。当只提交一个时通常为 null。

当请求多个时，地区热度同样所有中的最高值进行归一化。

主题模块 ​

模块对象名为 google_trends_topics_list_element_in_google_trends。

字段类型说明
positioninteger模块排列位置。
typestring固定为 google_trends_topics_list。
titlestring模块标题。
keywordsarray当前模块对应的。
dataobject主题数据。

data.top：热门主题 ​

字段类型说明
topic_idstringGoogle Trends 中的主题唯一标识。
topic_titlestring主题名称。
topic_typestring主题类型。
valuestring主题相对搜索热度。100 表示最热门主题，50 表示约为最高热度的一半。

data.rising：增长最快的主题 ​

字段类型说明
topic_idstringGoogle Trends 中的主题唯一标识。
topic_titlestring主题名称。
topic_typestring主题类型。
valuestring搜索热度增长比例，以百分比数值表示，不 % 符号。

查询模块 ​

模块对象名为 google_trends_queries_list_element_in_google_trends。

字段类型说明
positioninteger模块排列位置。
typestring固定为 google_trends_queries_list。
titlestring模块标题。
keywordsarray当前模块对应的。
dataobject查询数据。

data.top：热门查询 ​

字段类型说明
querystring搜索词。
valuestring搜索词的相对热度。

data.rising：增长最快的查询 ​

字段类型说明
querystring搜索词。
valuestring搜索热度增长比例，以百分比数值表示，不 % 符号。

请求示例 ​

curl ​

bash
task_id="03251338-0696-0170-0000-0d5c6ec12dd2"

curl --location --request GET \
  "https://api.seermartech.cn/v3/keywords_data/google_trends/explore/task_get/${task_id}" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json"

Python ​

python
import requests

task_id = "03251338-0696-0170-0000-0d5c6ec12dd2"

response = requests.get(
    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",
    },
)

data = response.json()

if data.get("status_code") == 20000:
    print(data)
else:
    print(
        f"请求失败，状态码：{data.get('status_code')}，"
        f"消息：{data.get('status_message')}"
    )

TypeScript ​

typescript
import axios from "axios";

const taskId = "03251338-0696-0170-0000-0d5c6ec12dd2";

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

响应示例 ​

以下示例展示主要字段和型数据结构：

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.1800 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "keywords_data",
        "google_trends",
        "explore",
        "task_get"
      ],
      "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": 3,
          "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": [100, 54]
                }
              ],
              "averages": [63, 42]
            },
            {
              "position": 2,
              "type": "google_trends_map",
              "title": "Interest by region",
              "keywords": [
                "seo api",
                "rank api"
              ],
              "data": [
                {
                  "geo_id": "US",
                  "geo_name": "United States",
                  "values": [100, 47],
                  "max_value_index": 0
                }
              ]
            },
            {
              "position": 3,
              "type": "google_trends_queries_list",
              "title": "Related queries",
              "keywords": [
                "seo api"
              ],
              "data": {
                "top": [
                  {
                    "query": "seo api tools",
                    "value": "100"
                  }
                ],
                "rising": [
                  {
                    "query": "seo trends api",
                    "value": "250"
                  }
                ]
              }
            }
          ]
        }
      ]
    }
  ]
}

错误处理 ​

请同时检查顶层 status_code 和任务级别的 tasks[].status_code：

  • 20000：请求成功；
  • 40000 及以上：任务执行或参数处理失败；
  • 状态码：根据 status_message 判断原因。

建议在生产环境中实现以下处理机制：

  1. 检查 HTTP 状态码和 JSON 中的 status_code；
  2. 检查 tasks_error 是否大于 0；
  3. 对任务级错误记录 id、status_code 和 status_message；
  4. 对临时性错误实施有限次数的重试；
  5. 在任务结果有效期 30 天保存已成功获取的数据。

实用场景 ​

  • 监测趋势：定期获取热度曲线，识别季节性需求和突发增长，指导发布节奏。
  • 比较目标市场热度：利用地区地图数据比较不同国家或地区的，确定本地化 SEO 和投放优级。
  • 挖掘增长型主题：分析 rising 主题，提前发现搜索需求快速增长的新话题，抢占排名窗口。
  • 扩展选题：读取热门查询，补长尾和文章子主题，提升覆盖范围。
  • 评估竞争方向：对多个进行趋势对比，判断用户变化，为集群和产品定位提供依据。

统一入口：官网 · LLM API · 控制台

© 2026 SeerMarTech · GEO · SEO 营销数据 API