SeerMarTech API 文档

主题

批量查询难度 ​

POST /v3/dataforseo_labs/google/bulk_keyword_difficulty/live

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

/v3/dataforseo_labs/google/bulk_keyword_difficulty/live

一次请求最多可查询 1,000 个的难度（Keyword Difficulty）。该指标用于衡量搜索结果前 10 条自然排名的相对难度，取值范围为 0～100，采用对数刻度计算。数值越高，通常表示获得前 10 条自然排名的难度越大。

接口限制与计费 ​

  • 请求体使用 UTF-8 编码的 JSON 格式。
  • POST 请求体是 JSON 数组，且每次 Live API 请求只能 1 个任务。
  • 每个任务最多 1,000 个。
  • 每分钟最多可发送 2,000 次 API 请求。
  • 同时发送的请求数最多为 30 个。
  • 每次请求均会产生费用。
  • 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。
  • 响应中的 cost 字段（平台原始 USD 成本兼容字段）表示本次请求或任务的成本，金额以扣费响应头为准。

请求参数 ​

请求体示例：

json
[
  {
    "keywords": [
      "dentist new york",
      "pizza brooklyn",
      "car dealer los angeles"
    ],
    "location_name": "United States",
    "language_name": "English",
    "tag": "keyword-difficulty-demo"
  }
]

任务参数 ​

参数名类型填说明
keywordsarray是目标列表。使用 UTF-8 编码，最多可传 1,000 个。平台会将转换为小写格式。
location_namestring条件填地理位置完整名称。当未指定 location_code 时填。例如：United Kingdom。
location_codeinteger条件填地理位置编码。当未指定 location_name 时填。例如：2840。
language_namestring条件填语言完整名称。当未指定 language_code 时填。例如：English。
language_codestring条件填语言编码。当未指定 language_name 时填。例如：en。
tagstring否用户自定义任务标识，最长 255 个字符。可用于识别任务并匹结果。提交的值会原样返回在响应的 data 对象中。

location_name 与 location_code 二选一；language_name 与 language_code 二选一。可通过以下接口查询可用的位置和语言：

/v3/dataforseo_labs/locations_and_languages

响应结构 ​

服务端返回 JSON 数据 tasks 任务数组。

顶层响应字段 ​

字段名类型说明
versionstring当前 API 版本。
status_codeinteger通用响应状态码。
status_messagestring通用状态说明。
timestring请求执行耗时，单位为秒。
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
tasks_countintegertasks 数组中的任务总数。
tasks_errorintegertasks 数组中返回错误的任务数量。
tasksarray任务结果数组。

错误码可参考错误码文档。

任务字段 ​

字段名类型说明
idstring任务唯一标识，采用 UUID 格式。
status_codeinteger任务状态码，通常在 10000～60000 范围。
status_messagestring任务状态说明。
timestring任务执行耗时，单位为秒。
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
result_countintegerresult 数组中的数量。
patharray请求 URL 路径。
dataobject提交任务时使用的参数。
resultarray任务结果数组。

result 字段 ​

字段名类型说明
se_typestring搜索引擎类型。
location_codeinteger / null请求中使用的地理位置编码。无可用数据时为 null。
language_codestring / null请求中使用的语言编码。无可用数据时为 null。
total_countinteger数据库中与请求条件的结果总数。
items_countintegeritems 数组返回的结果数量。
itemsarray含及对应难度的结果列表。

items 字段 ​

字段名类型说明
se_typestring搜索引擎类型。
keywordstring请求中的。
keyword_difficultyinteger难度，取值范围为 0～100。该值表示前 10 条自然搜索结果的相对难度，通常会结合搜索结果前 10 个页面的链接画像等因素计算。

curl 请求示例 ​

bash
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_name": "United States",
      "language_name": "English"
    }
  ]'

Python 请求示例 ​

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",
}

payload = [
    {
        "keywords": [
            "dentist new york",
            "pizza brooklyn",
            "car dealer los angeles",
        ],
        "location_name": "United States",
        "language_name": "English",
    }
]

response = requests.post(url, headers=headers, json=payload, timeout=60)
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 url =
  "https://api.seermartech.cn/v3/dataforseo_labs/google/bulk_keyword_difficulty/live";

const payload = [
  {
    keywords: [
      "dentist new york",
      "pizza brooklyn",
      "car dealer los angeles",
    ],
    location_name: "United States",
    language_name: "English",
  },
];

axios
  .post(url, payload, {
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
  })
  .then((response) => {
    const result = response.data;

    if (result.status_code === 20000) {
      console.log("请求成功：", result);
    } else {
      console.error(
        `请求失败，状态码：${result.status_code}，消息：${result.status_message}`
      );
    }
  })
  .catch((error) => {
    console.error("网络或服务异常：", error.message);
  });

响应示例 ​

json
{
  "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": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.0410 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"
        ]
      },
      "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": 67
            },
            {
              "se_type": "google",
              "keyword": "pizza brooklyn",
              "keyword_difficulty": 54
            },
            {
              "se_type": "google",
              "keyword": "car dealer los angeles",
              "keyword_difficulty": 72
            }
          ]
        }
      ]
    }
  ]
}

实用场景 ​

  • 筛选低竞争：批量获取候选词的难度，优选择更容易自然搜索前 10 的词，提升产出比。
  • 制定分层策略：按难度划分核心词、成长词和长尾词，为不同阶段的 SEO分资源。
  • 比较不同地区的排名难度：使用不同的 location_code 查询同一批，识别适合本地化 SEO 或区域市场拓展的目标词。
  • 评估多语言市场机会：切换 language_code 或 language_name，比较不同语言市场的竞争程度， SEO 选词。
  • 批量审核库：一次提交最多 1,000 个，快速理高难度或不适合当前网站权重的词，并建立可执行的选题单。

统一入口：官网 · LLM API · 控制台

© 2026 SeerMarTech · GEO · SEO 营销数据 API