类目（容旧版）- 实时接口

接口说明

该接口用于根据指定的商品或服务类目，返回与之的列表。

对于每个，接口可提供以下数据：

最近一个月的搜索量
过去 12 个月的搜索趋势
当前平均点击单价（CPC）
竞争度（competition）
每日展示、点击、CPC 的最小值、最大值、平均值
可选的 SERP 信息，如搜索结果数量、 URL、SERP 特征

容性说明

该接口文档描述的是 旧版（Legacy）结构。平台 API 已在 2022-03-19 更新请求与响应结构，但当前仍持续容本页所述版本。

接口路径保持不变：/v3/dataforseo_labs/keywords_for_categories/live
如需使用新版结构，请参考对应的新版本文档

请求方式

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

计费说明

该接口按请求计费。

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

请求格式

请求体为 UTF-8 编码的 JSON
POST 请求体格式为 JSON 数组：[{ ... }]
每分钟最多可发送 2000 次 API 调用
支持分页、排序和过滤
单次请求可通过 limit 控制返回结果数

请求参数

字段名	类型	说明
`category_codes`	array	商品/服务类目代码。填。最多可指定 20 个类目。完整类目列表请参考类目单。
`location_name`	string	地区完整名称。未提供 `location_code` 时填。`location_name` 与 `location_code` 二选一。示例：`United Kingdom`
`location_code`	integer	地区唯一标识。未提供 `location_name` 时填。`location_name` 与 `location_code` 二选一。可通过 `/v3/dataforseo_labs/locations_and_languages` 获取。示例：`2840`
`language_name`	string	语言完整名称。未提供 `language_code` 时填。`language_name` 与 `language_code` 二选一。示例：`English`
`language_code`	string	语言唯一标识。未提供 `language_name` 时填。`language_name` 与 `language_code` 二选一。可通过 `/v3/dataforseo_labs/locations_and_languages` 获取。示例：`en`
`category_intersection`	boolean	是否返回同时属于所有指定类目的。可选。默认：`false`
`include_serp_info`	boolean	是否在每个结果中 `serp_info`。可选。设为 `true` 后，会返回搜索结果数量、 URL、SERP 特征等信息。默认：`false`
`limit`	integer	返回的最大数量。可选。默认：`700`，最大：`1000`
`offset`	integer	结果偏移量。可选。默认：`0`。如设为 `10`，则跳过前 10 条结果，从后续结果开始返回
`offset_token`	string	后续分页令牌。可选。适用于单次请求结果 10,000 条时，时。使用响应中返回的 `offset_token` 获取后续结果。注意：如果请求中传 `offset_token`，除 `limit` 外的参数都会被忽略
`filters`	array	结果过滤条件数组。可选。最多支持 8 个过滤条件。条件之间需使用逻辑运算符 `and` 或 `or` 连接。支持运算符：`<`, `<=`, `>`, `>=`, `=`, `<>`, `in`, `not_in`, `like`, `not_like`。 `like` 与 `not_like` 支持使用 `%` 匹任意长度字符串
`order_by`	array	排序规则。可选。可使用与 `filters` 相同的字段路径。排序方式：`asc` 升序、`desc` 降序。单次请求最多支持 3 条排序规则
`tag`	string	自定义任务标识。可选。最大长度 255 字符。便于请求与响应结果对，响应中的 `data` 对象会返回该值

过滤与排序说明

filters 语法

filters 为条件数组，可组合多个条件，例如：

json

[
 ["impressions_info.daily_impressions_average", "in", [0, 1000]],
 "and",
 ["impressions_info.ad_position_average", "<", 3]
]

支持的逻辑/比较运算符：

逻辑：and、or
比较：<, <=, >, >=, =, <>
集合：in, not_in
模糊：like, not_like

order_by 语法

例如按搜索量降序排序：

json

["keyword_info.search_volume,desc"]

多个排序规则示例：

json

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

响应结构

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

顶层字段

字段名	类型	说明
`version`	string	当前 API 版本
`status_code`	integer	局状态码
`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 数组中的字段

字段名	类型	说明
`seed_categories`	array	请求中传的类目
`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 对象

字段名	类型	说明
`last_updated_time`	string	数据更新时间，UTC 格式：`yyyy-mm-dd hh-mm-ss +00:00`
`competition`	float	竞争度，基于广告数据，范围 0 到 1
`cpc`	float	历史平均点击单价，单位 USD
`search_volume`	integer	月均搜索量，近似值
`category_codes`	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 出价来弱化账户差异因素。

字段名	类型	说明
`last_updated_time`	string	展示数据更新时间
`bid`	integer	最大 CPC 出价。固定使用 `999` 以获取更高展示覆盖
`match` / `match_type`	string	匹类型，可为 `exact`、`broad`、`phrase`
`ad_position_min`	float	广告最小位置
`ad_position_max`	float	广告最大位置
`ad_position_average`	float	广告平均位置
`cpc_min`	float	在 `bid=999` 条件下的最小 CPC，单位 USD。不是 CPC
`cpc_max`	float	在 `bid=999` 条件下的最大 CPC，单位 USD。不是 CPC
`cpc_average`	float	在 `bid=999` 条件下的平均 CPC，单位 USD。不是 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	最小日花费，单位 USD
`daily_cost_max`	float	最大日花费，单位 USD
`daily_cost_average`	float	平均日花费，单位 USD

注意： CPC 请以 keyword_info.cpc 为准；impressions_info 中的 CPC 字段为特定模拟出价条件下的估算值。

bing_keyword_info 对象

基于 Bing Ads 的数据。在部分地区和语言下可用。

字段名	类型	说明
`last_updated_time`	string	数据更新时间
`search_volume`	integer	Bing 最近一个月搜索量
`monthly_searches`	array	Bing 月度搜索量趋势

serp_info 对象

当请求参数 include_serp_info=true 时返回；如果数据库中没有对应 SERP 数据，也可能返回 null。

字段名	类型	说明
`check_url`	string	搜索结果页直达链接，用于人工校验
`serp_item_types`	array	SERP 中出现的结果类型
`se_results_count`	string / integer	搜索结果数量
`last_updated_time`	string	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

注意：明细结果通常对 organic、paid、featured_snippet、local_pack 类型提供。

请求示例

cURL

bash

curl --location --request POST "https://api.seermartech.cn/v3/dataforseo_labs/keywords_for_categories/live" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "category_codes": [12191, 12193],
 "language_name": "English",
 "location_code": 2840,
 "include_serp_info": true,
 "filters": [
 ["impressions_info.daily_impressions_average", "in", [0, 1000]],
 "and",
 ["impressions_info.ad_position_average", "<", 3]
 ],
 "limit": 5
 }
]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/dataforseo_labs/keywords_for_categories/live"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

payload = [
 {
 "category_codes": [12191, 12193],
 "location_name": "United States",
 "language_name": "English",
 "filters": [
 ["impressions_info.daily_impressions_average", "in", [0, 1000]],
 "and",
 ["impressions_info.ad_position_average", "<", 3]
 ],
 "limit": 5
 }
]

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

TypeScript

typescript

import axios from "axios";

const payload = [
 {
 category_codes: [12191, 12193],
 language_name: "English",
 location_code: 2840,
 include_serp_info: true,
 filters: [
 ["impressions_info.daily_impressions_average", "in", [0, 1000]],
 "and",
 ["impressions_info.ad_position_average", "<", 3]
 ],
 limit: 5
 }
];

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

响应示例

json

{
 "version": "0.1.20220131",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "5.2265 sec.",
 "cost": 0.0105,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "示例任务ID",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "5.1901 sec.",
 "cost": 0.0105,
 "result_count": 1,
 "path": [
 "v3",
 "dataforseo_labs",
 "keywords_for_categories",
 "live"
 ],
 "data": {
 "api": "dataforseo_labs",
 "function": "keywords_for_categories",
 "category_codes": [12191, 12193],
 "language_name": "English",
 "include_serp_info": true,
 "location_code": 2840,
 "filters": [
 ["impressions_info.daily_impressions_average", "in", [0, 1000]],
 "and",
 ["impressions_info.ad_position_average", "<", 3]
 ],
 "limit": 5
 },
 "result": [
 {
 "location_code": 2840,
 "language_code": "en",
 "total_count": 574,
 "items_count": 5,
 "offset": 0,
 "offset_token": "eyJ...示例分页令牌...",
 "items": [
 {
 "keyword": "9020 dell",
 "location_code": 2840,
 "language_code": "en",
 "keyword_info": {
 "last_updated_time": "2022-01-28 13:19:29 +00:00",
 "competition": 1,
 "cpc": 0.912115,
 "search_volume": 1000,
 "categories": [12191, 12193],
 "monthly_searches": []
 },
 "keyword_properties": {
 "core_keyword": null,
 "keyword_difficulty": 32
 },
 "impressions_info": {
 "last_updated_time": "2021-12-11 19:31:15 +00:00",
 "bid": 999,
 "match_type": "exact",
 "ad_position_min": 1.85,
 "ad_position_max": 2,
 "ad_position_average": 1.68,
 "cpc_min": 75.05,
 "cpc_max": 91.72,
 "cpc_average": 83.38,
 "daily_impressions_min": null,
 "daily_impressions_max": null,
 "daily_impressions_average": null,
 "daily_clicks_min": null,
 "daily_clicks_max": null,
 "daily_clicks_average": null,
 "daily_cost_min": null,
 "daily_cost_max": null,
 "daily_cost_average": null
 },
 "bing_keyword_info": {
 "last_updated_time": "2021-12-21 10:26:18 +00:00",
 "search_volume": 10,
 "monthly_searches": []
 },
 "serp_info": {
 "check_url": "https://www.google.com/search?q=9020%20dell&num=100&hl=en&gl=US",
 "serp_item_types": ["organic", "paid"],
 "se_results_count": 5870000,
 "keyword_difficulty": 32,
 "last_updated_time": "2021-12-18 23:08:30 +00:00",
 "previous_updated_time": null
 }
 }
 ]
 }
 ]
 }
 ]
}

状态码与错误处理

顶层 status_code=20000 表示请求成功
各任务也有独立的 status_code 与 status_message
建议同时检查：
顶层 status_code
tasks_error
每个 task 的 status_code
完整错误码体系请参考错误码附录文档

使用建议

量大时优使用 offset_token 分页 当目标结果很多时，使用 offset_token 获取后续数据，可降低单次时风险。
使用 category_intersection=true 提高结果精度 如果传多个类目且希望结果同时属于这些类目，可开启该参数。
按业务目标组合过滤条件 例如：

筛选低竞争高搜索量词
筛选高展示潜力词
筛选广告位靠前的

按 keyword_info.search_volume 或 keyword_info.cpc 排序 有助于优获取更流量价值或商业价值的。

实用场景

挖掘类目词：根据商品类目批量获取搜索词，用于电商分类页、聚合页和专题页的 SEO 选词。
筛选高商业价值：结合 cpc、competition 和搜索量，识别更可能带来转化的，提升投放和优级判断。
评估类目需求趋势：利用 monthly_searches 分析过去 12 个月搜索变化，识别季节性需求和增长中的产品方向。
发现低难度切词：通过 keyword_difficulty 与过滤条件组合，寻找竞争相对较低但仍有流量空间的长尾词。
分析 SERP 机会位：启用 include_serp_info 后查看 SERP 特征，判断是否适合争夺自然结果、精选摘要、本地等位置。

类目（容旧版）- 实时接口 ​

接口说明 ​

容性说明 ​

请求方式 ​

计费说明 ​

请求格式 ​

请求参数 ​

过滤与排序说明 ​

filters 语法 ​

order_by 语法 ​

响应结构 ​

顶层字段 ​

tasks 数组中的字段 ​

result 数组中的字段 ​

items 字段说明 ​

基础字段 ​

keyword_info 对象 ​

monthly_searches 子字段 ​

keyword_properties 对象 ​

impressions_info 对象 ​

bing_keyword_info 对象 ​

serp_info 对象 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应示例 ​

状态码与错误处理 ​

使用建议 ​

实用场景 ​

类目（容旧版）- 实时接口

接口说明

容性说明

请求方式

计费说明

请求格式

请求参数

过滤与排序说明

filters 语法

order_by 语法

响应结构

顶层字段

tasks 数组中的字段

result 数组中的字段

items 字段说明

基础字段

keyword_info 对象

monthly_searches 子字段

keyword_properties 对象

impressions_info 对象

bing_keyword_info 对象

serp_info 对象

请求示例

cURL

Python

TypeScript

响应示例

状态码与错误处理

使用建议

实用场景