批量难度（旧版）

接口说明

该接口用于一次性查询最多 1,000 个的 Keyword Difficulty（难度） 指标。

难度表示：某个自然搜索结果前 10 名的相对难度。返回值为 0 到 100 的对数刻度分值，数值越高，通常表示该自然结果前 10 的竞争难度越大。

说明：

• 本页为旧版接口文档，当前仍保持容；
• 如需新版结构，可参考对应新版文档；
• 该指标通常基于 SERP 前 10 个页面的链接画像等多项因素综合计算。

请求地址

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

计费说明

该接口按请求计费。

原文未提供固定单价，因此无法直接换算人民币价格。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求格式

• 请求方法：POST
• 请求体格式：JSON
• 编码：UTF-8
• 请求体为 JSON 数组，格式如下：

[
 {
 "keywords": ["buy laptop", "cheap laptops for sale", "purchase laptop"],
 "location_code": 2840,
 "language_code": "en"
 }
]

频率限制

• 每分钟最多可发送 2000 次 API 调用

---

请求参数

以下为任务设置字段说明。

字段名	类型	说明
keywords	array	目标列表。填。UTF-8 编码；最多可提交 1000 个；每个长度至少 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
language_name	string	语言名。若未提供 language_code，则该字段填。可通过 /v3/dataforseo_labs/locations_and_languages 获取可用语言列表。示例：English
language_code	string	语言编码。若未提供 language_name，则该字段填。可通过 /v3/dataforseo_labs/locations_and_languages 获取可用语言编码。示例：en
tag	string	自定义任务标识。可选，最大长度 255 个字符。可用于请求与响应结果的对应，响应中的 data 对象会返回该值。

---

响应结构

接口返回 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	任务唯一标识，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[] 字段

字段名	类型	说明
location_code	integer	请求中的地区编码；若无数据则为 null
language_code	string	请求中的语言编码；若无数据则为 null
total_count	integer	与请求、数据库中匹的结果总量
items_count	integer	items 数组中返回的结果数量
items	array	及对应难度分值列表

items[] 字段

字段名	类型	说明
keyword	string	请求中的
keyword_difficulty	integer	自然搜索前 10 的难度分值，范围 0-100。该值基于对 SERP 前 10 页面链接画像等因素的分析计算得出。

---

请求示例

cURL

curl --location --request POST "https://api.seermartech.cn/v3/dataforseo_labs/bulk_keyword_difficulty/live" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "keywords": [
 "buy laptop",
 "cheap laptops for sale",
 "purchase laptop"
 ],
 "location_code": 2840,
 "language_code": "en"
 }
]'

Python

import requests

url = "https://api.seermartech.cn/v3/dataforseo_labs/bulk_keyword_difficulty/live"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
payload = [
 {
 "keywords": [
 "buy laptop",
 "cheap laptops for sale",
 "purchase laptop"
 ],
 "location_name": "United States",
 "language_name": "English"
 }
]

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

TypeScript

import axios from "axios";

const postArray = [
 {
 keywords: [
 "buy laptop",
 "cheap laptops for sale",
 "purchase laptop"
 ],
 location_code: 2840,
 language_code: "en"
 }
];

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

---

响应示例

{
 "version": "0.1.20211130",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.1214 sec.",
 "cost": 0.0103,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.1023 sec.",
 "cost": 0.0103,
 "result_count": 1,
 "path": [
 "v3",
 "dataforseo_labs",
 "bulk_keyword_difficulty",
 "live"
 ],
 "data": {
 "api": "dataforseo_labs",
 "function": "bulk_keyword_difficulty",
 "keywords": [
 "buy laptop",
 "cheap laptops for sale",
 "purchase laptop"
 ],
 "location_code": 2840,
 "language_code": "en"
 },
 "result": [
 {
 "location_code": 2840,
 "language_code": "en",
 "total_count": 3,
 "items_count": 3,
 "items": [
 {
 "keyword": "buy laptop",
 "keyword_difficulty": 46
 },
 {
 "keyword": "cheap laptops for sale",
 "keyword_difficulty": 58
 },
 {
 "keyword": "purchase laptop",
 "keyword_difficulty": 41
 }
 ]
 }
 ]
 }
 ]
}

---

状态码与错误处理

• 顶层 status_code 表示整个请求的执行状态；
• tasks[].status_code 表示单个任务的执行状态；
• 建议同时校验这两个状态码，并为异常设计重试、告警与底处理机制；
• 完整错误码定义请参考 /v3/appendix/errors。

常见判断方式：

• 20000：请求成功
• 状态码：表示参数错误、认证失败、额限制或平台处理异常等

---

使用建议

1. 单次最多提交 1000 个，适合批量评估竞争度；
2. 若需要稳定的地域和语言维度分析，建议始终显式传 location_code 与 language_code；
3. 会自动转为小写，做结果比对时建议统一归一化处理；
4. 若业务中需要任务追踪，建议传 tag 字段。

实用场景

• 批量筛选低难度词：一次评估大批候选的排名难度，优找出更容易前 10 的词，提升选题效率。
• 制定优级：结合难度与搜索量，对生产队列进行分层，优高价值且可竞争的主题。
• 评估新市场切机会：按不同国家地区和语言查询同一批难度，识别竞争更低的海外市场。
• 监控词库竞争变化：定期对核心词库重复查询难度分值，跟踪行业竞争强弱变化，为 SEO 策略调整提供依据。
• 落地页规划：根据不同的难度差异，决定是优做聚合页、专题页还是高质量深度页。