创意（旧版）实时接口

接口说明

/v3/dataforseo_labs/keyword_ideas/live 用于根据一组种子，返回与产品或服务类别的创意。

该接口会从本平台数据库中，基于类目性算法，筛选与属于同一类别的搜索词。单次请求最多可提交 200 个种子，并返回对应的建议。

每个返回结果通常以下数据：

最近一个月搜索量
过去 12 个月搜索趋势
当前 CPC（平均点击成本）
竞争度
每日展示、点击、CPC 的最小值 / 最大值 / 平均值
可选 SERP 信息

数据源： 本平台数据库（按产品类别分段） 搜索算法： 基于性的同类目发现

容性说明

该接口为旧版结构（Legacy）。自 2022-03-19 起，平台 API 已更新了本平台 Labs 的请求与响应结构，但仍持续容本旧版接口。如果你需要新版结构，可参考对应的新版本文档路径。

示例说明

不额外指定排序参数，且 "closely_variants": false 时：

-种子：

keyword research
content marketing
可能返回的创意：
free adword tools
find longtail keywords
how to do keywords research
seo keyword research template

请求信息

请求方式： POST请求地址：

https://api.seermartech.cn/v3/dataforseo_labs/keyword_ideas/live

认证方式：

http

Authorization: Bearer smt_live_YOUR_KEY
Content-Type: application/json

请求体格式：

所有 POST 数据使用 UTF-8 编码的 JSON，且请求体为 JSON 数组：

json

[
 {
 "keywords": ["phone", "watch"],
 "location_code": 2840,
 "limit": 5
 }
]

计费与限流

本接口按请求计费。 扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

原文未提供固定单价，因此无法直接换算参考人民币价格。

接口频率上限：

最高 2000 次 API 调用 / 分钟

你可以通过 limit、offset、offset_token、filters、order_by 等参数控制结果数量、分页、筛选与排序。

请求参数

顶层任务对象字段

字段名	类型	说明
`keywords`	array	填。种子数组。最多 200 个；每个最少 3 个字符；使用 UTF-8 编码；系统会自动转换为小写。
`location_name`	string	地区完整名称。当未提供 `location_code` 时填。`location_name` 与 `location_code` 二选一填。可通过 `/v3/dataforseo_labs/locations_and_languages` 获取可用地区列表。示例：`United Kingdom`
`location_code`	integer	地区唯一标识。当未提供 `location_name` 时填。`location_name` 与 `location_code` 二选一填。可通过 `/v3/dataforseo_labs/locations_and_languages` 获取可用地区编码。示例：`2840`
`closely_variants`	boolean	可选。搜索模式。设为 `true` 时，基于短语匹（phrase-match）算法；设为 `false` 时，基于广泛匹（broad-match）算法。默认值：`false`
`include_serp_info`	boolean	可选。是否返回每个的 SERP 数据。设为 `true` 后，响应中会 `serp_info`，搜索结果数量、 URL 和 SERP 特征。默认值：`false`
`limit`	integer	可选。返回结果中最多的数量。默认值：`700`；最大值：`1000`
`offset`	integer	可选。结果偏移量。默认值：`0`。例如传 `10` 时，会跳过前 10 条结果，从第 11 条开始返回。
`offset_token`	string	可选。用于获取后续分页结果的偏移令牌。该值会在响应中返回。若单次想获取 10,000 条结果，建议使用该参数时。注意：如果请求中提供了 `offset_token`，除 `limit` 外它参数都会被忽略。
`filters`	array	可选。结果筛选条件数组。最多支持 8 个过滤条件，条件之间可使用 `and` / `or`。支持操作符：`<`, `<=`, `>`, `>=`, `=`, `<>`, `in`, `not_in`, `like`, `not_like`。`like` 和 `not_like` 支持 `%` 通符。不能按 `relevance` 过滤。
`order_by`	array	可选。结果排序规则。可使用与 `filters` 相同的字段名进行排序。支持排序方式：`asc`（升序）、`desc`（降序）。单次请求最多设置 3 条排序规则。默认按 `relevance` 排序。注意：`relevance` 是性分值，只能用于排序，不能用于过滤，且不会出现在 `result` 数组中。
`tag`	string	可选。自定义任务标识，最大 255 个字符。可用于将请求与响应结果对应起来；该值会原样出现在响应的 `data` 对象中。

filters 用法说明

filters 是嵌套数组结构，用于表达筛选逻辑。可组合多个条件，并通过 and / or 构建复杂查询。

支持的操作符

<
<=
>
>=
=
<>
in
not_in
like
not_like

说明

like / not_like 支持 % 作为通符，表示任意长度字符串
最多支持 8 个过滤条件
不支持对 relevance 字段进行过滤

过滤示例

json

[
 [
 ["impressions_info.ad_position_average", ">", 0],
 "and",
 [
 ["impressions_info.cpc_max", ">", 0.5],
 "or",
 ["impressions_info.daily_clicks_max", ">=", 10]
 ]
 ]
]

order_by 用法说明

order_by 用于结果排序，可基于与 filters 相同的字段进行排序。

排序规则

asc：升序
desc：降序

说明

默认排序规则为 relevance
推荐保留默认排序，以获取最的创意
relevance 为系统字段，只能排序，不能过滤
单次请求最多 3 个排序规则

排序示例

json

[
 "keyword_info.search_volume,desc",
 "keyword_info.cpc,desc"
]

响应结构

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

顶层响应字段

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

tasks 数组中的字段

字段名	类型	说明
`id`	string	任务唯一标识，UUID 格式
`status_code`	integer	任务状态码，范围通常在 `10000-60000`
`status_message`	string	任务状态信息
`time`	string	任务执行耗时
`cost`	float	任务成本，单位 USD
`result_count`	integer	`result` 数组数量
`path`	array	URL 路径
`data`	object	回显请求中提交的参数
`result`	array	结果数组

result 数组中的字段

字段名	类型	说明
`seed_keywords`	array	POST 数组中提交的种子。返回时会解码 `%##`，`+` 会被还原为空格。
`location_code`	integer	请求中的地区编码
`language_code`	string	请求中的语言编码
`items_count`	integer	`items` 数组中的结果数量
`offset`	integer	当前偏移量
`offset_token`	string	用于获取后续结果的分页令牌，每次后续任务对应唯一值
`items`	array	创意及数据

items 字段说明

基础字段

字段名	类型	说明
`keyword`	string	返回的创意
`location_code`	integer	请求中的地区编码
`language_code`	string	请求中的语言编码

keyword_info 对象

字段名	类型	说明
`last_updated_time`	string	数据更新时间，UTC 格式：`yyyy-mm-dd hh-mm-ss +00:00`
`competition`	float	竞争度，基于 Google Ads 数据，范围 `0` 到 `1`
`cpc`	float	历史平均点击成本，单位 USD
`search_volume`	integer	平均月搜索量，表示该在 google.com 上的大致月搜索次数
`categories`	array	产品或服务类别
`monthly_searches`	array	最近 12 个月按月搜索量数据，面向指定地理位置

monthly_searches 子字段

字段名	类型	说明
`year`	integer	年份
`month`	integer	月份
`search_volume`	integer	当月平均搜索量

keyword_properties 对象

字段名	类型	说明
`core_keyword`	string	同组中的核心词。如果为 `null`，表示数据库中没有符合该聚类条件的。
`keyword_difficulty`	integer	自然排名难度，范围 `0-100`。用于表示自然搜索前 10 的难易程度，基于 SERP 前 10 页面的链接特征等因素计算。

impressions_info 对象

这是返回创意的展示预估数据，daily_impressions 相比传统搜索量，能提供更精细的流量参考。系统使用 999 出价以尽可能削弱账户差异因素。

字段名	类型	说明
`last_updated_time`	string	展示数据更新时间，UTC 格式
`bid`	integer	最大 CPC 出价。固定使用 `999` 用于获取更高展示估算值。
`match_type`	string	匹类型，可选值：`exact`、`broad`、`phrase`
`ad_position_min`	float	广告最低位次
`ad_position_max`	float	广告最高位次
`ad_position_average`	float	广告平均位次
`cpc_min`	float	在 `bid=999` 条件下的最小 CPC 估值，单位 USD。不是 CPC， CPC 请看 `keyword_info.cpc`
`cpc_max`	float	在 `bid=999` 条件下的最大 CPC 估值，单位 USD。不是 CPC
`cpc_average`	float	在 `bid=999` 条件下的平均 CPC 估值，单位 USD。不是 CPC
`daily_impressions_min`	float	日展示量最小值，在 `bid=999` 条件下估算
`daily_impressions_max`	float	日展示量最大值，在 `bid=999` 条件下估算
`daily_impressions_average`	float	日展示量平均值，在 `bid=999` 条件下估算
`daily_clicks_min`	float	日点击量最小值
`daily_clicks_max`	float	日点击量最大值
`daily_clicks_average`	float	日点击量平均值
`daily_cost_min`	float	日花费最小值，单位 USD
`daily_cost_max`	float	日花费最大值，单位 USD
`daily_cost_average`	float	日花费平均值，单位 USD

bing_keyword_info 对象

基于 Bing Ads 的数据。 注意： 部分地区和语言支持该数据。

字段名	类型	说明
`last_updated_time`	string	Bing 数据最后更新时间，UTC 格式
`search_volume`	integer	Bing 最近一个月搜索量
`monthly_searches`	array	指定地区下的 Bing 月度搜索数据

serp_info 对象

如果请求中未设置 include_serp_info=true，数据库中没有该的 SERP 数据，则此字段为 null。

字段名	类型	说明
`check_url`	string	直接访问搜索结果页的 URL，可用于校验结果
`serp_item_types`	array	SERP 中出现的结果类型。可能值：`answer_box`、`app`、`carousel`、`multi_carousel`、`featured_snippet`、`google_flights`、`google_reviews`、`images`、`jobs`、`knowledge_graph`、`local_pack`、`map`、`organic`、`paid`、`people_also_ask`、`related_searches`、`people_also_search`、`shopping`、`top_stories`、`twitter`、`video`、`events`、`mention_carousel`、`recipes`、`top_sights`、`scholarly_articles`、`popular_products`、`podcasts`、`questions_and_answers`、`find_results_on`、`stocks_box`
`se_results_count`	string	搜索结果总数
`last_updated_time`	string	SERP 数据更新时间，UTC 格式

说明：返回通常覆盖 organic、paid、featured_snippet、local_pack 这几类。

错误处理

响应中的 status_code 和 status_message 用于表示整体请求状态；tasks[].status_code 和 tasks[].status_message 用于表示单个任务状态。

建议在接时至少处理以下几类：

顶层请求成功，但部分任务失败
参数缺失或参数格式错误 -出频率限制
使用 offset_token 分页时参数冲突
某些无 SERP / Bing 数据，字段返回 null

完整错误码体系请参考 /v3/appendix/errors。

请求示例

cURL

bash

curl --location --request POST "https://api.seermartech.cn/v3/dataforseo_labs/keyword_ideas/live" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "keywords": ["phone", "watch"],
 "location_code": 2840,
 "include_serp_info": true,
 "filters": [
 ["impressions_info.ad_position_average", ">", 0],
 "and",
 [
 ["impressions_info.cpc_max", ">", 0.5],
 "or",
 ["impressions_info.daily_clicks_max", ">=", 10]
 ]
 ],
 "limit": 5
 }
]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/dataforseo_labs/keyword_ideas/live"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

data = [
 {
 "keywords": ["phone", "watch"],
 "location_name": "United States",
 "filters": [
 ["impressions_info.ad_position_average", ">", 0],
 "and",
 [
 ["impressions_info.cpc_max", ">", 0.5],
 "or",
 ["impressions_info.daily_clicks_max", ">=", 10]
 ]
 ]
 }
]

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

if result.get("status_code") == 20000:
 print(result)
else:
 print(f"error. Code: {result.get('status_code')} Message: {result.get('status_message')}")

TypeScript

typescript

import axios from "axios";

const postArray = [
 {
 keywords: ["phone", "watch"],
 location_code: 2840,
 filters: [
 ["impressions_info.ad_position_average", ">", 0],
 "and",
 [
 ["impressions_info.cpc_max", ">", 0.5],
 "or",
 ["impressions_info.daily_clicks_max", ">=", 10]
 ]
 ]
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/dataforseo_labs/keyword_ideas/live",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 },
 data: postArray
})
 .then((response) => {
 // 返回结果
 console.log(response.data);
 })
 .catch((error) => {
 console.log(error);
 });

响应示例

json

{
 "version": "0.1.20220131",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "4.6637 sec.",
 "cost": 0.0105,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "dataforseo_labs",
 "function": "keyword_ideas",
 "keywords": ["phone", "watch"],
 "location_code": 2840,
 "include_serp_info": true,
 "filters": [
 ["impressions_info.ad_position_average", ">", 0],
 "and",
 [
 ["impressions_info.cpc_max", ">", 0.5],
 "or",
 ["impressions_info.daily_clicks_max", ">=", 10]
 ]
 ],
 "limit": 5
 },
 "result": [
 {
 "location_code": 2840,
 "language_code": null,
 "total_count": 289465,
 "items_count": 5,
 "offset": 0,
 "offset_token": "eyJDdXJyZW50T2Zmc2V0Ijo1LCJSZXF1ZXN0RGF0YSI6...",
 "items": [
 {
 "keyword": "iphone watch price",
 "location_code": 2840,
 "language_code": "en",
 "keyword_properties": {
 "core_keyword": null,
 "keyword_difficulty": 32
 },
 "impressions_info": {
 "last_updated_time": "2021-12-10 13:42:09 +00:00",
 "bid": 999,
 "match_type": "exact",
 "ad_position_min": 1.14,
 "ad_position_max": 1,
 "ad_position_average": 1.07,
 "cpc_min": 18.8,
 "cpc_max": 22.97,
 "cpc_average": 20.89,
 "daily_impressions_min": 80.98,
 "daily_impressions_max": 98.98,
 "daily_impressions_average": 89.98,
 "daily_clicks_min": 8.38,
 "daily_clicks_max": 10.24,
 "daily_clicks_average": 9.31,
 "daily_cost_min": 175,
 "daily_cost_max": 213.89,
 "daily_cost_average": 194.45
 },
 "bing_keyword_info": {
 "last_updated_time": "2021-12-20 19:57:49 +00:00",
 "search_volume": 110,
 "monthly_searches": []
 },
 "serp_info": {
 "check_url": "https://www.google.com/search?q=iphone%20watch%20price&num=100&hl=en&gl=US&gws_rd=cr&ie=UTF-8&oe=UTF-8&uule=w+CAIQIFISCQs2MuSEtepUEUK33kOSuTsc",
 "serp_item_types": ["organic", "paid"],
 "se_results_count": 99,
 "keyword_difficulty": 32,
 "last_updated_time": "2021-12-19 13:35:12 +00:00",
 "previous_updated_time": null
 }
 },
 {
 "keyword": "apple health watch price",
 "location_code": 2840,
 "language_code": "en"
 },
 {
 "keyword": "alcatel smart watches",
 "location_code": 2840,
 "language_code": "en"
 },
 {
 "keyword": "iphone watch features",
 "location_code": 2840,
 "language_code": "en"
 },
 {
 "keyword": "galaxy watch att",
 "location_code": 2840,
 "language_code": "en"
 }
 ]
 }
 ]
 }
 ]
}

使用建议

想获取最的创意时，建议保持默认 relevance 排序
需要分析真实搜索结果环境时，可开启 include_serp_info
如果需要大批量翻页抓取，优使用 offset_token，深分页时
如果你更心广告流量潜力，可重点 impressions_info
如果要筛出高商业价值，可联合使用 search_volume、cpc、competition 和 keyword_difficulty

实用场景

扩展选题：核心业务词，批量发现同类目长尾，帮助团队补专题页、博客页和问答页选题。
筛选高商业价值词：结合 cpc、competition、daily_clicks_average 等字段，识别更有投放价值或转化潜力的。
构建分层库：基于种子词批量生成词，再按搜索量、难度、SERP 特征进行分层，用于 SEO 词库建设。
评估地区市场差异：针对不同 location_code 重复请求，比较同类在不同市场的热度与竞争，支持出海 SEO 或本地化投放。
识别 SERP 机会位：开启 include_serp_info 后分析是否存在 featured_snippet、local_pack、paid 等结果类型，为结构和页面优化提供方向。

创意（旧版）实时接口 ​

接口说明 ​

容性说明 ​

示例说明 ​

请求信息 ​

计费与限流 ​

请求参数 ​

顶层任务对象字段 ​

filters 用法说明 ​

支持的操作符 ​

说明 ​

过滤示例 ​

order_by 用法说明 ​

排序规则 ​

说明 ​

排序示例 ​

响应结构 ​

顶层响应字段 ​

tasks 数组中的字段 ​

result 数组中的字段 ​

items 字段说明 ​

基础字段 ​

keyword_info 对象 ​

monthly_searches 子字段 ​

keyword_properties 对象 ​

impressions_info 对象 ​

bing_keyword_info 对象 ​

serp_info 对象 ​

错误处理 ​

请求示例 ​

cURL ​

Python ​

创意（旧版）实时接口

接口说明

容性说明

示例说明

请求信息

计费与限流

请求参数

顶层任务对象字段

filters 用法说明

支持的操作符

说明

过滤示例

order_by 用法说明

排序规则

说明

排序示例

响应结构

顶层响应字段

tasks 数组中的字段

result 数组中的字段

items 字段说明

基础字段

keyword_info 对象

monthly_searches 子字段

keyword_properties 对象

impressions_info 对象

bing_keyword_info 对象

serp_info 对象

错误处理

请求示例

cURL

Python