实时获取子区域度

POST /v3/keywords_data/dataforseo_trends/subregion_interests/live

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

/v3/keywords_data/dataforseo_trends/subregion_interests/live

用于获取指定在不同国家、地区或子区域中的相对热度数据。支持查询 Google Search、Google News 和 Google Shopping 对应的数据类型，可用于分析在各地区的受欢迎程度，并比较多个在指定地区及地区中的热度差异。

当请求中一个时，响应中的 interests_comparison 将为 null。每个请求最多提交 5 个，无论 keywords 数组中多少个，均按请求次数计费。

算法会综合网页、新闻文章或商品信息的度及热度，并结合匿名用户网络行为数据计算热度。

历史数据范围如下：

web 类型：最早支持 2004-01-01
news 和 ecommerce 类型：最早支持 2008-01-01

请求信息

http

POST https://api.seermartech.cn/v3/keywords_data/dataforseo_trends/subregion_interests/live
Content-Type: application/json
Authorization: Bearer smt_live_YOUR_KEY

计费与请求限制

按每个请求计费，与请求中的数量无。
实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。
单个 Live API 请求只能一个任务。
每个请求的请求体为 UTF-8 编码的 JSON 数组。平台限流以认证说明中的 30/60/120 次/分钟规则为准。
同时进行的请求数最多为 30 个。

请求参数

请求体是 JSON 数组，数组中的每个对象代表一个任务。

参数	类型	填	说明
`keywords`	array	是	要查询的列表，最多 5 个。建议使用符号、特殊字符、表符号或非标准字符。使用非拉丁字符时，将返回这些字符使用国家或地区的数据。
`location_name`	string	否	搜索引擎位置的完整名称。不传时返回结果。使用此参数时无需同时传 `location_code`。
`location_code`	integer	否	搜索引擎位置代码。不传时返回结果。使用此参数时无需同时传 `location_name`。
`type`	string	否	数据类型。可选值：`web`、`news`、`ecommerce`。默认值为 `web`。
`date_from`	string	否	时间范围起始日期，格式为 `yyyy-mm-dd`。不传时，默认使用前一年当天的日期。`web` 类型最早为 `2004-01-01`，类型最早为 `2008-01-01`。
`date_to`	string	否	时间范围结束日期，格式为 `yyyy-mm-dd`。不传时默认为当天日期。
`time_range`	string	否	预设时间范围。如果同时指定 `date_from` 或 `date_to`，该参数将被忽略。可选值：`past_4_hours`、`past_day`、`past_7_days`、`past_30_days`、`past_90_days`、`past_12_months`、`past_5_years`。
`tag`	string	否	自定义任务标识，最长 255 个字符。可用于识别任务并在响应中匹结果，提交的值会原样返回在响应的 `data` 对象中。

location_name 与 location_code 二选一即可。可通过以下接口获取可用位置及名称、代码和区域标识：

http

GET /v3/keywords_data/dataforseo_trends/locations

注意：返回数据对应于所指定位置所属的国家。
例如，指定 United Kingdom 或位置代码 2840 时，结果将该位置所属国家提供。

请求示例

json

[
  {
    "keywords": [
      "rugby",
      "cricket"
    ],
    "location_name": "United States",
    "type": "web",
    "date_from": "2023-01-01",
    "date_to": "2024-01-01",
    "tag": "sports-trend-analysis"
  }
]

响应结构

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

顶层字段

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	通用状态码。`20000` 表示请求成功。
`status_message`	string	通用状态说明。
`time`	string	请求执行耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务总数。
`tasks_error`	integer	返回错误的任务数量。
`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	请求对应的 URL 路径信息。
`data`	object	创建任务时提交的参数。
`result`	array	任务结果数组。

`result` 字段

字段	类型	说明
`keywords`	array	请求中提交的。
`type`	string	请求中的数据类型。
`location_code`	integer \| null	请求中的位置代码。无数据时可能为 `null`。
`language_code`	string \| null	语言代码。无数据时为 `null`。
`datetime`	string	结果接收时间，采用 UTC 格式：`yyyy-mm-dd hh-mm-ss +00:00`。
`items_count`	integer	`items` 数组中的结果数量。
`items`	array	含热度及数据。

`items` 字段

字段	类型	说明
`position`	integer	素排序位置，从 `1` 开始。
`type`	string	素类型，固定为 `subregion_interests`。
`keywords`	array	参与计算的。`interests` 和 `interests_comparison` 中的数据均基于此数组。
`interests`	array	每个在各子区域中的热度数据。
`interests_comparison`	object \| null	多个在各子区域中的对比结果。提交一个时为 `null`。
`absolute_items`	array	多个在所有地区范围的热度数据。

`interests`

字段	类型	说明
`keyword`	string	。
`values`	array	该在各国家或地区中的相对热度。

values 数组中的：

字段	类型	说明
`geo_id`	string \| null	地区标识，可用于匹请求中的位置参数，例如 `US-NY`。
`geo_name`	string	地区名称，例如 `Andorra`。
`value`	integer	指定时间范围，该在当前地区的相对热度。系统会将所有地区中该的最高热度设为 `100`，地区按比例表示。<br><br>`100` 表示该在所有地区中的最高热度；`50` 表示热度约为最高值的一半；`0` 表示数据不足。

`interests_comparison`

当请求多个时，该对象用于比较这些在每个地区的热度。

字段	类型	说明
`items`	array	各地区的热度对比结果。数组中的值以该地区热度最高的为 `100`。

items 中的字段：

字段	类型	说明
`geo_id`	string \| null	地区标识，例如 `US-NY`。
`geo_name`	string	地区名称。
`values`	array	当前地区各的热度值。数组第一个值对应请求中 `keywords` 的第一个，依此类推。

计算规则：

在每个地区确定所有请求中的最高热度，并设为 100。
50 表示该热度约为该地区最高的一半。
0 表示数据不足。

`absolute_items`

该对象用于比较多个在所有地区范围的整体热度。

字段	类型	说明
`geo_id`	string \| null	地区标识，例如 `US-NY`。
`geo_name`	string	地区名称。
`values`	array	各相对于所有地区、所有最高热度的数值。数组第一个值对应第一个，依此类推。

计算规则：

在所有和所有地区中确定最高热度，并设为 100。
50 表示该在当前地区的热度约为局最高值的一半。
0 表示数据不足。

响应示例

以下示例展示了型响应结构，地区列表已做截取：

json

{
  "version": "0.1.20231117",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.9749 sec.",
  "cost": 0.0144,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.6210 sec.",
      "cost": 0.0144,
      "result_count": 1,
      "path": [
        "v3",
        "keywords_data",
        "dataforseo_trends",
        "subregion_interests",
        "live"
      ],
      "data": {
        "api": "keywords_data",
        "function": "subregion_interests",
        "se": "dataforseo_trends",
        "keywords": [
          "rugby",
          "cricket"
        ],
        "date_from": "2023-01-01",
        "date_to": "2024-01-01",
        "type": "web",
        "location_name": "United States"
      },
      "result": [
        {
          "keywords": [
            "rugby",
            "cricket"
          ],
          "type": "trends",
          "location_code": 2840,
          "language_code": null,
          "datetime": "2024-03-12 11:53:18 +00:00",
          "items_count": 1,
          "items": [
            {
              "position": 1,
              "type": "subregion_interests",
              "keywords": [
                "rugby",
                "cricket"
              ],
              "interests": [
                {
                  "keyword": "rugby",
                  "values": [
                    {
                      "geo_id": null,
                      "geo_name": "Alaska",
                      "value": 34
                    },
                    {
                      "geo_id": null,
                      "geo_name": "California",
                      "value": 72
                    }
                  ]
                },
                {
                  "keyword": "cricket",
                  "values": [
                    {
                      "geo_id": null,
                      "geo_name": "Alaska",
                      "value": 61
                    },
                    {
                      "geo_id": null,
                      "geo_name": "California",
                      "value": 100
                    }
                  ]
                }
              ],
              "interests_comparison": {
                "items": [
                  {
                    "geo_id": null,
                    "geo_name": "Alaska",
                    "values": [
                      56,
                      100
                    ]
                  },
                  {
                    "geo_id": null,
                    "geo_name": "California",
                    "values": [
                      72,
                      100
                    ]
                  }
                ]
              },
              "absolute_items": [
                {
                  "geo_id": null,
                  "geo_name": "Alaska",
                  "values": [
                    34,
                    61
                  ]
                },
                {
                  "geo_id": null,
                  "geo_name": "California",
                  "values": [
                    72,
                    100
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

调用示例

cURL

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/keywords_data/dataforseo_trends/subregion_interests/live" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "location_name": "United States",
      "date_from": "2023-01-01",
      "date_to": "2024-01-01",
      "type": "web",
      "keywords": [
        "rugby",
        "cricket"
      ]
    }
  ]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/keywords_data/dataforseo_trends/subregion_interests/live"

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

# POST 请求体是 JSON 数组
payload = [
    {
        "location_name": "United States",
        "date_from": "2023-01-01",
        "date_to": "2024-01-01",
        "type": "web",
        "keywords": [
            "rugby",
            "cricket",
        ],
    }
]

response = requests.post(url, headers=headers, json=payload, timeout=60)
response.raise_for_status()

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: "2023-01-01",
    date_to: "2024-01-01",
    type: "web",
    keywords: ["rugby", "cricket"],
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/keywords_data/dataforseo_trends/subregion_interests/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);
  });

错误处理

请根据以下字段判断请求和任务是否成功：

顶层 status_code
任务级 tasks[].status_code
status_message 或 tasks[].status_message

当 tasks_error 大于 0 时，表示至少有一个任务返回错误。建议在业务系统中实现异常重试、参数校验、时处理和错误记录机制。

实用场景

识别区域热度差异：分析同一在不同省州、城市或子区域的热度，确定 SEO和投放资源的优市场。
比较地域偏好：对比最多 5 个在每个地区的相对热度，筛选适合当地标题、落地页和广告文案的。
发现本地化机会：定位某个热度显著较高的地区，为区域专题页、门店页和本地服务页制定计划。
评估趋势渠道表现：分别查询 web、news 和 ecommerce 类型，判断更适合搜索、新闻传播还是电商选品。
构建区域报表：定期保存 interests、interests_comparison 和 absolute_items 数据，跟踪各地区热度变化并支持市场复盘。

实时获取子区域度 ​

请求信息 ​

计费与请求限制 ​

请求参数 ​

请求示例 ​

响应结构 ​

顶层字段 ​

任务字段 ​

result 字段 ​

items 字段 ​

interests ​

interests_comparison ​

absolute_items ​

响应示例 ​

调用示例 ​

cURL ​

Python ​

TypeScript ​

错误处理 ​

实用场景 ​