实时获取 Google Trends Explore 数据

POST /v3/keywords_data/google_trends/explore/live

本接口使用 POST 方法，路径为：

/v3/keywords_data/google_trends/explore/live

用于实时获取 Google Trends「探索」功能中的热度数据，支持 Google Search、Google News、Google Images、Google Shopping 和 YouTube 等数据类型。

Live 方法会在单次请求中直接返回结果，无需像 Standard 方法一样分别调用任务提交和结果查询接口。每次 API 调用只能提交 1 个任务，但一个任务最多可 5 个。

> 限流说明 > > - 单分钟提交 250 个 Live 任务时，可能触发限流错误。 > - 所有 Google Trends 接口合计每日最多处理 500,000 次请求。建议将大批量请求分散到多个日期，以降低数据采集失败概率。 > - 如需更高吞吐量，建议使用 Standard 方法 /v3/keywords_data/google_trends/explore/task_post。该方式支持每分钟最多 2,000 次 API 调用，每次 POST 最多提交 100 个任务，且价格更低，但需要额外调用结果查询接口。

历史数据范围：

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

请求信息

http

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

请求头：

http

Authorization: Bearer smt_live_YOUR_KEY
Content-Type: application/json

请求体使用 UTF-8 编码的 JSON 数组格式。每次 Live API 调用只能一个任务对象：

json

[
  {
    "location_name": "United States",
    "date_from": "2019-01-01",
    "date_to": "2020-01-01",
    "type": "youtube",
    "category_code": 3,
    "keywords": [
      "rugby",
      "cricket"
    ]
  }
]

计费说明

本接口按请求计费，无论 keywords 数组中 1 个还是多个，均按一次请求扣费。

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

请求参数

参数	类型	填	说明
`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`、`news`、`youtube`、`images`、`froogle`。默认值为 `web`。
`category_code`	integer	否	搜索类别代码。默认值为 `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`；类型支持 `2008_present`。
`item_types`	array	否	指定返回的数据项类型。可选值：`google_trends_graph`、`google_trends_map`、`google_trends_topics_list`、`google_trends_queries_list`。默认值为 `["google_trends_graph"]`。为提升执行速度，建议每次只指定一种类型。返回主题或查询时，`keywords` 最多只能 1 个。
`tag`	string	否	自定义任务标识，最多 255 个字符。可用于在响应结果中匹任务，提交的值会原样返回在任务的 `data` 对象中。

响应结构

接口返回 JSON 数据 tasks 数组。

顶层响应字段

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

任务字段

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

`result` 字段

字段	类型	说明
`keywords`	array	请求中提交的。
`location_code`	integer	请求对应的地域代码。无可用数据时为 `null`。
`language_code`	string	请求对应的语言代码。无可用数据时为 `null`。
`check_url`	string	对应的 Google Trends 结果页面 URL，可用于核验数据。
`datetime`	string	接收结果的时间，UTC 格式为 `yyyy-mm-dd hh-mm-ss +00:00`。
`items_count`	integer	`items` 数组中的数量。
`items`	array	返回的数据项。

`items` 数据项

`google_trends_graph`

表示指定时间范围的热度趋势。

字段	类型	说明
`position`	integer	素在 Google Trends 页面中的位置，如 `1`、`2`、`3`。
`type`	string	固定为 `google_trends_graph`。
`title`	string	图表标题。
`keywords`	array	当前图表对应的。
`data`	array	按时间点返回的趋势数据。
`averages`	array	所有时间范围计算得到的平均热度。

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`	integer	当前时间点的相对热度。100 表示该时间范围的最高热度，50 表示约为最高热度的一半，0 表示数据不足。多个同时查询时，数值会以所有中的最高值为基准进行归一化。

`google_trends_map`

表示不同地域的热度分布。

字段	类型	说明
`position`	integer	素在 Google Trends 页面中的位置。
`type`	string	固定为 `google_trends_map`。
`title`	string	地图标题。
`keywords`	array	当前地图对应的。
`data`	array	各地域的热度数据。

data 数组中的字段：

字段	类型	说明
`geo_id`	string	Google Trends 地域标识，可用于匹请求中的地域参数。示例：`US-NY`。
`geo_name`	string	地域名称。
`values`	integer	指定地域中的相对热度。100 表示最高热度，50 表示约为最高热度的一半，0 表示数据不足。多个同时查询时，以所有中的最高值为基准进行归一化。
`max_value_index`	integer 或 null	可比较中的最大值索引。提交多个时返回对应索引；只提交一个时为 `null`。

`google_trends_topics_list`

返回与的主题列表。使用该类型时，keywords 最多只能 1 个。

字段	类型	说明
`position`	integer	素在 Google Trends 页面中的位置。
`type`	string	固定为 `google_trends_topics_list`。
`title`	string	主题列表标题。
`keywords`	array	当前主题列表对应的。
`data`	object	主题数据。

data 对象：

top：最热门的主题。
rising：搜索频率增长最快的新主题。

主题字段：

字段	类型	说明
`topic_id`	string	Google Trends 中的主题唯一标识。
`topic_title`	string	主题名称。
`topic_type`	string	主题类型。
`value`	string	主题热度。`top` 中为相对热度值，100 表示最热门主题；`rising` 中表示指定时间范围的相对增长度，数值不 `%` 符号。

`google_trends_queries_list`

返回与的搜索查询列表。使用该类型时，keywords 最多只能 1 个。

字段	类型	说明
`position`	integer	素在 Google Trends 页面中的位置。
`type`	string	固定为 `google_trends_queries_list`。
`title`	string	查询列表标题。
`keywords`	array	当前查询列表对应的。
`data`	object	查询数据。

data 对象：

top：最热门的查询。
rising：搜索频率增长最快的新查询。

查询字段：

字段	类型	说明
`query`	string	搜索查询。
`value`	string	查询热度。`top` 中为相对热度值，100 表示最热门查询；`rising` 中表示指定时间范围的相对增长度，数值不 `%` 符号。

请求示例

curl

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/keywords_data/google_trends/explore/live" \
  --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",
      "type": "youtube",
      "category_code": 3,
      "keywords": [
        "rugby",
        "cricket"
      ]
    }
  ]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/keywords_data/google_trends/explore/live"

payload = [
    {
        "location_name": "United States",
        "date_from": "2019-01-01",
        "date_to": "2020-01-01",
        "type": "youtube",
        "category_code": 3,
        "keywords": ["rugby", "cricket"]
    }
]

headers = {
    "Authorization": "Bearer smt_live_YOUR_KEY",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)
result = response.json()

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        f"请求失败，错误码：{result.get('status_code')}，"
        f"错误信息：{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",
    type: "youtube",
    category_code: 3,
    keywords: ["rugby", "cricket"]
  }
];

axios.post(
  "https://api.seermartech.cn/v3/keywords_data/google_trends/explore/live",
  payload,
  {
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json"
    }
  }
).then((response) => {
  const result = response.data;

  if (result.status_code === 20000) {
    console.log(result);
  } else {
    console.error(result.status_code, result.status_message);
  }
}).catch((error) => {
  console.error("请求异常：", error.message);
});

响应示例

json

{
  "version": "0.1.20220420",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "6.1707 sec.",
  "cost": 0.0648,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "6f2f7c1e-8e6a-4a1f-9e2f-123456789abc",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "6.1707 sec.",
      "cost": 0.0648,
      "result_count": 1,
      "path": [
        "v3",
        "keywords_data",
        "google_trends",
        "explore",
        "live"
      ],
      "data": {
        "api": "keywords_data",
        "function": "explore",
        "se": "google_trends",
        "location_name": "United States",
        "date_from": "2019-01-01",
        "date_to": "2020-01-01",
        "keywords": [
          "rugby",
          "cricket"
        ]
      },
      "result": [
        {
          "type": "trends",
          "location_code": 2840,
          "language_code": "en",
          "check_url": "https://trends.google.com/trends/explore?hl=en&geo=US",
          "datetime": "2022-04-21 18:40:17 +00:00",
          "items_count": 1,
          "items": [
            {
              "position": 1,
              "type": "google_trends_graph",
              "title": "Interest over time",
              "keywords": [
                "rugby",
                "cricket"
              ],
              "data": [
                {
                  "date_from": "2019-01-13",
                  "date_to": "2019-01-19",
                  "timestamp": 1547337600,
                  "missing_data": false,
                  "values": 72
                }
              ],
              "averages": []
            }
          ]
        }
      ]
    }
  ]
}

错误处理

请根据顶层 status_code 和任务级 status_code 判断请求是否成功：

20000：请求成功。
非 20000：请求或任务处理失败，应结合对应的 status_message 进行排查。
任务级错误可能只影响 tasks 数组中的部分任务，应通过 tasks_error 和每个任务的状态码分别处理。
完整错误码及状态信息请参考 /v3/appendix/errors。

实用场景

监测热度趋势：按日、周或月获取热度变化，识别季节性需求并安排 SEO发布计划。
比较多组热度：在同一地域和时间范围比较多个，确定优优化的主题与目标词。
定位地域搜索需求：使用 google_trends_map 获取不同国家、州或城市的热度分布，为本地 SEO 和区域投放制定依据。
挖掘主题与查询：使用 google_trends_topics_list 和 google_trends_queries_list 发现热门及增长中的词，扩展集群和长尾。
分析视频搜索趋势：将 type 设置为 youtube，评估视频主题热度变化，为视频选题、标题优化和排期提供数据支持。

实时获取 Google Trends Explore 数据 ​

请求信息 ​

计费说明 ​

请求参数 ​

响应结构 ​

顶层响应字段 ​

任务字段 ​

result 字段 ​

items 数据项 ​

google_trends_graph ​

google_trends_map ​

google_trends_topics_list ​

google_trends_queries_list ​

请求示例 ​

curl ​

Python ​

TypeScript ​

响应示例 ​

错误处理 ​

实用场景 ​