（旧版）

GET /v3/dataforseo_labs/locations_and_languages

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

/v3/dataforseo_labs/related_keywords/live

> 说明：本页面描述的是旧版 Related Keywords 接口。接口请求和响应结构已于 2022 年 3 月 19 日更新，但旧版接口仍可继续使用。新版本请参考 /v3/dataforseo_labs/google/related_keywords/live/。

接口用于获取搜索结果页（SERP）中“搜索”模块出现的。通过设置搜索深度，最多可获取约 4,680 个建议。

每个可能以下数据：

产品或服务类别
最近一个月的搜索量
过去 12 个月的搜索量趋势
当前每次点击费用（CPC）
竞争度
每日展示次数、点击次数和 CPC 的最小值、最大值及平均值
可选的 SERP 信息
数据源：本平台 SERP 数据库
搜索算法：从指定种子的 SERP“搜索”模块开始，按深度优方式递归查找查询词

搜索深度示例

当 depth 设置为 1，种子为 keyword research 时，可能返回以下：

free keyword research
keyword research tools
best free keyword research tool
keyword research tips
seo keyword research tool
keyword research step by step
how to do keyword research 2019
keyword research google ads

计费与请求限制

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

所有 POST 请求使用 UTF-8 编码的 JSON 格式，请求体为任务数组。单次请求可提交多个任务，每分钟最多提交 2,000 次 API 调用。

请求参数

请求体中的每个对象代表一个任务。

参数	类型	说明
`keyword`	string	种子。填，使用 UTF-8 编码，长度至少为 3 个字符。会被转换为小写格式。
`location_name`	string	地理位置完整名称。当未指定 `location_code` 时填。与 `location_code` 二选一。可通过 `/v3/dataforseo_labs/locations_and_languages` 获取可用位置列表。例如：`United Kingdom`。
`location_code`	integer	地理位置代码。当未指定 `location_name` 时填。与 `location_name` 二选一。例如：`2840`。
`language_name`	string	语言完整名称。当未指定 `language_code` 时填。与 `language_code` 二选一。例如：`English`。
`language_code`	string	语言代码。当未指定 `language_name` 时填。与 `language_name` 二选一。例如：`en`。
`depth`	integer	搜索深度。可选，默认值为 `1`，取值范围为 `0` 至 `4`。不同深度的预计最大数量：`0`：种子本身；`1`：约 8 个；`2`：约 72 个；`3`：约 584 个；`4`：约 4,680 个。
`include_seed_keyword`	boolean	是否返回种子的数据。设为 `true` 时，种子数据会出现在响应的 `seed_keyword_data` 数组中。默认值为 `false`。
`include_serp_info`	boolean	是否返回每个的 SERP 数据。设为 `true` 时，响应会 `serp_info`，搜索结果数量、 URL 和 SERP 特征。默认值为 `false`。
`replace_with_core_keyword`	boolean	是否使用核心返回数据。设为 `true` 时，`serp_info` 和 `related_keywords` 返回所属分组的主数据；设为 `false` 时，返回指定的数据（如数据库中存在）。默认值为 `false`。
`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 个。
`tag`	string	用户自定义任务标识，最长 255 个字符。可用于请求和响应，提交的值会出现在响应的 `data` 对象中。

`filters` 示例

json

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

`order_by` 示例

json

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

请求示例

cURL

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/dataforseo_labs/related_keywords/live" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "keyword": "phone",
      "location_name": "United States",
      "language_name": "English",
      "depth": 1,
      "include_serp_info": true,
      "filters": [
        [
          "keyword_data.impressions_info.ad_position_average",
          ">",
          1
        ],
        "and",
        [
          [
            "keyword_data.impressions_info.cpc_max",
            "<",
            0.5
          ],
          "or",
          [
            "keyword_data.impressions_info.daily_clicks_max",
            ">=",
            10
          ]
        ]
      ],
      "limit": 5
    }
  ]'

Python

python

import requests

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

payload = [
    {
        "keyword": "phone",
        "location_name": "United States",
        "language_name": "English",
        "depth": 1,
        "include_serp_info": True,
        "filters": [
            [
                "keyword_data.impressions_info.ad_position_average",
                ">",
                1
            ],
            "and",
            [
                [
                    "keyword_data.impressions_info.cpc_max",
                    "<",
                    0.5
                ],
                "or",
                [
                    "keyword_data.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(
        "请求失败：{} {}".format(
            result.get("status_code"),
            result.get("status_message")
        )
    )

TypeScript

typescript

import axios from "axios";

const payload = [
  {
    keyword: "phone",
    location_name: "United States",
    language_name: "English",
    depth: 1,
    include_serp_info: true,
    filters: [
      [
        "keyword_data.impressions_info.ad_position_average",
        ">",
        1,
      ],
      "and",
      [
        [
          "keyword_data.impressions_info.cpc_max",
          "<",
          0.5,
        ],
        "or",
        [
          "keyword_data.impressions_info.daily_clicks_max",
          ">=",
          10,
        ],
      ],
    ],
    limit: 5,
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/dataforseo_labs/related_keywords/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 数据，顶层 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	本次 POST 请求中提交的任务参数。
`result`	array	任务结果数组。

`result` 字段

字段	类型	说明
`seed_keyword`	string	请求中的种子。
`seed_keyword_data`	array	种子数据。当 `include_seed_keyword` 为 `true` 时返回。数组中的字段结构与 `keyword_data` 相同。
`location_code`	integer	请求中的地理位置代码。
`language_code`	string	请求中的语言代码。
`total_count`	integer	数据库中与请求条件匹的结果总数。
`items_count`	integer	`items` 数组中返回的结果数量。
`items`	array	及数据。

`keyword_data` 字段

字段	类型	说明
`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` 且数据库中存在对应数据时返回，否则为 `null`。

`keyword_info`

字段	类型	说明
`last_updated_time`	string	数据更新时间，UTC 格式：`yyyy-mm-dd hh-mm-ss +00:00`。例如：`2019-11-15 12:57:46 +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	难度，取值范围为 `0` 至 `100`，用于表示自然搜索结果前 10 名的难度。数值越高，排名难度通常越大。

`impressions_info`

展示数据使用最高出价 999 进行估算，以尽可能减少账户因素对展示次数计算的影响。daily_impressions 可作为搜索量数据的补参考。

字段	类型	说明
`last_updated_time`	string	展示数据更新时间，UTC 格式。
`bid`	integer	最高每次点击出价。接口通常使用 `999` 作为估算出价。
`match` / `match_type`	string	匹类型，可取 `exact`、`broad`、`phrase`。不同数据版本中可能显示为 `match` 或 `match_type`。
`ad_position_min`	float	最低广告位置。
`ad_position_max`	float	最高广告位置。
`ad_position_average`	float	平均广告位置。
`cpc_min`	float	估算最低 CPC。该值基于出价 `999`，不代表 CPC； CPC 请查看 `keyword_info.cpc`。
`cpc_max`	float	估算最高 CPC。该值基于出价 `999`，不代表 CPC。
`cpc_average`	float	估算平均 CPC。该值基于出价 `999`，不代表 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`

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

可能出现的 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。

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

organic
paid
featured_snippet
local_pack

结果级字段

字段	类型	说明
`depth`	integer	当前相对于种子的搜索深度。
`related_keywords`	array \| null	与当前的搜索查询列表。

响应示例

json

{
  "version": "0.1.20220131",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.1277 sec.",
  "cost": 0.0103,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.1200 sec.",
      "cost": 0.0103,
      "result_count": 1,
      "path": [
        "v3",
        "dataforseo_labs",
        "related_keywords",
        "live"
      ],
      "data": {
        "api": "dataforseo_labs",
        "function": "related_keywords",
        "keyword": "phone",
        "language_name": "English",
        "location_code": 2840,
        "include_serp_info": true,
        "limit": 5
      },
      "result": [
        {
          "seed_keyword": "phone",
          "location_code": 2840,
          "language_code": "en",
          "total_count": 3,
          "items_count": 3,
          "items": [
            {
              "keyword_data": {
                "keyword": "phone number",
                "location_code": 2840,
                "language_code": "en",
                "keyword_info": {
                  "last_updated_time": "2022-01-12 04:30:50 +00:00",
                  "competition": 0.169876,
                  "cpc": 1.171982,
                  "search_volume": 368000,
                  "categories": [],
                  "monthly_searches": [
                    {
                      "year": 2021,
                      "month": 12,
                      "search_volume": 368000
                    }
                  ]
                },
                "keyword_properties": {
                  "core_keyword": null,
                  "keyword_difficulty": 100
                },
                "impressions_info": {
                  "last_updated_time": "2022-01-15 23:06:18 +00:00",
                  "bid": 999,
                  "match_type": "exact",
                  "ad_position_min": 1.17,
                  "ad_position_max": 1.00,
                  "ad_position_average": 1.08,
                  "cpc_min": 136.18,
                  "cpc_max": 166.45,
                  "cpc_average": 151.31,
                  "daily_impressions_min": 2422.98,
                  "daily_impressions_max": 2961.42,
                  "daily_impressions_average": 2692.20,
                  "daily_clicks_min": 166.36,
                  "daily_clicks_max": 203.33,
                  "daily_clicks_average": 184.85,
                  "daily_cost_min": 25172.88,
                  "daily_cost_max": 30766.86,
                  "daily_cost_average": 27969.87
                },
                "bing_keyword_info": {
                  "last_updated_time": "2022-01-21 21:53:49 +00:00",
                  "search_volume": 20090,
                  "monthly_searches": []
                },
                "serp_info": {
                  "check_url": "https://www.google.com/search?q=phone%20number",
                  "serp_item_types": [
                    "organic",
                    "people_also_ask",
                    "related_searches"
                  ],
                  "se_results_count": 3650000000,
                  "last_updated_time": "2022-01-13 22:33:10 +00:00",
                  "previous_updated_time": null
                }
              },
              "depth": 1,
              "related_keywords": null
            }
          ]
        }
      ]
    }
  ]
}

状态码与异常处理

请根据顶层和任务级的 status_code 判断请求是否成功：

20000：请求成功。
状态码：请求或任务执行异常，应结合 status_message 排查。

建议客户端同时处理以下：

HTTP 请求失败
顶层 status_code 异常
单个任务的 status_code 异常
tasks_error 大于 0
result、items 或可选字段为空
serp_info 为 null

实用场景

扩展种子词的搜索词：围绕核心递归发现用户搜索表达，扩大 SEO和落地页的覆盖范围。
筛选高潜力：结合搜索量、竞争度、难度和 CPC，优选择流量潜力高且竞争适中的词进行优化。
规划主题集群：利用 core_keyword 和 related_keywords 识别分组，构建支柱页、专题页和长尾之间的主题。
评估广告投放机会：使用 CPC、广告位、每日展示次数和每日点击次数估算的商业价值，为预算分提供依据。
分析 SERP形态：通过 serp_info 判断目标是否精选摘要、问答、图片、本地结果等 SERP 特征，指导页面结构和格式设计。

（旧版） ​

搜索深度示例 ​

计费与请求限制 ​

请求参数 ​

filters 示例 ​

order_by 示例 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应结构 ​

顶层响应字段 ​

任务字段 ​

result 字段 ​

keyword_data 字段 ​

keyword_info ​

keyword_properties ​

impressions_info ​

bing_keyword_info ​

serp_info ​

结果级字段 ​

响应示例 ​

状态码与异常处理 ​

实用场景 ​

（旧版）

搜索深度示例

计费与请求限制

请求参数

`filters` 示例

`order_by` 示例

请求示例

cURL

Python

TypeScript

响应结构

顶层响应字段

任务字段

`result` 字段

`keyword_data` 字段

`keyword_info`

`keyword_properties`

`impressions_info`

`bing_keyword_info`

`serp_info`

结果级字段

响应示例

状态码与异常处理

实用场景