建议（旧版）

本接口使用 POST /v3/dataforseo_labs/keyword_ideas/live，用于根据指定种子所属的产品或服务类别，查找建议。

> 本页面描述的是旧版接口结构。新版接口文档请参考 /v3/dataforseo_labs/google/keyword_ideas/live/。本平台继续容旧版请求与响应格式。

接口最多支持提交 200 个种子，并返回、近月搜索量、过去 12 个月搜索趋势、CPC、竞争度，以及广告展示、点击和成本的最小值、最大值与平均值。

数据来源：按产品类别划分的数据库
搜索算法：基于性，查找与种子属于相同类别的搜索词
默认搜索模式：广泛匹，closely_variants 默认为 false 平台限流以认证说明中的 30/60/120 次/分钟规则为准
请求格式：UTF-8 编码的 JSON 数组
单次任务结果上限：默认 700 条，最多 1000 条

计费

每次请求均会产生费用。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数

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

参数	类型	填	说明
`keywords`	array	是	种子数组。使用 UTF-8 编码；最多 200 个；每个至少 3 个字符。会被转换为小写格式。
`location_name`	string	条件填	地理位置完整名称。当未指定 `location_code` 时填。至少指定 `location_name` 或 `location_code` 之一。
`location_code`	integer	条件填	地理位置唯一标识。当未指定 `location_name` 时填。至少指定 `location_name` 或 `location_code` 之一。
`closely_variants`	boolean	否	搜索模式。`true` 使用短语匹算法；`false` 使用广泛匹算法。默认值为 `false`。
`include_serp_info`	boolean	否	是否返回每个的 SERP 数据搜索结果数量、 URL 和 SERP 特征。默认值为 `false`。
`limit`	integer	否	返回结果数组中的最大数量。默认值为 `700`，最大值为 `1000`。
`offset`	integer	否	结果偏移量。默认值为 `0`。例如设置为 `10` 时，将跳过前 10 条结果并返回后续结果。
`offset_token`	string	否	用于分页获取后续结果的令牌。响应中会返回该字段。适用于单次任务需要获取 10,000 条结果、可能导致时的场景。
`filters`	array	否	结果过滤条件。最多同时使用 8 个过滤条件，条件之间使用 `and` 或 `or` 连接。
`order_by`	array	否	结果排序规则。最多设置 3 条排序规则。
`tag`	string	否	自定义任务标识，最多 255 个字符。该值会原样返回在响应的 `data` 对象中。

地理位置

可通过以下接口获取可用的地理位置及名称或代码：

GET /v3/dataforseo_labs/locations_and_languages

示例：

text

location_name: United Kingdom
location_code: 2840

`closely_variants` 搜索模式

值	说明
`true`	使用短语匹算法，返回更接近种子短语的结果
`false`	使用广泛匹算法，返回同类别的

过滤条件 `filters`

支持的比较运算符：

text

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

like 和 not_like 支持使用 % 匹任意长度的字符串空字符串。

过滤条件示例：

json

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

> relevance 只能用于排序，不能用于过滤。更多过滤语法请参考 /v3/dataforseo_labs/filters。

排序规则 `order_by`

排序规则使用字段名和排序方向组成：

text

["字段名,asc"]
["字段名,desc"]

asc：升序
desc：降序

默认按 relevance 排序，以优返回与种子最的结果。

relevance 是系统排序标识，不会出现在 result 数组中，也不能用于过滤。多个排序规则之间使用逗号分隔，单次请求最多设置 3 条排序规则。

分页参数 `offset_token`

当响应中返回 offset_token 时，可将复制到下一次请求中获取后续结果。

如果请求中指定了 offset_token：

除 limit 外，请求参数不会参与本次任务处理；
每个后续任务的 offset_token 都是唯一的；
应使用同一个初始任务返回的令牌继续分页。

响应结构

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

顶层响应字段

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	局状态码。完整错误码请参考 `/v3/appendix/errors`。
`status_message`	string	局状态信息。
`time`	string	请求执行耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务总数。
`tasks_error`	integer	`tasks` 数组中执行失败的任务数量。
`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	本次 POST 请求中提交的任务参数。
`result`	array	建议结果数组。

`result` 字段

字段	类型	说明
`seed_keywords`	array	请求中提交的种子。返回时会解码 `%##`；加号 `+` 会解码为空格。
`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`	object	基础数据。
`keyword_properties`	object	附加信息。
`impressions_info`	object	广告展示、点击和 CPC 数据。
`bing_keyword_info`	object	基于 Bing 广告数据的信息。
`serp_info`	object / null	SERP 数据。当 `include_serp_info` 为 `true` 且数据库中存在对应数据时返回。

`keyword_info`

字段	类型	说明
`last_updated_time`	string	数据更新时间，UTC 格式：`yyyy-mm-dd hh-mm-ss +00:00`。
`competition`	float	竞争度，取值范围为 `0–1`，基于广告数据计算。
`cpc`	float	历史平均每次点击费用。
`search_volume`	integer	近月平均搜索量，表示该在 Google 搜索中的估算搜索次数。
`categories`	array	产品和服务类别。
`monthly_searches`	array	过去 12 个月、面向指定地理位置的月度搜索量。

monthly_searches 中的：

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

`keyword_properties`

字段	类型	说明
`core_keyword`	string / null	相似分组中的核心。若为 `null`，表示数据库中没有符合条件的核心。
`keyword_difficulty`	integer	自然搜索结果前 10 名的难度，按 `0–100` 的对数刻度计算。数值越高，排名难度通常越大。

`impressions_info`

该对象中的展示量数据可作为搜索量的补参考。计算时使用 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	使用 `999` 出价时的最低 CPC 估值。该字段不是 CPC； CPC 请查看 `keyword_info.cpc`。
`cpc_max`	float	使用 `999` 出价时的最高 CPC 估值。该字段不是 CPC。
`cpc_average`	float	使用 `999` 出价时的平均 CPC 估值。该字段不是 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	最低每日广告成本估值。
`daily_cost_max`	float	最高每日广告成本估值。
`daily_cost_average`	float	平均每日广告成本估值。

`bing_keyword_info`

Bing 数据适用于有限的地理位置和语言组合。

字段	类型	说明
`last_updated_time`	string	Bing 数据更新时间，UTC 格式。
`search_volume`	integer / null	过去一个月该在 Bing 中的搜索量。
`monthly_searches`	array	指定位置下的 Bing 月度搜索量。

`serp_info`

当请求未设置 include_serp_info: true，数据库中没有该的 SERP 数据时，serp_info 返回 null。

字段	类型	说明
`check_url`	string	搜索引擎结果页的直接 URL，可用于核验结果。
`serp_item_types`	array	SERP 中出现的结果类型。
`se_results_count`	string / integer	该的搜索结果数量。
`last_updated_time`	string	SERP 数据更新时间，UTC 格式。

可能出现的 serp_item_types：

text

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

结果明细会针对以下类型返回：

text

organic、paid、featured_snippet、local_pack

请求示例

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,
      "filters": [
        [
          "impressions_info.ad_position_average",
          ">",
          0
        ],
        "and",
        [
          [
            "impressions_info.cpc_max",
            ">",
            0.5
          ],
          "or",
          [
            "impressions_info.daily_clicks_max",
            ">=",
            10
          ]
        ]
      ],
      "limit": 5
    }
  ]'

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],
      ],
    ],
    limit: 5,
  },
];

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

Python

python

import requests

url = "https://api.seermartech.cn/v3/dataforseo_labs/keyword_ideas/live"

payload = [
    {
        "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],
            ],
        ],
        "limit": 5,
    }
]

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"))
    )

PHP

php

<?php

$url = 'https://api.seermartech.cn/v3/dataforseo_labs/keyword_ideas/live';

$postData = [
    [
        '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],
            ],
        ],
        'limit' => 5,
    ],
];

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer smt_live_YOUR_KEY',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($postData, JSON_UNESCAPED_UNICODE),
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);

响应示例

以下示例展示主要响应结构。items 中的数据字段可能因位置、语言、数据库覆盖范围及是否启用 SERP 数据而有所不同。

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": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "4.6637 sec.",
      "cost": 0.0105,
      "result_count": 1,
      "path": [
        "v3",
        "dataforseo_labs",
        "keyword_ideas",
        "live"
      ],
      "data": {
        "api": "dataforseo_labs",
        "function": "keyword_ideas",
        "keywords": ["phone", "watch"],
        "location_code": 2840,
        "include_serp_info": true,
        "limit": 5
      },
      "result": [
        {
          "seed_keywords": ["phone", "watch"],
          "location_code": 2840,
          "language_code": "en",
          "total_count": 289465,
          "items_count": 5,
          "offset": 0,
          "offset_token": "NEXT_PAGE_TOKEN",
          "items": [
            {
              "keyword": "iphone watch features",
              "location_code": 2840,
              "language_code": "en",
              "keyword_info": {
                "last_updated_time": "2022-01-12 16:05:15 +00:00",
                "competition": 1,
                "cpc": 3.150623,
                "search_volume": 50,
                "categories": [],
                "monthly_searches": [
                  {
                    "year": 2021,
                    "month": 12,
                    "search_volume": 50
                  }
                ]
              },
              "keyword_properties": {
                "core_keyword": null,
                "keyword_difficulty": 70
              },
              "impressions_info": {
                "last_updated_time": "2022-01-17 00:11:53 +00:00",
                "bid": 999,
                "match_type": "exact",
                "ad_position_min": 1.11,
                "ad_position_max": 1,
                "ad_position_average": 1.06,
                "cpc_min": 12.52,
                "cpc_max": 15.3,
                "cpc_average": 13.91,
                "daily_impressions_min": null,
                "daily_impressions_max": null,
                "daily_impressions_average": null,
                "daily_clicks_min": null,
                "daily_clicks_max": null,
                "daily_clicks_average": null,
                "daily_cost_min": null,
                "daily_cost_max": null,
                "daily_cost_average": null
              },
              "bing_keyword_info": {
                "last_updated_time": "2022-01-23 00:25:17 +00:00",
                "search_volume": 10,
                "monthly_searches": []
              },
              "serp_info": {
                "check_url": "https://www.google.com/search?q=iphone%20watch%20features",
                "serp_item_types": ["organic", "people_also_ask"],
                "se_results_count": 84,
                "last_updated_time": "2022-01-11 16:02:49 +00:00"
              }
            }
          ]
        }
      ]
    }
  ]
}

错误处理

建议客户端同时检查：

HTTP 状态码；
顶层 status_code；
每个任务的 tasks[].status_code；
对应的 status_message。

完整状态码和错误信息请参考 /v3/appendix/errors。

实用场景

扩展种子：根据产品词或服务词批量发现同类别搜索需求，扩大 SEO和落地页覆盖范围。
筛选高潜力：结合 search_volume、keyword_difficulty 和 competition 过滤结果，优安排搜索需求较高且竞争可控的。
规划广告投放：利用 cpc、daily_clicks_average 和 daily_cost_average 估算的投放成本与流量潜力。
分析搜索趋势：读取 monthly_searches 的 12 个月数据，识别季节性需求并安排发布或营销活动。
评估 SERP 机会：启用 include_serp_info，分析自然结果、付费结果、精选摘要和本地结果等 SERP 特征，确定适合的排名策略。

建议（旧版） ​

计费 ​

请求参数 ​

地理位置 ​

closely_variants 搜索模式 ​

过滤条件 filters ​

排序规则 order_by ​

分页参数 offset_token ​

响应结构 ​

顶层响应字段 ​

任务字段 ​

result 字段 ​

items 字段 ​

keyword_info ​

keyword_properties ​

impressions_info ​

bing_keyword_info ​

serp_info ​

请求示例 ​

cURL ​

TypeScript ​

Python ​

PHP ​

响应示例 ​

错误处理 ​

实用场景 ​

建议（旧版）

计费

请求参数

地理位置

`closely_variants` 搜索模式

过滤条件 `filters`

排序规则 `order_by`

分页参数 `offset_token`

响应结构

顶层响应字段

任务字段

`result` 字段

`items` 字段

`keyword_info`

`keyword_properties`

`impressions_info`

`bing_keyword_info`

`serp_info`

请求示例

cURL

TypeScript

Python

PHP

响应示例

错误处理

实用场景