SeerMarTech API 文档

主题

按分类获取（实时） ​

接口说明 ​

该接口用于根据指定的产品/服务分类，返回与这些分类的列表。

每个可返回以下核心数据：

  • 最近一个月的搜索量
  • 过去 12 个月的搜索量趋势
  • 当前平均点击单价（CPC）
  • 竞价竞争度
  • 可选的 SERP 信息
  • 可选的点击流归一化数据

请求地址 ​

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

计费说明 ​

该接口按请求计费。原文未提供固定单价，因此无法预估单次人民币参考价。 扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

调用限制 ​

  • 每分钟最多可发起 2000 次 API 调用
  • 同时并发请求数上限为 30

请求格式 ​

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

请求参数 ​

字段类型说明
category_codesarray填。产品/服务分类数组。最多可传 20 个分类编码。分类单可通过参考文档获取。
location_namestringlocation_code 未提供时填。地区完整名称。需与 location_code 二选一。可通过 /v3/dataforseo_labs/locations_and_languages 获取可用地区名称。例如：United Kingdom
location_codeintegerlocation_name 未提供时填。地区唯一编码。需与 location_name 二选一。可通过 /v3/dataforseo_labs/locations_and_languages 获取可用地区编码。例如：2840
language_namestringlanguage_code 未提供时填。语言完整名称。需与 language_code 二选一。可通过 /v3/dataforseo_labs/locations_and_languages 获取可用语言名称。例如：English
language_codestringlanguage_name 未提供时填。语言编码。需与 language_name 二选一。可通过 /v3/dataforseo_labs/locations_and_languages 获取可用语言编码。例如：en
category_intersectionboolean可选。是否返回同时属于所有指定分类的。true 表示取交集；false 表示取并集。默认：true
include_serp_infoboolean可选。是否在结果中返回每个的 serp_info 数据搜索结果数、对应搜索 URL、SERP 特征等。默认：false
include_clickstream_databoolean可选。是否返回点击流指标。开启后，响应中将 clickstream_keyword_info、keyword_info_normalized_with_clickstream、keyword_info_normalized_with_bing。默认：false
ignore_synonymsboolean可选。是否忽略高度相似词。设为 true 时返回核心，不返回高相似度同义词。默认：false
limitinteger可选。返回条数上限。默认：100，最大：1000
offsetinteger可选。结果偏移量。默认：0。例如设置为 10 时，将跳过前 10 条结果。建议在获取不 10,000 条结果时使用
offset_tokenstring可选。用于翻页获取后续结果。适合拉取 10,000 条数据时使用，可时。如果请求中指定了 offset_token，除 limit 外余参数将被忽略
filtersarray可选。结果过滤条件数组，最多支持 8 个过滤条件。条件之间可使用 and、or 连接
order_byarray可选。结果排序规则。排序字段与 filters 可用字段一致。支持 asc、desc。单次请求最多支持 3 条排序规则
tagstring可选。自定义任务标识，最大长度 255。便于在响应中识别和任务

filters 用法 ​

filters 支持以下运算符：

  • regex
  • not_regex
  • <
  • <=
  • >
  • >=
  • =
  • <>
  • in
  • not_in
  • match
  • not_match
  • ilike
  • not_ilike
  • like
  • not_like

说明：

  • like / not_like / ilike / not_ilike 支持 % 通符
  • % 可匹任意长度字符串（空字符串）
  • 多个条件之间可通过 and、or 组合

filters 示例 ​

json
[
 ["keyword_info.search_volume", ">", 1000],
 "and",
 ["keyword", "like", "%desktop%"]
]

如需更复杂的过滤语法，可参考 /v3/dataforseo_labs/filters。

order_by 用法 ​

支持使用与 filters 相同的字段路径进行排序。

单字段排序示例 ​

json
["keyword_info.search_volume,desc"]

多字段排序示例 ​

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

默认排序规则以平台当前实现为准。单次请求最多支持 3 条排序规则。

请求示例 ​

cURL ​

bash
curl --location --request POST "https://api.seermartech.cn/v3/dataforseo_labs/google/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,
 "limit": 3
 }
]'

Python ​

python
import requests

url = "https://api.seermartech.cn/v3/dataforseo_labs/google/keywords_for_categories/live"
payload = [
 {
 "category_codes": [12191, 12193],
 "location_name": "United States",
 "language_name": "English",
 "filters": [
 ["keyword_info.search_volume", ">", 10]
 ],
 "limit": 3
 }
]
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

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

TypeScript ​

typescript
import axios from "axios";

const postArray = [
 {
 category_codes: [12191, 12193],
 language_name: "English",
 location_code: 2840,
 filters: [
 ["keyword_info.search_volume", ">", 10]
 ],
 limit: 3
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/dataforseo_labs/google/keywords_for_categories/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.response?.data || error.message);
 });

响应结构 ​

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

顶层字段 ​

字段类型说明
versionstring当前 API 版本
status_codeinteger通用状态码
status_messagestring通用状态信息
timestring执行耗时，单位秒
costfloat本次请求总费用，单位 USD
tasks_countintegertasks 数组中的任务数
tasks_errorinteger返回错误的任务数
tasksarray任务结果数组

tasks 数组字段 ​

字段类型说明
idstring任务唯一标识，UUID 格式
status_codeinteger任务状态码
status_messagestring任务状态信息
timestring任务执行耗时
costfloat单任务费用，单位 USD
result_countintegerresult 数组个数
patharray请求路径
dataobject与请求体中提交参数一致
resultarray结果数组

result 数组字段 ​

字段类型说明
se_typestring搜索引擎类型
seed_categoriesarray请求中提交的分类
location_codeinteger请求中的地区编码
language_codestring请求中的语言编码
total_countinteger数据库中匹该请求的总结果数
items_countinteger当前 items 返回条数
offsetinteger当前偏移量
offset_tokenstring后续翻页令牌
itemsarray及数据

items 字段说明 ​

基础字段 ​

字段类型说明
se_typestring搜索引擎类型
keywordstring找到的
location_codeinteger地区编码
language_codestring语言编码

keyword_info 对象 ​

返回的基础指标数据。

字段类型说明
se_typestring搜索引擎类型
last_updated_timestring数据更新时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00
competitionfloat竞价竞争度，取值 0 到 1
competition_levelstring竞争级别，可为 LOW、MEDIUM、HIGH，未知时为 null
cpcfloat平均点击单价，单位 USD
search_volumeinteger平均月搜索量
low_top_of_page_bidfloat首页顶部广告展示的较低出价参考
high_top_of_page_bidfloat首页顶部广告展示的较高出价参考
categoriesarray所属产品/服务分类
monthly_searchesarray最近 12 个月月度搜索量
search_volume_trendobject搜索量趋势变化

monthly_searches 子字段 ​

字段类型说明
yearinteger年份
monthinteger月份
search_volumeinteger当月搜索量

search_volume_trend 子字段 ​

字段类型说明
monthlyinteger相比上个月的变化百分比
quarterlyinteger相比上季度的变化百分比
yearlyinteger相比去年的变化百分比

clickstream_keyword_info 对象 ​

当 include_clickstream_data=true 时返回。

字段类型说明
search_volumeinteger基于点击流估算的月搜索量
last_updated_timestring点击流数据集更新时间
gender_distributionobject性别分布
age_distributionobject年龄分布
monthly_searchesarray月度点击流搜索量

gender_distribution ​

字段类型说明
femaleinteger女性用户数
maleinteger男性用户数

age_distribution ​

字段类型说明
18-24integer18-24 岁用户数
25-34integer25-34 岁用户数
35-44integer35-44 岁用户数
45-54integer45-54 岁用户数
55-64integer55-64 岁用户数

keyword_properties 对象 ​

附加属性信息。

字段类型说明
se_typestring搜索引擎类型
core_keywordstring同义词聚类中的核心
synonym_clustering_algorithmstring同义词识别算法，可为 keyword_metrics 或 text_processing
keyword_difficultyinteger排名难度，范围 0-100
detected_languagestring系统识别出的语言
is_another_languageboolean是否与请求设置语言不同
words_countinteger词数

serp_info 对象 ​

当 include_serp_info=true 时返回；若平台无对应 SERP 数据，也可能为 null。

字段类型说明
se_typestring搜索引擎类型
check_urlstring搜索结果检查链接
serp_item_typesarraySERP 中出现的结果类型
se_results_countstring搜索结果数量
last_updated_timestring最近一次 SERP 更新时间
previous_updated_timestring上一次 SERP 更新时间

支持识别的 serp_item_types括：

answer_box、app、carousel、multi_carousel、featured_snippet、google_flights、google_reviews、third_party_reviews、google_posts、images、jobs、knowledge_graph、local_pack、hotels_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、visual_stories、commercial_units、local_services、google_hotels、math_solver、currency_box、product_considerations、found_on_web、short_videos、refine_products、explore_brands、perspectives、discussions_and_forums、compare_sites、courses、ai_overview

注意：明细结果对 organic、paid、featured_snippet、local_pack 返回。

返回该在自然搜索前 10 页面中的平均外链画像。

字段类型说明
se_typestring搜索引擎类型
backlinksfloat平均外链数
dofollowfloat平均 dofollow 链接数
referring_pagesfloat平均引荐页面数
referring_domainsfloat平均引荐域名数
referring_main_domainsfloat平均主域名数
rankfloat平均 Rank 值
main_domain_rankfloat平均主域名 Rank 值
last_updated_timestring外链数据更新时间

search_intent_info 对象 ​

返回搜索意图信息。

字段类型说明
se_typestring搜索引擎类型支持 google
main_intentstring主搜索意图：informational、navigational、commercial、transactional
foreign_intentarray补搜索意图，取值同上
last_updated_timestring搜索意图数据更新时间

keyword_info_normalized_with_bing 对象 ​

返回使用 Bing 搜索量归一化后的数据。

字段类型说明
last_updated_timestring数据集更新时间
search_volumeinteger当前搜索量
is_normalizedboolean是否已使用 Bing 数据归一化
monthly_searchesarray月度搜索量数据

keyword_info_normalized_with_clickstream 对象 ​

返回使用点击流数据归一化后的数据。

字段类型说明
last_updated_timestring数据集更新时间
search_volumeinteger当前搜索量
is_normalizedboolean是否已使用点击流数据归一化
monthly_searchesarray月度搜索量数据

响应示例 ​

json
{
 "version": "0.1.20240801",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.1943 sec.",
 "cost": 0.0103,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "dataforseo_labs",
 "function": "keywords_for_categories",
 "se_type": "google",
 "category_codes": [12191, 12193],
 "language_name": "English",
 "location_code": 2840,
 "include_serp_info": true,
 "limit": 3
 },
 "result": [
 {
 "location_code": 2840,
 "language_code": "en",
 "total_count": 11982,
 "items_count": 3,
 "offset": 0,
 "offset_token": "eyJDdXJyZW50T2Zmc2V0IjozLCJSZXF1ZXN0RGF0YSI6eyJjYXRlZ29yaWVzIjpbMTIxOTEsMTIxOTNdLCJsb2NhdGlvbiI6Mjg0MCwibGFuZ3VhZ2UiOiJlbiIsImludGVyc2VjdCI6dHJ1ZSwibG9hZF9zZXJwX2luZm8iOnRydWUsInNlYXJjaF9hZnRlcl90b2tlbiI6bnVsbCwiaWdub3JlX3N5bm9ueW1zIjpmYWxzZSwic2VhcmNoX2VuZ2luZSI6Imdvb2dsZSIsInVzZV9uZXdfY2F0ZWdvcmllcyI6dHJ1ZSwib3JkZXJfYnkiOnsib3JkZXJfZmllbGQiOiJrZXl3b3JkX2luZm8uc2VhcmNoX3ZvbHVtZSIsIm9yZGVyX3R5cGUiOiJEZXNjIiwibmV4dCI6bnVsbH0sImxpbWl0IjozLCJvZmZzZXQiOjAsImFpZCI6MTUzNX0sIlJhd1F1ZXJ5IjpudWxsLCJJZCI6IjQwY2ViMTk5LTk3ZGYtNGRmZC04MzJhLThkMmI3NWNlZGZiYSIsIlNlYXJjaEFmdGVyRGF0YSI6WzE0ODAwLCI4YjA2NzljNy1lZWVhLTFjMmEtYWRlNi0wNDg5M2FlZTc1NGEiXX0=",
 "items": [
 {
 "se_type": "google",
 "keyword": "desktop dell optiplex",
 "location_code": 2840,
 "language_code": "en",
 "keyword_info": {
 "se_type": "google",
 "last_updated_time": "2024-08-08 11:13:37 +00:00",
 "competition": 0.07,
 "competition_level": "LOW",
 "cpc": 0.51,
 "search_volume": 18100,
 "monthly_searches": [],
 "search_volume_trend": {
 "monthly": 22,
 "quarterly": 22,
 "yearly": 0
 }
 },
 "clickstream_keyword_info": null,
 "keyword_properties": {
 "se_type": "google",
 "core_keyword": "dell optiplex desktop",
 "synonym_clustering_algorithm": "text_processing",
 "keyword_difficulty": 19,
 "detected_language": "en",
 "is_another_language": false,
 "words_count": 3
 },
 "serp_info": {
 "se_type": "google",
 "check_url": "https://www.google.com/search?q=desktop%20dell%20optiplex&num=100&hl=en&gl=US&gws_rd=cr&ie=UTF-8&oe=UTF-8&glp=1&uule=w+CAIQIFISCQs2MuSEtepUEUK33kOSuTsc",
 "serp_item_types": ["organic", "paid"],
 "se_results_count": 22200000,
 "last_updated_time": "2024-07-14 22:14:14 +00:00",
 "previous_updated_time": "2022-07-15 11:54:47 +00:00"
 }
 }
 ]
 }
 ]
 }
 ]
}

状态码与错误处理 ​

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

常见成功状态：

  • 20000：成功

错误码完整列表可参考 /v3/appendix/errors。 建议在生产环境中建立统一的异常处理和重试机制，以下：

  • 参数缺失或格式错误
  • 地区/语言/分类编码无效 -出并发或频率限制
  • 翻页时 offset_token 失效或使用方式错误

使用建议 ​

  1. 类别组合策略 若希望保留同时属于多个分类的，使用 category_intersection=true；如需尽可能扩大候选词覆盖面，使用 false。

  2. 大结果集分页

  • 10,000 条优用 offset -过 10,000 条建议改用 offset_token

  1. 控制成本include_clickstream_data=true 会提高成本。在确需查看点击流维度、归一化搜索量或人群分布时开启。

  2. 去重与聚类 如果只想保留核心词，减少相似词噪音，可将 ignore_synonyms 设为 true。

实用场景 ​

  • 挖掘类目池：按产品分类批量获取，快速建立电商站、品牌站或站的类目词库。
  • 筛选高价值投放词：结合 search_volume、cpc、competition 过滤，优定位有商业价值且可投放的词。
  • 识别季节性需求变化：利用 monthly_searches 与 search_volume_trend 判断热度走势，排期和广告预算调整。
  • 分析 SERP 竞争环境：开启 include_serp_info 后查看 SERP 特征和结果量，判断目标词更适合做自然排名还是付费流量。
  • 构建类目页与专题页结构：基于分类词及核心词聚类结果，规划站点信息架构，提升类目页覆盖度与链组织质量。

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

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