批量难度查询

接口说明

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

难度表示：某个 Google 自然搜索前 10 名结果的相对难度。返回值范围为 0 到 100，采用 对数刻度 表示。数值越高，通常意味着前 10 名自然结果越困难。

接口路径：

POST /v3/dataforseo_labs/google/bulk_keyword_difficulty/live

完整请求地址：

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

计费与频率限制

• 本接口按请求计费
• 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准
• 调用频率上限：2000 次/分钟
• 最大并发请求数：30

请求格式

• 请求方法：POST
• 编码格式：UTF-8
• 请求体格式：JSON 数组 [{ ... }]

请求参数

以下为单个任务对象可用字段说明：

字段名	类型	说明
keywords	array	填。目标列表。最多支持 1000 个；使用 UTF-8 编码；会自动转换为小写。
location_name	string	地区完整名称。若未提供 location_code，则该字段填。示例：United Kingdom
location_code	integer	地区编码。若未提供 location_name，则该字段填。示例：2840
language_name	string	语言完整名称。若未提供 language_code，则该字段填。示例：English
language_code	string	语言编码。若未提供 language_name，则该字段填。示例：en
tag	string	可选。用户自定义任务标识，最长 255 个字符，可用于请求与响应结果匹；返回时会出现在响应的 data 对象中。

地区与语言列表获取

可通过以下接口获取可用的 location_name、location_code、language_name、language_code：

/v3/dataforseo_labs/locations_and_languages

响应结构

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

顶层字段

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

tasks[] 字段

字段名	类型	说明
id	string	任务唯一标识，UUID 格式
status_code	integer	任务状态码，范围通常为 10000-60000，完整列表参考 /v3/appendix/errors
status_message	string	任务状态信息，完整列表参考 /v3/appendix/errors
time	string	任务执行耗时，单位秒
cost	float	单个任务费用，单位 USD
result_count	integer	result 数组中的结果数量
path	array	URL 路径
data	object	回显请求中提交的参数
result	array	获取结果数组

tasks[].result[] 字段

字段名	类型	说明
se_type	string	搜索引擎类型
location_code	integer	请求中的地区编码；若无数据则为 null
language_code	string	请求中的语言编码；若无数据则为 null
total_count	integer	数据库中与本次请求的结果总数
items_count	integer	items 数组返回的结果数量
items	array	及难度列表

tasks[].result[].items[] 字段

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

请求示例

cURL

curl --location --request POST "https://api.seermartech.cn/v3/dataforseo_labs/google/bulk_keyword_difficulty/live" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "keywords": [
 "dentist new york",
 "pizza brooklyn",
 "car dealer los angeles"
 ],
 "location_code": 2840,
 "language_name": "English",
 "tag": "batch-kd-001"
 }
]'

Python

import requests

url = "https://api.seermartech.cn/v3/dataforseo_labs/google/bulk_keyword_difficulty/live"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
data = [
 {
 "keywords": [
 "dentist new york",
 "pizza brooklyn",
 "car dealer los angeles"
 ],
 "location_name": "United States",
 "language_name": "English",
 "tag": "batch-kd-001"
 }
]

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

TypeScript

import axios from "axios";

const postData = [
 {
 keywords: [
 "dentist new york",
 "pizza brooklyn",
 "car dealer los angeles"
 ],
 location_code: 2840,
 language_name: "English",
 tag: "batch-kd-001"
 }
];

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

响应示例

{
 "version": "0.1.20220216",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0510 sec.",
 "cost": 0.0103,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "a6c5c7d2-1c23-4f32-9c7d-1234567890ab",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0321 sec.",
 "cost": 0.0103,
 "result_count": 1,
 "path": [
 "v3",
 "dataforseo_labs",
 "google",
 "bulk_keyword_difficulty",
 "live"
 ],
 "data": {
 "api": "dataforseo_labs",
 "function": "bulk_keyword_difficulty",
 "se_type": "google",
 "location_code": 2840,
 "language_code": "en",
 "keywords": [
 "dentist new york",
 "pizza brooklyn",
 "car dealer los angeles"
 ],
 "tag": "batch-kd-001"
 },
 "result": [
 {
 "se_type": "google",
 "location_code": 2840,
 "language_code": "en",
 "total_count": 3,
 "items_count": 3,
 "items": [
 {
 "se_type": "google",
 "keyword": "dentist new york",
 "keyword_difficulty": 62
 },
 {
 "se_type": "google",
 "keyword": "pizza brooklyn",
 "keyword_difficulty": 48
 },
 {
 "se_type": "google",
 "keyword": "car dealer los angeles",
 "keyword_difficulty": 71
 }
 ]
 }
 ]
 }
 ]
}

状态码与错误处理

• 顶层 status_code 表示整个请求的执行状态
• tasks[].status_code 表示单个任务的执行状态
• 建议同时检查：
• HTTP 状态码
• 顶层 status_code
• 任务级 tasks[].status_code

常用成功状态：

状态码	含义
20000	请求成功

完整错误码与状态说明请参考：

/v3/appendix/errors

使用建议

• 批量提交时，建议按主题或业务线分组，便于后续分析
• 若已有固定地区和语言，优使用 location_code 与 language_code，可减少名称歧义
• 对返回的 keyword_difficulty 建议结合搜索量、CPC、SERP 特征等指标综合评估，而不是单独使用
• 单次最多支持 1000 个；若量更大，建议分批请求

实用场景

• 筛选低难度词：批量识别更容易前 10 的，帮助团队优布局更快见效的 SEO 主题。
• 评估新市场机会：按不同国家或语言查询同一批难度，判断哪些区域更适合优投放。
• 建立分层：将按难度分为低、中、高竞争层级，为规划、外链和上线节奏提供依据。
• 对比细分主题竞争度：针对同一业务下的多个词批量计算难度，快速找出竞争相对可控的切方向。
• 流量增长预测：将难度与搜索量、转化价值结合，筛选“可做且值得做”的目标词，提升 SEO 投产出比。