建议（旧版）

POST /v3/dataforseo_labs/keyword_suggestions/live

接口概述

/v3/dataforseo_labs/keyword_suggestions/live 用于基于指定种子，返回该的搜索词建议。

这是一个旧版接口。虽然平台 API 已在 2022-03-19 更新了本平台 Labs 的请求与响应结构，但本接口对应的旧版能力仍然可用并保持容。如需新版结构，可参考对应的新版本接口文档。

该接口基于检索算法工作：系统会查找所有指定种子的搜索词，并在前、后或中间插单词。返回结果中的词序不一定与提交时一致，因此适合获取大量长尾。

例如，种子为 keyword research，可能返回：

google research keyword
how to do keyword research
keyword competitor research
how to do keyword research for content marketing

除本身外，接口还会返回：

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

数据源： 本平台数据库 检索算法： 基于种子的匹，支持前后或中间附加词

请求方式

POST https://api.seermartech.cn/v3/dataforseo_labs/keyword_suggestions/live

计费说明

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

根据示例响应，单次请求参考价约为：

参考价约 ¥0.1680 / 次

调用限制

请求体为 JSON（UTF-8）
使用 POST 方法提交
请求体格式为 JSON 数组：[{ ... }]
最高支持 2000 次 API 调用/分钟
支持结果数量控制、过滤、排序与翻页

请求参数

字段名	类型	说明
`keyword`	string	填。种子。使用 UTF-8 编码；长度至少 3 个字符；系统会自动转为小写。
`location_name`	string	可选。地区完整名称。使用该字段时可不传 `location_code`。可通过 `/v3/dataforseo_labs/locations_and_languages` 获取可用地区列表。不传则返回所有可用地区的数据。示例：`United Kingdom`
`location_code`	integer	可选。地区编码。使用该字段时可不传 `location_name`。可通过 `/v3/dataforseo_labs/locations_and_languages` 获取可用地区编码。不传则返回所有可用地区的数据。示例：`2840`
`include_seed_keyword`	boolean	可选。是否在响应中种子本身的数据。设为 `true` 时，响应中的 `seed_keyword_data` 会返回该的详细数据。默认值：`false`
`include_serp_info`	boolean	可选。是否返回每个对应的 SERP 信息。设为 `true` 时，响应中会返回 `serp_info`，结果数、 URL、SERP 特征等。默认值：`false`
`exact_match`	boolean	可选。是否按精确短语检索。设为 `true` 时，返回的你指定的完整短语，但前后可带词。默认值：`true`
`filters`	array	可选。结果过滤条件数组。最多支持 8 个过滤条件。条件之间可使用逻辑运算符 `and`、`or`。支持操作符：`<`, `<=`, `>`, `>=`, `=`, `<>`, `in`, `not_in`, `like`, `not_like`。`like` 和 `not_like` 支持 `%` 通任意长度字符串。
`order_by`	array	可选。结果排序规则。可使用与 `filters` 相同的字段路径。排序方式支持：`asc` 升序、`desc` 降序。单次请求最多支持 3 条排序规则。多条规则使用逗号分隔。
`limit`	integer	可选。返回最大数量。默认值：`100`；最大值：`1000`
`offset`	integer	可选。结果偏移量。默认值：`0`。例如传 `10`，则跳过前 10 条结果，返回之后的数据。
`offset_token`	string	可选。后续翻页请求的偏移令牌。适用于单次获取 10,000 条结果时，时。该值由上一次响应返回。注意：请求中一旦指定 `offset_token`，除 `limit` 外它参数都会被忽略。
`tag`	string	可选。自定义任务标识，最大长度 255 字符。可用于请求结果对账与业务追踪。响应中的 `data` 对象会原样返回该值。

filters 用法说明

filters 支持多层嵌套条件，常用于筛选搜索量、CPC、竞争度、难度、展示/点击预估等指标。

支持的逻辑与比较操作：

逻辑：and、or
比较：<, <=, >, >=, =, <>
集合：in, not_in
模糊：like, not_like

可用于过滤的型字段：

keyword
keyword_info.search_volume
keyword_info.cpc
keyword_info.competition
keyword_properties.keyword_difficulty
impressions_info.ad_position_average
impressions_info.cpc_max
impressions_info.daily_clicks_max

示例：

json

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

order_by 用法说明

order_by 用于结果排序，支持升序和降序。

示例：

json

[
 "keyword_info.search_volume,desc",
 "keyword_properties.keyword_difficulty,asc"
]

说明：

最多支持 3 条排序规则
多条规则按顺序依次生效

响应结构

接口返回 JSON 对象 tasks 数组。

顶层字段

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

tasks 数组字段

字段名	类型	说明
`id`	string	任务 ID，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_keyword`	string	请求中提交的种子
`seed_keyword_data`	array	种子本身的数据。在 `include_seed_keyword=true` 时返回，字段结构与 `items` 中单项一致
`location_code`	integer	请求中的地区编码；若无数据则为 `null`
`language_code`	string	请求中的语言编码；若无数据则为 `null`
`total_count`	integer	数据库中与请求的总结果数
`items_count`	integer	当前 `items` 中返回的结果数量
`offset`	integer	当前偏移量
`offset_token`	string	下一页结果令牌
`items`	array	及数据

items 数组字段

字段名	类型	说明
`keyword`	string	建议
`location_code`	integer	地区编码
`language_code`	string	语言编码
`keyword_info`	object	基础数据
`keyword_properties`	object	附加属性
`impressions_info`	object	曝与点击预估数据
`bing_keyword_info`	object	基于 Bing Ads 的数据
`serp_info`	object	SERP 信息；在 `include_serp_info=true` 且数据库存在数据时返回

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	平均月搜索量
`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 字段说明

impressions_info 提供广告与点击表现的估算数据，可作为搜索量的更细粒度补。系统使用 999 的出价来降低账户差异因素带来的影响。

字段名	类型	说明
`last_updated_time`	string	曝数据更新时间，UTC 格式
`bid`	integer	最大 CPC 出价，固定用于估算，通常为 `999`
`match` / `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_max`	float	在 `bid=999` 前提下的最高 CPC 估算值，单位 USD；不是 CPC
`cpc_average`	float	在 `bid=999` 前提下的平均 CPC 估算值，单位 USD；不是 CPC
`daily_impressions_min`	float	最低日量估值
`daily_impressions_max`	float	最高日量估值
`daily_impressions_average`	float	平均日量估值
`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

注意： CPC 请使用 keyword_info.cpc；impressions_info.cpc_* 为估算值，不代表真实成交点击成本。

bing_keyword_info 字段说明

注意：Bing 数据在部分地区和语言下可用。

字段名	类型	说明
`last_updated_time`	string	Bing 数据更新时间，UTC 格式
`search_volume`	integer	Bing 最近一个月搜索量
`monthly_searches`	array	Bing 月度搜索量趋势

monthly_searches 子字段：

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

serp_info 字段说明

如果请求中未将 include_serp_info 设置为 true，或数据库中不存在该的 SERP 数据，则 serp_info 为 null。

字段名	类型	说明
`check_url`	string	对应搜索引擎结果页的直接链接，可用于人工核验
`serp_item_types`	array	SERP 中出现的结果类型
`se_results_count`	string	搜索结果总数
`last_updated_time`	string	SERP 数据更新时间，UTC 格式

可能出现的 serp_item_types括：

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

，可返回详细结果的数据类型通常：

organic
paid
featured_snippet
local_pack

请求示例

cURL

bash

curl --location --request POST "https://api.seermartech.cn/v3/dataforseo_labs/keyword_suggestions/live" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "keyword": "phone",
 "location_code": 2840,
 "include_serp_info": true,
 "filters": [
 [
 "impressions_info.ad_position_average",
 ">",
 1
 ],
 "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_suggestions/live"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

payload = [
 {
 "keyword": "phone",
 "location_name": "United States",
 "filters": [
 ["impressions_info.ad_position_average", ">", 1],
 "and",
 [
 ["impressions_info.cpc_max", "<", 0.5],
 "or",
 ["impressions_info.daily_clicks_max", ">=", 10]
 ]
 ]
 }
]

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

TypeScript

typescript

import axios from "axios";

const payload = [
 {
 keyword: "phone",
 location_code: 2840
 }
];

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

响应示例

json

{
 "version": "0.1.20220131",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "2.4779 sec.",
 "cost": 0.0105,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "dataforseo_labs",
 "function": "keyword_suggestions",
 "keyword": "phone",
 "location_code": 2840,
 "include_serp_info": true,
 "filters": [
 [
 "impressions_info.ad_position_average",
 ">",
 1
 ],
 "and",
 [
 [
 "impressions_info.cpc_max",
 "<",
 0.5
 ],
 "or",
 [
 "impressions_info.daily_clicks_max",
 ">=",
 10
 ]
 ]
 ],
 "limit": 5
 },
 "result": [
 {
 "items": [
 {
 "keyword": "irs phone number",
 "keyword_properties": {
 "core_keyword": null,
 "keyword_difficulty": 62
 },
 "impressions_info": {
 "last_updated_time": "2022-01-16 19:44:25 +00:00",
 "bid": 999,
 "match_type": "exact",
 "ad_position_min": 1.14,
 "ad_position_max": 1,
 "ad_position_average": 1.07,
 "cpc_min": 13.1,
 "cpc_max": 16.01,
 "cpc_average": 14.56,
 "daily_impressions_min": 982.44,
 "daily_impressions_max": 1200.76,
 "daily_impressions_average": 1091.6,
 "daily_clicks_min": 58.7,
 "daily_clicks_max": 71.75,
 "daily_clicks_average": 65.23,
 "daily_cost_min": 854.52,
 "daily_cost_max": 1044.41,
 "daily_cost_average": 949.47
 },
 "bing_keyword_info": {
 "last_updated_time": "2022-02-01 07:00:07 +00:00",
 "search_volume": 15420
 },
 "serp_info": {
 "check_url": "https://www.google.com/search?q=irs%20phone%20number&num=100&hl=en&gl=US&gws_rd=cr&ie=UTF-8&oe=UTF-8&uule=w+CAIQIFISCQs2MuSEtepUEUK33kOSuTsc",
 "se_results_count": 208000000,
 "keyword_difficulty": 62,
 "last_updated_time": "2022-01-13 20:30:08 +00:00",
 "previous_updated_time": null
 }
 },
 {
 "keyword": "find my phone",
 "location_code": 2840,
 "language_code": "en",
 "keyword_info": {
 "last_updated_time": "2022-01-16 23:26:18 +00:00",
 "competition": 0.14583037220500414,
 "cpc": 1.136297,
 "search_volume": 673000
 },
 "keyword_properties": {
 "core_keyword": null,
 "keyword_difficulty": 94
 }
 }
 ]
 }
 ]
 }
 ]
}

状态码与错误处理

顶层 status_code 表示整个请求是否成功
tasks[].status_code 表示单个任务的执行状态
建议业务系统同时处理：
HTTP 状态码
顶层 status_code
任务级 status_code

常见成功状态：

20000：成功

完整错误码请参考 /v3/appendix/errors。建议对时、参数错误、额限制、空结果等做好异常处理。

使用建议

做大批量拉取时优使用 offset_token

当结果集很大时，使用翻页令牌比单次请求大量结果更稳妥。

需要核验 SERP 结构时开启 include_serp_info

可查看 SERP 特征、结果数量及核验链接，但会增加返回数据量。

广告投放评估优结合 impressions_info

该对象可补传统搜索量数据，适合投放预估与商机筛选。

** SEO 筛选重点 search_volume 与 keyword_difficulty**

用于平衡流量潜力与排名难度。

实用场景

挖掘长尾：基于种子词批量扩展该词的搜索词，快速搭建选题库与专题页池。
筛选低竞争高潜力词：结合 search_volume、competition、keyword_difficulty 过滤，提升 SEO 投产出比。
评估商业化价值：利用 cpc、daily_clicks_*、daily_cost_* 判断的广告价值， SEM 投放和预算规划。
分析 SERP 版式机会：开启 include_serp_info 查看是否存在精选摘要、本地、付费位等特征，判断自然流量切空间。
构建分页采集流程：通过 offset_token 持续拉取大结果集，适合库建设、竞品词挖掘和行业语义覆盖分析。

建议（旧版） ​

接口概述 ​

请求方式 ​

计费说明 ​

调用限制 ​

请求参数 ​

filters 用法说明 ​

order_by 用法说明 ​

响应结构 ​

顶层字段 ​

tasks 数组字段 ​

result 数组字段 ​

items 数组字段 ​

keyword_info 字段说明 ​

keyword_properties 字段说明 ​

impressions_info 字段说明 ​

bing_keyword_info 字段说明 ​

serp_info 字段说明 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应示例 ​

状态码与错误处理 ​

使用建议 ​

实用场景 ​

建议（旧版）

接口概述

请求方式

计费说明

调用限制

请求参数

filters 用法说明

order_by 用法说明

响应结构

顶层字段

tasks 数组字段

result 数组字段

items 数组字段

keyword_info 字段说明

keyword_properties 字段说明

impressions_info 字段说明

bing_keyword_info 字段说明

serp_info 字段说明

请求示例

cURL

Python

TypeScript

响应示例

状态码与错误处理

使用建议

实用场景