网站挖掘（旧版）—实时接口

GET /v3/dataforseo_labs/locations_and_languages

接口说明

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

text

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

Keywords For Site（旧版）用于根据目标网站域名，返回与该网站的列表。每个通常：

所属类别
最近月份的搜索量
每次点击费用（CPC）
竞争度
过去 12 个月的搜索量趋势
难度
广告展示、点击和费用预估
可选的搜索结果页（SERP）信息

> 本页面说明的是旧版请求和响应结构。新版接口文档请参考 /v3/dataforseo_labs/google/keywords_for_site/live/。

数据来源与算法

数据来源：数据库，结合广告数据、域名数据及 SERP 数据。
搜索算法：根据目标网站所属类别，检索与性较高的。
示例：
- 目标域名：letslevitate.com
- 可能返回的：xvt blades、scar blades falcon、palatine blades、blades macomb il

计费说明

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

所有 POST 数据使用 UTF-8 编码的 JSON 格式。请求体是 JSON 数组，任务参数放在数组中。平台限流以认证说明中的 30/60/120 次/分钟规则为准。

你可以通过 limit、offset、offset_token、filters 和 order_by 控制返回数量、分页、筛选及排序。

请求参数

参数	类型	填	说明
`target`	string	是	目标网站域名，不应 `https://` 或 `www.`，例如 `apple.com`。
`location_name`	string	二选一	地理位置完整名称。当未指定 `location_code` 时填，例如 `United States`。
`location_code`	integer	二选一	地理位置唯一编号。当未指定 `location_name` 时填，例如 `2840`。
`language_name`	string	否	语言完整名称。指定该参数后无需再指定 `language_code`，例如 `English`。不指定时返回所有可用语言的结果。
`language_code`	string	否	语言代码。指定该参数后无需再指定 `language_name`，例如 `en`。不指定时返回所有可用语言的结果。
`include_serp_info`	boolean	否	是否为每个返回 SERP 数据搜索结果数量、 URL 和 SERP 特征。默认值为 `false`。
`include_subdomains`	boolean	否	是否将目标域名的子域名纳搜索。设置为 `false` 时忽略子域名。默认值为 `true`。
`limit`	integer	否	`items` 数组最多返回的数量。默认值为 `700`，最大值为 `1000`。
`offset`	integer	否	结果偏移量，默认值为 `0`。例如设置为 `10` 时，跳过前 10 条结果。
`offset_token`	string	否	后续分页令牌。该值由响应中的同名字段返回，用于获取同一任务的后续结果。指定此参数后，除 `limit` 外的请求参数均不会生效。
`filters`	array	否	结果筛选条件。最多支持 8 个筛选条件，需要使用 `and` 或 `or` 连接。不能按 `relevance` 筛选。
`order_by`	array	否	结果排序规则。最多支持 3 个排序字段，格式为 `字段,排序方向`，排序方向为 `asc` 或 `desc`。
`tag`	string	否	用户自定义任务标识，最多 255 个字符。该值会原样返回在响应的 `data` 对象中。

地理位置和语言

可通过以下接口获取可用的地理位置及语言：

text

GET https://api.seermartech.cn/v3/dataforseo_labs/locations_and_languages

location_name 与 location_code须至少指定一个；language_name 与 language_code 均为可选参数，并且同一请求中不应同时指定。

筛选条件

支持的运算符：

text

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

like 和 not_like 支持使用 % 匹零个或多个字符。

示例：

json

"filters": [
  ["keyword_info.search_volume", ">", 1000],
  "and",
  ["keyword_info.competition", "<", 0.5]
]

排序规则

排序字段使用如下格式：

json

"order_by": [
  "keyword_info.search_volume,desc"
]

默认性排序，以优返回与目标网站最接近的。relevance 是系统排序标识，不会出现在 result 数组中，也不能用于筛选。

请求示例

curl

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/dataforseo_labs/keywords_for_site/live" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "target": "apple.com",
      "location_code": 2840,
      "language_code": "en",
      "include_serp_info": true,
      "include_subdomains": true,
      "filters": [
        ["keyword_info.search_volume", ">", 1000]
      ],
      "order_by": [
        "keyword_info.search_volume,desc"
      ],
      "limit": 5
    }
  ]'

Python

python

import requests

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

headers = {
    "Authorization": "Bearer smt_live_YOUR_KEY",
    "Content-Type": "application/json",
}

payload = [
    {
        "target": "apple.com",
        "location_name": "United States",
        "language_name": "English",
        "include_serp_info": True,
        "include_subdomains": True,
        "filters": [
            ["serp_info.keyword_difficulty", ">", 0]
        ],
        "order_by": [
            "keyword_info.search_volume,desc"
        ],
        "limit": 5,
    }
]

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

if data.get("status_code") == 20000:
    print(data)
else:
    print(
        "请求失败，错误码：{}，错误信息：{}".format(
            data.get("status_code"),
            data.get("status_message"),
        )
    )

TypeScript

typescript

import axios from "axios";

const payload = [
  {
    target: "apple.com",
    location_code: 2840,
    language_code: "en",
    include_serp_info: true,
    include_subdomains: true,
    filters: [
      ["keyword_info.search_volume", ">", 1000],
    ],
    order_by: [
      "keyword_info.search_volume,desc",
    ],
    limit: 5,
  },
];

axios.post(
  "https://api.seermartech.cn/v3/dataforseo_labs/keywords_for_site/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	当前接口版本。
`status_code`	integer	整体请求状态码。`20000` 表示成功。
`status_message`	string	整体状态说明。
`time`	string	请求执行耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务总数。
`tasks_error`	integer	执行失败的任务数量。
`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	请求路径信息。
`data`	object	请求中提交的任务参数。
`result`	array	结果数组。

`result` 字段

字段	类型	说明
`target`	string	请求中的目标域名。
`location_code`	integer	地理位置编号。
`language_code`	string	语言代码。
`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 广告数据的信息；部分地区和语言支持。
`serp_info`	object / null	SERP 数据。未将 `include_serp_info` 设置为 `true`，或数据库中没有该的 SERP 数据时为 `null`。

`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	难度，取值范围为 `0` 至 `100`，用于表示自然搜索结果前 10 名的难度。数值越高，竞争通常越激烈。

`impressions_info`

该对象基于最高出价 999 的广告预估数据，用于降低账户因素对展示量估算的影响。daily_impressions 通常可作为月搜索量之外的参考指标。

字段	类型	说明
`last_updated_time`	string	展示数据更新时间，UTC 格式。
`bid`	integer	最高每次点击出价，接口通常返回 `999`。
`match_type`	string	匹类型：`exact`、`broad`、`phrase`。
`ad_position_min`	float	最低广告位置。
`ad_position_max`	float	最高广告位置。
`ad_position_average`	float	平均广告位置。
`cpc_min`	float	最低预估 CPC。该字段是出价为 `999` 时的估算值，并非 CPC。
`cpc_max`	float	最高预估 CPC。该字段是出价为 `999` 时的估算值，并非 CPC。
`cpc_average`	float	平均预估 CPC。 CPC 请使用 `keyword_info.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`

字段	类型	说明
`last_updated_time`	string	数据更新时间，UTC 格式。
`search_volume`	integer	过去一个月在 Bing 上的搜索量。
`monthly_searches`	array	指定地区过去 12 个月的月度搜索量。

monthly_searches 数组字段与 keyword_info.monthly_searches 相同：

json

{
  "year": 2024,
  "month": 1,
  "search_volume": 320
}

`serp_info`

当 include_serp_info 为 true 且存在对应 SERP 数据时返回。

字段	类型	说明
`check_url`	string	搜索结果页直接 URL，可用于核验返回结果。
`serp_item_types`	array	搜索结果页中出现的结果类型。
`se_results_count`	string / integer	搜索结果总数。
`keyword_difficulty`	integer	自然搜索结果前 10 名的难度，范围为 `0` 至 `100`。
`last_updated_time`	string	SERP 数据最近更新时间，UTC 格式。
`previous_updated_time`	string / null	SERP 数据上一次更新时间，UTC 格式。

serp_item_types 可能：

text

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

响应示例

json

{
  "version": "0.1.20220214",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "9.3410 sec.",
  "cost": 0.0105,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "060815ಾತ-0001-0000-0000-000000000000",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "8.9210 sec.",
      "cost": 0.0105,
      "result_count": 1,
      "path": [
        "v3",
        "dataforseo_labs",
        "keywords_for_site",
        "live"
      ],
      "data": {
        "api": "dataforseo_labs",
        "function": "keywords_for_site",
        "target": "apple.com",
        "language_name": "English",
        "location_code": 2840,
        "include_serp_info": true,
        "include_subdomains": true,
        "filters": [],
        "order_by": [
          "keyword_info.search_volume,desc"
        ],
        "limit": 5
      },
      "result": [
        {
          "target": "apple.com",
          "location_code": 2840,
          "language_code": "en",
          "total_count": 125000,
          "items_count": 1,
          "offset": 0,
          "offset_token": "eyJvZmZzZXQiOjF9",
          "items": [
            {
              "keyword": "apple",
              "location_code": 2840,
              "language_code": "en",
              "keyword_info": {
                "last_updated_time": "2022-01-24 13:13:43 +00:00",
                "competition": 0.72,
                "cpc": 1.25,
                "search_volume": 1000000,
                "categories": [
                  10001
                ],
                "monthly_searches": [
                  {
                    "year": 2022,
                    "month": 1,
                    "search_volume": 1000000
                  }
                ]
              },
              "keyword_properties": {
                "core_keyword": null,
                "keyword_difficulty": 90
              },
              "impressions_info": {
                "last_updated_time": "2022-01-24 13:13:43 +00:00",
                "bid": 999,
                "match_type": "exact",
                "ad_position_min": 1.2,
                "ad_position_max": 2.1,
                "ad_position_average": 1.6,
                "cpc_min": 1.1,
                "cpc_max": 2.4,
                "cpc_average": 1.8,
                "daily_impressions_min": 1000,
                "daily_impressions_max": 1500,
                "daily_impressions_average": 1250,
                "daily_clicks_min": 50,
                "daily_clicks_max": 80,
                "daily_clicks_average": 65,
                "daily_cost_min": 80,
                "daily_cost_max": 140,
                "daily_cost_average": 110
              },
              "bing_keyword_info": {
                "last_updated_time": "2022-01-29 07:30:05 +00:00",
                "search_volume": 320,
                "monthly_searches": [
                  {
                    "year": 2022,
                    "month": 1,
                    "search_volume": 320
                  }
                ]
              },
              "serp_info": {
                "check_url": "https://www.google.com/search?q=apple",
                "serp_item_types": [
                  "organic",
                  "paid",
                  "images",
                  "people_also_ask"
                ],
                "se_results_count": 7270000000,
                "keyword_difficulty": 90,
                "last_updated_time": "2022-01-13 20:29:05 +00:00",
                "previous_updated_time": null
              }
            }
          ]
        }
      ]
    }
  ]
}

状态码与异常处理

请根据顶层 status_code、任务级 status_code 及对应的 status_message 判断请求是否成功：

20000：请求或任务执行成功。
状态码：表示请求参数、认证、频率限制、数据处理或服务异常。

建议在客户端实现以下处理逻辑：

判断 HTTP 状态码。
再判断顶层 status_code。
遍历 tasks，检查每个任务的 status_code。
对失败任务记录 id、status_code 和 status_message。
使用 offset_token 获取大批量结果，单次请求时。

实用场景

挖掘竞品网站：竞品域名，获取、搜索量和竞争度，扩展竞品研究与规划范围。
筛选选题：按搜索量、难度和 CPC 过滤，优安排流量潜力且竞争可控的文章主题。
规划区域化 SEO：结合 location_code 或 location_name 获取不同地区的数据，制定本地化落地页和区域策略。
评估广告投放机会：使用 CPC、广告位置、展示量、点击量和日均费用预估，判断的商业价值与投放预算。
分析自然搜索竞争：结合 serp_info、SERP 特征和 keyword_difficulty，识别适合争取自然排名的及对应结果页形态。

网站挖掘（旧版）—实时接口 ​

接口说明 ​

数据来源与算法 ​

计费说明 ​

请求参数 ​

地理位置和语言 ​

筛选条件 ​

排序规则 ​

请求示例 ​

curl ​

Python ​

TypeScript ​

响应结构 ​

顶层字段 ​

任务字段 ​

result 字段 ​

items 字段 ​

keyword_info ​

keyword_properties ​

impressions_info ​

bing_keyword_info ​

serp_info ​

响应示例 ​

状态码与异常处理 ​

实用场景 ​

网站挖掘（旧版）—实时接口

接口说明

数据来源与算法

计费说明

请求参数

地理位置和语言

筛选条件

排序规则

请求示例

curl

Python

TypeScript

响应结构

顶层字段

任务字段

`result` 字段

`items` 字段

`keyword_info`

`keyword_properties`

`impressions_info`

`bing_keyword_info`

`serp_info`

响应示例

状态码与异常处理

实用场景