数据 / Trends / 人群画像（Live）

接口说明

该接口用于获取指定在不同年龄段与性别中的热度分布，数据来源于平台 Trends 数据。可用于分析以下搜索类型中的趋势：

web：Google Search
news：Google News
ecommerce：Google Shopping

接口会对 keywords 数组中的每个分别返回人群画像数据；如果一次请求提交多个，还会返回这些之间的人群对比结果。

单个 keywords 数组最多可传 5 个
系统按请求次数计费，与数组中数量无
web 类型历史数据最早可到 2004-01-01
类型历史数据最早可到 2008-01-01

请求方式

POST https://api.seermartech.cn/v3/keywords_data/dataforseo_trends/demography/live

计费说明

本接口按请求计费。参考价约 ¥0.0320 / 次。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

调用限制

每分钟最多 2000 次 API 调用
最大并发请求数 30
POST 请求体为 UTF-8 编码的 JSON
请求体格式为 JSON 数组：[{ ... }]

计算逻辑说明

本接口基于与网页、新闻或商品列表之间的，以及这些本身的受欢迎程度，结合匿名化用户网络行为数据，生成热度的人群分布结果。

返回值中的热度并非原始搜索量，而是标准化后的相对热度值。因此更适合做：

人群结构分析
受众偏好对比
多在不同人群中的相对强弱判断

请求参数

任务参数说明

字段名	类型	说明
`keywords`	array	填。数组，最多 5 个。建议特殊符号和非常规字符（如 UTF 特殊字符、emoji）。若使用非拉丁字符，将返回这些字符使用地区对应的数据。
`location_name`	string	搜索引擎地域名称，可选。不传则返回结果。若传此字段，则无需再传 `location_code`。例如：`United Kingdom`。可通过 `/v3/keywords_data/dataforseo_trends/locations` 获取可用地域列表。注意：结果按该地域所属国家返回。
`location_code`	integer	搜索引擎地域代码，可选。不传则返回结果。若传此字段，则无需再传 `location_name`。例如：`2840`。可通过 `/v3/keywords_data/dataforseo_trends/locations` 获取可用地域列表。注意：结果按该代码所属国家返回。
`type`	string	趋势数据类型，可选。默认 `web`。可选值：`web`、`news`、`ecommerce`
`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_4_hours`、`past_day`、`past_7_days`、`past_30_days`、`past_90_days`、`past_12_months`、`past_5_years`
`tag`	string	自定义任务标识，可选，最长 255 个字符。可用于请求与响应结果的对应，返回时会出现在响应的 `data` 对象中。

响应结构

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

顶层字段

字段名	类型	说明
`version`	string	当前 API 版本
`status_code`	integer	通用状态码，完整列表见 `/v3/appendix/errors`
`status_message`	string	通用状态信息，完整列表见 `/v3/appendix/errors`
`time`	string	执行耗时，单位秒
`cost`	float	本次请求总费用，单位 USD
`tasks_count`	integer	`tasks` 数组中的任务数量
`tasks_error`	integer	返回错误的任务数量
`tasks`	array	任务结果数组

`tasks` 数组字段

字段名	类型	说明
`id`	string	任务唯一标识，UUID 格式
`status_code`	integer	任务状态码，范围通常为 `10000-60000`，完整列表见 `/v3/appendix/errors`
`status_message`	string	任务状态信息
`time`	string	任务执行耗时，单位秒
`cost`	float	当前任务费用，单位 USD
`result_count`	integer	`result` 数组中的结果数
`path`	array	URL 路径
`data`	object	与请求中提交的参数一致
`result`	array	结果数组

`result` 数组字段

字段名	类型	说明
`keywords`	array	请求中提交的
`type`	array/string	请求中的趋势类型
`location_code`	integer	请求中的地域代码；无数据时为 `null`
`language_code`	string	请求中的语言代码；无数据时为 `null`
`datetime`	string	结果生成时间，UTC 格式：`yyyy-mm-dd hh-mm-ss +00:00`
`items_count`	integer	`items` 数组中的结果数量
`items`	array	热度及数据

`items`素说明

该接口返回的核心类型为 demography。

字段名	类型	说明
`position`	integer	素位置序号，如 `1`、`2`、`3`
`type`	string	素类型，固定为 `demography`
`keywords`	array	列表，`demography` 与 `demography_comparison` 的数据均基于该数组
`demography`	object	每个的人群画像数据，按年龄与性别拆分
`demography_comparison`	object	多之间的人群对比结果；如果只传 1 个，则该字段为 `null`

`demography` 字段说明

`demography.age`

按年龄段返回每个的热度分布。

字段名	类型	说明
`keyword`	string	当前
`values`	array	年龄段与热度值组成的数组

values 中每个：

字段名	类型	说明
`type`	string	年龄段，可选值：`18-24`、`25-34`、`35-44`、`45-54`、`55-64`
`value`	integer	该年龄段的热度值

计算方式：

系统会找出该在所有年龄段中的最高热度值，并将该最高值标准化为 100；年龄段按相对比例换算。

100：该在该年龄段达到最高热度
0：数据不足，无法形成有效热度

`demography.gender`

按性别返回每个的热度分布。

字段名	类型	说明
`keyword`	string	当前
`values`	array	性别与热度值组成的数组

values 中每个：

字段名	类型	说明
`type`	string	性别类别，可选值：`female`、`male`
`value`	integer	该性别人群中的热度值

计算方式：

系统会找出该在所有性别人群中的最高热度值，并将最高值记为 100；性别人群按相对比例计算。

100：该在该性别人群达到最高热度
0：数据不足

`demography_comparison` 字段说明

该对象用于比较多个在不同年龄段、不同性别人群中的相对热度。

如果请求中只传了一个，该字段返回 null。

`demography_comparison.age`

按年龄段对比多个。

字段名为动态年龄段键名，可：

18-24
25-34
35-44
45-54
55-64

每个年龄段对应一个数组，数组顺序与请求中的 keywords 顺序一致。

例如：

第 1 个值对应 keywords[0]
第 2 个值对应 keywords[1]
以此类推

计算方式：

系统会统计某一年龄段下所有指定的总热度，再将各的热度换算为该年龄段中的相对占比。

值越高，说明该在该年龄段相对更受欢迎
100 表示该在该分组中最强
0 表示数据不足

`demography_comparison.gender`

按性别对比多个。

可字段：

female
male

每个字段对应一个数组，数组顺序与请求中的 keywords 顺序一致，用于表示各在该性别人群中的相对热度。

计算逻辑与年龄对比一致：

系统会以某一性别人群中的所有目标总热度为基准，计算各的相对占比。

请求示例

cURL

bash

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

Python

python

import requests

url = "https://api.seermartech.cn/v3/keywords_data/dataforseo_trends/demography/live"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
data = [
 {
 "location_name": "United States",
 "date_from": "2023-01-01",
 "date_to": "2024-01-01",
 "type": "web",
 "keywords": ["rugby", "cricket"]
 }
]

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

TypeScript

typescript

import axios from "axios";

const postData = [
 {
 location_name: "United States",
 date_from: "2023-01-01",
 date_to: "2024-01-01",
 type: "web",
 keywords: ["rugby", "cricket"]
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/keywords_data/dataforseo_trends/demography/live",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 },
 data: postData
})
 .then((response) => {
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error);
 });

响应示例

json

{
 "version": "0.1.20231117",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.6673 sec.",
 "cost": 0.002,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "keywords_data",
 "function": "demography",
 "se": "dataforseo_trends",
 "keywords": ["rugby", "cricket"],
 "date_from": "2023-01-01",
 "date_to": "2024-01-01",
 "type": "web",
 "location_name": "United States"
 },
 "result": [
 {
 "type": "trends",
 "location_code": 2840,
 "language_code": null,
 "datetime": "2024-03-12 12:00:40 +00:00",
 "items_count": 1,
 "items": [
 {
 "type": "demography",
 "demography": {
 "age": [
 {
 "keyword": "rugby",
 "values": [
 { "type": "18-24", "value": 72 },
 { "type": "25-34", "value": 100 },
 { "type": "35-44", "value": 81 },
 { "type": "45-54", "value": 56 },
 { "type": "55-64", "value": 39 }
 ]
 },
 {
 "keyword": "cricket",
 "values": [
 { "type": "18-24", "value": 68 },
 { "type": "25-34", "value": 100 },
 { "type": "35-44", "value": 88 },
 { "type": "45-54", "value": 61 },
 { "type": "55-64", "value": 40 }
 ]
 }
 ],
 "gender": [
 {
 "keyword": "rugby",
 "values": [
 { "type": "female", "value": 54 },
 { "type": "male", "value": 100 }
 ]
 },
 {
 "keyword": "cricket",
 "values": [
 { "type": "female", "value": 49 },
 { "type": "male", "value": 100 }
 ]
 }
 ]
 },
 "demography_comparison": {
 "age": {
 "18-24": [51, 49],
 "25-34": [50, 50],
 "35-44": [48, 52],
 "45-54": [47, 53],
 "55-64": [49, 51]
 },
 "gender": {
 "female": [52, 48],
 "male": [50, 50]
 }
 }
 }
 ]
 }
 ]
 }
 ]
}

状态码与错误处理

建议同时处理两层状态：

顶层状态：status_code / status_message
任务级状态：tasks[].status_code / tasks[].status_message

常见判断方式：

20000：请求成功
状态码：表示参数错误、权限问题、频率限或平台处理异常等

完整错误码说明请参考：/v3/appendix/errors

在生产环境中，建议至少处理以下异常场景：

鉴权失败
请求参数缺失或格式错误 -出频率限制
地域或日期范围无效
返回数据为空或部分字段为 null

使用建议

如果明确分析国家市场，优传 location_name 或 location_code
若需要稳定对比长期趋势，建议固定 date_from 与 date_to
比较多个时，尽量保证语义接近，否则人群差异解释价值会下降
当 value 为 0 时，通常表示该分组数据不足，不建议直接用于结论判断
若传 1 个，不会返回有效的 demography_comparison

实用场景

识别受众年龄层：分析目标在不同年龄段中的热度差异，用于优化选题、广告创意与落地页表达。
比较人群偏好：同时提交多个候选，判断它们分别更受哪些年龄段或性别人群欢迎，提升投放与 SEO 选词准确性。
校准地区化策略：结合 location_name 分析不同国家市场中的受众结构差异，为本地化和跨境推广提供依据。
验证产品受众画像：将品牌词、品类词、竞品词放在同一请求中对比，判断搜索受众是否与既有用户画像一致。
渠道投放分组：将趋势人群分布结果用于 SEO、营销、信息流广告的受众细分，提升人群定向与素材匹效果。

数据 / Trends / 人群画像（Live） ​

接口说明 ​

计算逻辑说明 ​

请求参数 ​

任务参数说明 ​

响应结构 ​

顶层字段 ​

tasks 数组字段 ​

result 数组字段 ​

items素说明 ​

demography 字段说明 ​

demography.age ​

demography.gender ​

demography_comparison 字段说明 ​

demography_comparison.age ​

demography_comparison.gender ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应示例 ​

状态码与错误处理 ​

使用建议 ​

实用场景 ​

数据 / Trends / 人群画像（Live）

接口说明

计算逻辑说明

请求参数

任务参数说明

响应结构

顶层字段

`tasks` 数组字段

`result` 数组字段

`items`素说明

`demography` 字段说明

`demography.age`

`demography.gender`

`demography_comparison` 字段说明

`demography_comparison.age`

`demography_comparison.gender`

请求示例

cURL

Python

TypeScript

响应示例

状态码与错误处理

使用建议

实用场景