建议（旧版）

GET /v3/dataforseo_labs/locations_and_languages

本接口使用 POST 方法，请求路径为：

/v3/dataforseo_labs/keyword_suggestions/live

> 本页面描述的是建议接口的旧版数据结构。本平台继续容该版本；如需使用新版结构，请参考对应的 Google 建议接口文档。

接口说明

本接口根据指定的种子，返回该的长尾搜索词建议。

接口采用搜索算法，返回的可以在种子前、后或中间词语。短语中的词序可能与顺序不同。

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

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

每个建议通常：

最近一个月的搜索量；
过去 12 个月的月度搜索量趋势；
竞争度和每次点击费用（CPC）；
每日展示次数、点击次数和成本的最小值、最大值及平均值；
可选的搜索结果页（SERP）信息；
可选的种子数据。

**数据源：**数据库
**搜索算法：**查找指定种子、且可在前后或插词语的搜索词。

计费与请求限制

每次成功提交请求都会产生费用。参考价约 ¥0.0320 / 次，扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求使用 UTF-8 编码的 JSON 格式。请求体为 JSON 数组，每个数组代表一个任务。

平台限流以认证说明中的 30/60/120 次/分钟规则为准。通过 limit、offset、offset_token、filters 和 order_by 可以控制返回结果的数量、筛选条件及排序方式。

请求参数

参数	类型	说明
`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 数据搜索结果数量、 URL 和 SERP 特征。默认值：`false`。
`exact_match`	boolean	可选。是否按完整短语搜索。设为 `true` 时，返回结果完整种子短语，但短语前后仍可附加词语。默认值：`true`。
`filters`	array	可选。结果过滤条件。最多支持 8 个过滤条件，条件之间使用 `and` 或 `or` 连接。
`order_by`	array	可选。结果排序规则。可使用与 `filters` 相同的字段和运算符。支持 `asc` 升序和 `desc` 降序，最多设置 3 条排序规则。
`limit`	integer	可选。最多返回的数量。默认值：`100`，最大值：`1000`。
`offset`	integer	可选。结果偏移量。默认值：`0`。例如设置为 `10` 时，将跳过前 10 条结果。
`offset_token`	string	可选。后续分页令牌。该值会在响应中返回，用于获取同一任务的后续结果。当指定此参数时，除 `limit` 外，请求参数都不会参与任务处理。每个后续任务的 `offset_token` 都是唯一的。
`tag`	string	可选。自定义任务标识，最多 255 个字符。该值会原样返回在响应的 `data` 对象中，可用于任务和结果。

支持的过滤运算符

支持以下运算符：

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

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

过滤条件示例：

json

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

响应结构

接口返回 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	任务结果数组。

任务字段

字段	类型	说明
`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	请求中提交的任务参数。
`result`	array	建议结果。

`result` 字段

字段	类型	说明
`seed_keyword`	string	请求中的种子。
`seed_keyword_data`	array	种子数据。数组中的字段结构与 `items` 中的数据相同。当 `include_seed_keyword` 为 `true` 时返回。
`location_code`	integer / null	请求中的地区代码。没有对应数据时为 `null`。
`language_code`	string / null	请求中的语言代码。没有对应数据时为 `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 / 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	月均搜索量，即指定地区该在搜索引擎上的近似月搜索次数。
`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`。该指标综合分析 SERP 前 10 个页面的链接等因素计算。

`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	以 `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	过去一个月在 Bing 上的搜索次数。
`monthly_searches`	array	指定地区的月度 Bing 搜索量。

monthly_searches 数组字段：

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

`serp_info`

当未设置 include_serp_info: true，或数据库中没有对应的 SERP 数据时，该字段为 null。

字段	类型	说明
`check_url`	string	搜索结果页直接 URL，可用于人工核验结果。
`serp_item_types`	array	SERP 中出现的结果类型。
`se_results_count`	string	搜索结果总数。
`last_updated_time`	string	SERP 数据更新时间，UTC 格式。
`previous_updated_time`	string / null	上一次 SERP 数据更新时间。

支持的 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。

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

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_seed_keyword": true,
      "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]
        ]
      ],
      "order_by": [
        "keyword_info.search_volume,desc"
      ],
      "limit": 5
    }
  ]'

Python

python

import requests

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

payload = [
    {
        "keyword": "phone",
        "location_name": "United States",
        "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"))
    )

TypeScript

typescript

import axios from "axios";

const payload = [
  {
    keyword: "phone",
    location_code: 2840,
    include_serp_info: true,
    limit: 5,
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/dataforseo_labs/keyword_suggestions/live",
    payload,
    {
      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);
  });

响应示例

以下示例展示主要字段，返回结果可能更多和月度明细：

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": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "2.4779 sec.",
      "cost": 0.0105,
      "result_count": 1,
      "path": [
        "v3",
        "dataforseo_labs",
        "keyword_suggestions",
        "live"
      ],
      "data": {
        "api": "dataforseo_labs",
        "function": "keyword_suggestions",
        "keyword": "phone",
        "location_code": 2840,
        "include_serp_info": true,
        "limit": 5
      },
      "result": [
        {
          "seed_keyword": "phone",
          "location_code": 2840,
          "language_code": "en",
          "total_count": 5,
          "items_count": 5,
          "offset": 0,
          "offset_token": "eyJvZmZzZXQiOjV9",
          "items": [
            {
              "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,
                "categories": [],
                "monthly_searches": [
                  {
                    "year": 2021,
                    "month": 12,
                    "search_volume": 673000
                  }
                ]
              },
              "keyword_properties": {
                "core_keyword": null,
                "keyword_difficulty": 94
              },
              "impressions_info": {
                "last_updated_time": "2022-01-24 22:15:52 +00:00",
                "bid": 999,
                "match_type": "exact",
                "ad_position_min": 1.14,
                "ad_position_max": 1.0,
                "ad_position_average": 1.07,
                "cpc_min": 129.48,
                "cpc_max": 158.25,
                "cpc_average": 143.87,
                "daily_impressions_min": 5869.55,
                "daily_impressions_max": 7173.89,
                "daily_impressions_average": 6521.72,
                "daily_clicks_min": 430.02,
                "daily_clicks_max": 525.58,
                "daily_clicks_average": 477.8,
                "daily_cost_min": 61866.61,
                "daily_cost_max": 75614.75,
                "daily_cost_average": 68740.68
              },
              "bing_keyword_info": {
                "last_updated_time": "2022-02-01 03:08:39 +00:00",
                "search_volume": 43350,
                "monthly_searches": []
              },
              "serp_info": {
                "check_url": "https://www.google.com/search?q=find%20my%20phone",
                "serp_item_types": [
                  "organic",
                  "paid",
                  "people_also_ask",
                  "related_searches"
                ],
                "se_results_count": "13680000000",
                "last_updated_time": "2022-01-13 20:30:34 +00:00",
                "previous_updated_time": null
              }
            }
          ]
        }
      ]
    }
  ]
}

错误处理

应同时检查顶层和任务级别的 status_code：

20000：请求或任务执行成功；
非 20000：请求或任务执行失败，应结合对应的 status_message 处理；
tasks_error：表示任务数组中执行失败的任务数量。

分页时，请使用响应中的 offset_token 发起后续请求。指定 offset_token 后，除 limit 外的参数不会生效。

实用场景

扩展种子：根据核心词批量发现长尾搜索词，为规划和库建设提供候选词。
筛选高潜力：结合搜索量、难度和竞争度，优定位流量潜力较高且竞争适中的词。
评估广告投放价值：使用 CPC、广告排名、每日展示次数和点击次数估算的投放成本与流量收益。
分析搜索需求趋势：读取过去 12 个月的月度搜索量，识别季节性需求和发布时间窗口。
核验 SERP 机会：结合 SERP 类型、自然结果和精选摘要等信息，判断是否适合争取自然排名或特殊搜索结果位。

建议（旧版） ​

接口说明 ​

计费与请求限制 ​

请求参数 ​

支持的过滤运算符 ​

响应结构 ​

顶层字段 ​

任务字段 ​

result 字段 ​

items 字段 ​

keyword_info ​

keyword_properties ​

impressions_info ​

bing_keyword_info ​

serp_info ​

请求示例 ​

curl ​

Python ​

TypeScript ​

响应示例 ​

错误处理 ​

实用场景 ​