keywords_data/dataforseo_trends/demography/live

POST /v3/keywords_data/dataforseo_trends/demography/live

接口说明

POST /v3/keywords_data/dataforseo_trends/demography/live

本接口用于查询指定在不同年龄段和性别群体中的热度分布。数据支持以下趋势类型：

web：Google 搜索趋势
news：Google 新闻趋势
ecommerce：Google Shopping 趋势

每个都会在结果数组中返回对应的人口统计数据。单个请求最多可提交 5 个。系统按请求次数计费，与 keywords 数组中的数量无。

历史数据范围：

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

请求限制与计费

每个 Live API 请求只能 1 个任务。平台限流以认证说明中的 30/60/120 次/分钟规则为准。
同时进行的请求数最多为 30。
每次请求单独计费，即使请求中多个。
参考价约 ¥0.0144 / 次。
实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

所有 POST 请求均须使用 UTF-8 编码的 JSON 格式，请求体是 JSON 数组。

请求参数

请求体示例：

json

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

任务参数

参数	类型	填	说明
`keywords`	array	是	要查询的列表，最多 5 个。建议使用符号、特殊字符、Unicode 表等。使用非拉丁字符时，返回结果将基于该字符使用国家或地区的数据。
`location_name`	string	否	搜索引擎位置的完整名称，例如 `United States`、`United Kingdom`。不填写时返回结果。填写此参数后无需填写 `location_code`。
`location_code`	integer	否	搜索引擎位置编码，例如 `2840`。不填写时返回结果。填写此参数后无需填写 `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`，则以明确指定的日期为准，忽略此参数。
`tag`	string	否	自定义任务标识，最长 255 个字符。该值会原样返回在响应的 `data` 对象中，可用于请求与结果。

`time_range` 可选值

text

past_4_hours
past_day
past_7_days
past_30_days
past_90_days
past_12_months
past_5_years

位置查询

可通过以下接口获取可用的位置名称和位置编码：

text

GET https://api.seermartech.cn/v3/keywords_data/dataforseo_trends/locations

注意：返回数据对应于指定位置所属的国家或地区。

响应字段

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

顶层响应字段

字段	类型	说明
`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` 数组中的数量。
`path`	array	请求路径信息。
`data`	object	创建任务时提交的参数。
`result`	array	查询结果数组。

`result` 字段

字段	类型	说明
`keywords`	array	请求中的列表。
`type`	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` 字段

字段	类型	说明
`position`	integer	素序号，从 `1` 开始。
`type`	string	素类型，固定为 `demography`。
`keywords`	array	。`demography` 和 `demography_comparison` 中的数据均基于此数组中的计算。
`demography`	object	每个的人口统计热度分布，年龄和性别维度。
`demography_comparison`	object	多个之间的人口统计热度对比。只提交一个时，该字段为 `null`。

`demography` 字段

年龄分布：`demography.age`

字段	类型	说明
`keyword`	string	当前人口统计数据对应的。
`values`	array	年龄段及对应热度值。
`values[].type`	string	年龄段，可选值：`18-24`、`25-34`、`35-44`、`45-54`、`55-64`。
`values[].value`	integer	在该年龄段的相对热度值。

热度值计算方式：

以该在所有年龄段中的最高热度为 100。
年龄段的热度按相对比例表示。
100 表示该在对应维度中的最高热度。
0 表示该的数据不足。

性别分布：`demography.gender`

字段	类型	说明
`keyword`	string	当前人口统计数据对应的。
`values`	array	性别类别及对应热度值。
`values[].type`	string	性别类别，可选值：`female`、`male`。
`values[].value`	integer	在该性别类别中的相对热度值。

热度值以该在所有性别类别中的最高值为 100，值按相对比例表示。0 表示数据不足。

`demography_comparison` 字段

当请求中多个时，接口会返回之间的相对热度对比；当只提交一个时，该字段为 null。

按年龄对比：`demography_comparison.age`

可用字段：

text

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

json

{
  "18-24": [62, 38],
  "25-34": [55, 45]
}

上述结果表示：

第一个数值对应 keywords[0]
第二个数值对应 keywords[1]

计算方式为：统计指定年龄段所有的总热度，并将各按比例换算为总和为 100 的相对值。

按性别对比：`demography_comparison.gender`

支持以下字段：

female
male

每个字段对应一个数组，数组顺序与请求中的 keywords 顺序一致。数值表示指定性别类别各的相对热度，最高值为 100，0 表示数据不足。

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 '[
    {
      "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/demography/live"

payload = [
    {
        "location_name": "United States",
        "date_from": "2023-01-01",
        "date_to": "2024-01-01",
        "type": "web",
        "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(
        "请求失败，状态码：%s，消息：%s"
        % (result.get("status_code"), result.get("status_message"))
    )

TypeScript 示例

typescript

import axios from "axios";

const url =
  "https://api.seermartech.cn/v3/keywords_data/dataforseo_trends/demography/live";

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

axios
  .post(url, requestData, {
    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);
  });

响应示例

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": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.6000 sec.",
      "cost": 0.002,
      "result_count": 1,
      "path": [
        "v3",
        "keywords_data",
        "dataforseo_trends",
        "demography",
        "live"
      ],
      "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": [
        {
          "keywords": [
            "rugby",
            "cricket"
          ],
          "type": "trends",
          "location_code": 2840,
          "language_code": null,
          "datetime": "2024-03-12 12:00:40 +00:00",
          "items_count": 1,
          "items": [
            {
              "position": 1,
              "type": "demography",
              "keywords": [
                "rugby",
                "cricket"
              ],
              "demography": {
                "age": [
                  {
                    "keyword": "rugby",
                    "values": [
                      {
                        "type": "18-24",
                        "value": 82
                      },
                      {
                        "type": "25-34",
                        "value": 100
                      },
                      {
                        "type": "35-44",
                        "value": 74
                      },
                      {
                        "type": "45-54",
                        "value": 51
                      },
                      {
                        "type": "55-64",
                        "value": 28
                      }
                    ]
                  },
                  {
                    "keyword": "cricket",
                    "values": [
                      {
                        "type": "18-24",
                        "value": 65
                      },
                      {
                        "type": "25-34",
                        "value": 79
                      },
                      {
                        "type": "35-44",
                        "value": 100
                      },
                      {
                        "type": "45-54",
                        "value": 83
                      },
                      {
                        "type": "55-64",
                        "value": 60
                      }
                    ]
                  }
                ],
                "gender": [
                  {
                    "keyword": "rugby",
                    "values": [
                      {
                        "type": "female",
                        "value": 43
                      },
                      {
                        "type": "male",
                        "value": 100
                      }
                    ]
                  },
                  {
                    "keyword": "cricket",
                    "values": [
                      {
                        "type": "female",
                        "value": 52
                      },
                      {
                        "type": "male",
                        "value": 100
                      }
                    ]
                  }
                ]
              },
              "demography_comparison": {
                "age": {
                  "18-24": [56, 44],
                  "25-34": [61, 39],
                  "35-44": [43, 57],
                  "45-54": [38, 62],
                  "55-64": [32, 68]
                },
                "gender": {
                  "female": [45, 55],
                  "male": [58, 42]
                }
              }
            }
          ]
        }
      ]
    }
  ]
}

错误处理

请根据顶层 status_code、任务级 status_code 和对应的 status_message 判断请求是否成功。建议在客户端实现以下处理机制：

检查 HTTP 状态码和 API 响应状态码。
检查 tasks_error 是否大于 0。
对任务级错误进行重试或记录。
对 location_name 与 location_code 同时传、日期出可用范围、数量限制等参数错误进行校验。

完整错误码请参考：

text

/v3/appendix/errors

实用场景

识别目标用户年龄层：分析在不同年龄段的热度差异，为 SEO选题、广告定向和落地页文案提供依据。
比较竞品受众结构：对比多个品牌或产品在年龄和性别维度上的热度，发现竞品覆盖不足的人群。
优化季节性策略：结合 date_from、date_to 或预设时间范围，判断不同人群在特定时期的搜索变化。
细分电商用户画像：使用 ecommerce 类型分析购物的人口统计分布，商品页面优化和人群运营。
评估新闻传播受众：使用 news 类型比较新闻主题在不同性别和年龄群体中的度，支持媒体选题和舆分析。

keywords_data/dataforseo_trends/demography/live ​

接口说明 ​

请求限制与计费 ​

请求参数 ​

任务参数 ​

time_range 可选值 ​

位置查询 ​

响应字段 ​

顶层响应字段 ​

tasks 数组字段 ​

result 字段 ​

items 字段 ​

demography 字段 ​

年龄分布：demography.age ​

性别分布：demography.gender ​

demography_comparison 字段 ​

按年龄对比：demography_comparison.age ​

按性别对比：demography_comparison.gender ​

cURL 示例 ​

Python 示例 ​

TypeScript 示例 ​

响应示例 ​

错误处理 ​

实用场景 ​

keywords_data/dataforseo_trends/demography/live

接口说明

请求限制与计费

请求参数

任务参数

`time_range` 可选值

位置查询

响应字段

顶层响应字段

`tasks` 数组字段

`result` 字段

`items` 字段

`demography` 字段

年龄分布：`demography.age`

性别分布：`demography.gender`

`demography_comparison` 字段

按年龄对比：`demography_comparison.age`

按性别对比：`demography_comparison.gender`

cURL 示例

Python 示例

TypeScript 示例

响应示例

错误处理

实用场景