SeerMarTech API 文档

主题

Google 建议（实时） ​

接口说明 ​

/v3/dataforseo_labs/google/keyword_suggestions/live 用于根据给定的种子，返回该的搜索词建议。

该接口基于搜索算法工作：系统会在数据库中查找所有指定种子词的搜索词，并在词组前、后或中间插词。返回结果中的词序不一定与一致。

因此，这个接口非常适合批量挖掘与核心词的长尾。除本身外，返回结果还可：

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

数据来源： 本平台数据库 搜索算法： 基于指定种子词的匹，返回该词并附加词的搜索词

示例 ​

指定种子：

keyword research

可能返回的建议词：

  • google research keyword
  • how to do keyword research
  • keyword competitor research
  • how to do keyword research for content marketing

请求信息 ​

请求方式： POST请求地址：

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

计费与频率限制 ​

本接口按请求计费。 扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

若按示例响应中的单次费用 USD 0.0101 估算，则：

参考价约 ¥0.1616 / 次

如启用 include_clickstream_data=true，请求费用将翻倍。

频率限制：

  • 每分钟最多 2000 次 API 调用
  • 最多 30 个并发请求

请求体格式 ​

所有 POST 数据均需使用 UTF-8 编码的 JSON，且请求体为 JSON 数组：

json
[
 {
 "keyword": "phone",
 "location_code": 2840,
 "language_name": "English",
 "include_serp_info": true,
 "include_seed_keyword": true,
 "limit": 1
 }
]

请求参数 ​

字段名类型说明
keywordstring填。种子。使用 UTF-8 编码。系统会自动转换为小写。
location_namestring可选。地区完整名称。设置后可不传 location_code。如：United Kingdom。可通过 /v3/dataforseo_labs/locations_and_languages 获取可用地区列表。忽略该字段时，将返回所有可用地区的数据。
location_codeinteger可选。地区编码。设置后可不传 location_name。如：2840。可通过 /v3/dataforseo_labs/locations_and_languages 获取。忽略该字段时，将返回所有可用地区的数据。
language_namestring可选。语言完整名称。设置后可不传 language_code。如：English。可通过 /v3/dataforseo_labs/locations_and_languages 获取。若省略，默认使用该地区下记录数最多的语言。
language_codestring可选。语言编码。设置后可不传 language_name。如：en。可通过 /v3/dataforseo_labs/locations_and_languages 获取。若省略，默认使用该地区下记录数最多的语言。
include_seed_keywordboolean可选。是否在响应中的 seed_keyword_data 返回种子词自身的数据。默认 false。
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。开启后费用翻倍。
exact_matchboolean可选。是否按精确短语匹。设为 true 时，返回结果将你指定的完整短语，但前后仍可能带有词。默认 false。
ignore_synonymsboolean可选。是否忽略高度相似。设为 true 时返回核心，不返回高度相似词。默认 false。
filtersarray可选。结果过滤条件数组。最多支持 8 个过滤条件，条件之间需使用 and / or 连接。
order_byarray可选。排序规则。可按与 filters 相同的字段进行排序，排序方式支持 asc / desc。单次请求最多支持 3 条排序规则。
limitinteger可选。返回的最大数量。默认 100，最大 1000。
offsetinteger可选。结果偏移量。默认 0。例如传 10 表示跳过前 10 条结果。建议在获取不 10,000 条结果时使用。
offset_tokenstring可选。后续分页令牌。适合获取 10,000 条结果时使用，时。若传该字段，则除 limit 外它参数不会生效。
tagstring可选。自定义任务标识，最大长度 255。可用于请求结果对账与任务追踪。

过滤与排序 ​

filters 支持的操作符 ​

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

说明：

  • like / not_like / ilike / not_ilike 支持使用 % 匹任意长度字符串
  • 多个条件之间使用 and / or 连接
  • 最多 8 个过滤条件

order_by 排序说明 ​

  • asc：升序
  • desc：降序
  • 多个排序条件之间使用逗号分隔
  • 单次请求最多支持 3 条排序规则

响应结构 ​

接口返回 JSON 编码数据，最外层 tasks 数组。

顶层字段 ​

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

tasks[] 字段 ​

字段名类型说明
idstring任务唯一标识，UUID 格式。
status_codeinteger任务状态码，范围通常为 10000-60000。
status_messagestring任务状态信息。
timestring任务执行耗时。
costfloat当前任务费用，单位 USD。
result_countintegerresult 数组数量。
patharrayURL 路径。
dataobject回显请求中提交的参数。
resultarray获取结果数组。

result[] 字段 ​

字段名类型说明
se_typestring搜索引擎类型。
seed_keywordstring请求中提交的种子。
seed_keyword_dataobject种子数据。字段结构与 items[] 中单项一致在 include_seed_keyword=true 时返回。
location_codeinteger请求中的地区编码，无数据时为 null。
language_codestring请求中的语言编码，无数据时为 null。
total_countinteger数据库中与请求的总结果数。
items_countinteger当前 items 数组返回的结果数量。
offsetinteger当前偏移量。
offset_tokenstring用于获取后续分页结果的令牌。
itemsarray建议列表。

items[] 字段说明 ​

字段名类型说明
se_typestring搜索引擎类型。
keywordstring返回的建议。
location_codeinteger地区编码。
language_codestring语言编码。
keyword_infoobject基础数据。
clickstream_keyword_infoobject点击流数据在 include_clickstream_data=true 时返回。
keyword_propertiesobject属性信息。
serp_infoobjectSERP 数据在 include_serp_info=true 且数据库存在对应数据时返回。
avg_backlinks_infoobject对应 SERP 前 10 名页面的平均外链数据。
search_intent_infoobject搜索意图信息。
keyword_info_normalized_with_bingobject使用 Bing 数据归一化后的搜索量信息。
keyword_info_normalized_with_clickstreamobject使用点击流数据归一化后的搜索量信息。

keyword_info 字段 ​

字段名类型说明
se_typestring搜索引擎类型。
last_updated_timestring数据更新时间，UTC 格式，如 2019-11-15 12:57:46 +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同义词聚类中的核心。若无可识别同义词则为 null。
synonym_clustering_algorithmstring同义词识别算法。可能值：keyword_metrics、text_processing。
keyword_difficultyinteger难度，范围 0-100。数值越高，自然搜索前 10 越困难。
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。

字段名类型说明
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 字段 ​

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

keyword_info_normalized_with_clickstream 字段 ​

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

认证方式 ​

请在请求头中使用 Bearer Token：

http
Authorization: Bearer smt_live_YOUR_KEY
Content-Type: application/json

请求示例 ​

cURL ​

bash
curl --location --request POST "https://api.seermartech.cn/v3/dataforseo_labs/google/keyword_suggestions/live" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "keyword": "phone",
 "language_name": "English",
 "location_code": 2840,
 "include_serp_info": true,
 "include_seed_keyword": true,
 "limit": 1
 }
]'

Python ​

python
import requests

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

payload = [
 {
 "keyword": "phone",
 "location_name": "United States",
 "language_name": "English",
 "include_serp_info": True,
 "include_seed_keyword": True,
 "limit": 1
 }
]

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

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

if result.get("status_code") == 20000:
 print(result)
else:
 print(f"error. Code: {result.get('status_code')} Message: {result.get('status_message')}")

TypeScript ​

typescript
import axios from "axios";

const postArray = [
 {
 keyword: "phone",
 location_code: 2840,
 language_name: "English",
 include_serp_info: true,
 include_seed_keyword: true,
 limit: 1
 }
];

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

响应示例 ​

json
{
 "version": "0.1.20240801",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.2704 sec.",
 "cost": 0.0101,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "dataforseo_labs",
 "function": "keyword_suggestions",
 "se_type": "google",
 "keyword": "phone",
 "location_code": 2840,
 "language_code": "en",
 "include_serp_info": true,
 "include_seed_keyword": true,
 "limit": 1
 },
 "result": [
 {
 "seed_keyword_data": {
 "keyword_info": {
 "monthly_searches": [],
 "search_volume_trend": {
 "monthly": 22,
 "quarterly": 22,
 "yearly": 0
 }
 }
 },
 "clickstream_keyword_info": null,
 "serp_info": {
 "se_type": "google",
 "check_url": "https://www.google.com/search?q=phone&num=100&hl=en&gl=US&gws_rd=cr&ie=UTF-8&oe=UTF-8&glp=1&uule=w+CAIQIFISCQs2MuSEtepUEUK33kOSuTsc",
 "serp_item_types": [],
 "se_results_count": 19880000000,
 "last_updated_time": "2024-07-15 00:43:34 +00:00",
 "previous_updated_time": "2024-05-18 22:29:28 +00:00"
 },
 "keyword_properties": {
 "se_type": "google",
 "core_keyword": null,
 "synonym_clustering_algorithm": "text_processing",
 "keyword_difficulty": 83,
 "detected_language": "en",
 "is_another_language": false,
 "words_count": 1
 },
 "search_intent_info": {
 "se_type": "google",
 "main_intent": "navigational",
 "foreign_intent": [],
 "last_updated_time": "2023-03-02 03:54:21 +00:00"
 },
 "avg_backlinks_info": {
 "se_type": "google",
 "backlinks": 6835.7,
 "dofollow": 3775.6,
 "referring_pages": 5352.2,
 "referring_domains": 1100.3,
 "referring_main_domains": 955.1,
 "rank": 369.3,
 "main_domain_rank": 681.2,
 "last_updated_time": "2024-07-14 21:43:39 +00:00"
 },
 "keyword_info_normalized_with_bing": {
 "last_updated_time": "2024-08-17 01:41:37 +00:00",
 "search_volume": 324416,
 "is_normalized": true,
 "monthly_searches": []
 },
 "keyword_info_normalized_with_clickstream": {
 "last_updated_time": "2024-08-11 13:24:34 +00:00",
 "search_volume": 368000,
 "is_normalized": true,
 "monthly_searches": []
 }
 },
 {
 "location_code": 2840,
 "language_code": "en",
 "total_count": 3488300,
 "items_count": 1,
 "offset": 0,
 "offset_token": "eyJDdXJyZW50T2Zmc2V0IjoxLCJSZXF1ZXN0RGF0YSI6eyJrZXl3b3JkIjoicGhvbmUiLCJpbmNsdWRlX3NlZWRfa2V5d29yZCI6dHJ1ZSwiZnVsbF9tYXRjaCI6ZmFsc2UsImxvYWRfc2VycF9pbmZvIjp0cnVlLCJzZWFyY2hfYWZ0ZXJfdG9rZW4iOm51bGwsImlnbm9yZV9zeW5vbnltcyI6ZmFsc2UsImxhbmd1YWdlIjoiZW4iLCJzZWFyY2hfZW5naW5lIjoiZ29vZ2xlIiwibG9jYXRpb24iOjI4NDAsInVzZV9uZXdfY2F0ZWdvcmllcyI6dHJ1ZSwib3JkZXJfYnkiOnsib3JkZXJfZmllbGQiOiJrZXl3b3JkX2luZm8uc2VhcmNoX3ZvbHVtZSIsIm9yZGVyX3R5cGUiOiJEZXNjIiwibmV4dCI6bnVsbH0sImxpbWl0IjoxLCJvZmZzZXQiOjAsImFpZCI6MTUzNX0sIlJhd1F1ZXJ5IjpudWxsLCJJZCI6Ijc0MjcwOGQwLWZjMjgtNDMwZi04NzA3LTRhZmVjYmJkNDgwZCIsIlNlYXJjaEFmdGVyRGF0YSI6WzE4MzAwMDAsIjkwYzI4YjVjLWVmNWQtNGUwMi04MGU2LTBkYThkZjQyZDY0NyJdfQ==",
 "items": [
 {
 "keyword_info": {
 "monthly_searches": [],
 "search_volume_trend": {
 "monthly": 22,
 "quarterly": 22,
 "yearly": 0
 }
 },
 "clickstream_keyword_info": null,
 "keyword_properties": {
 "se_type": "google",
 "core_keyword": null,
 "synonym_clustering_algorithm": "text_processing",
 "keyword_difficulty": 0,
 "detected_language": "en",
 "is_another_language": false,
 "words_count": 3
 },
 "serp_info": {
 "se_type": "google",
 "check_url": "https://www.google.com/search?q=boost%20cell%20phone&num=100&hl=en&gl=US&gws_rd=cr&ie=UTF-8&oe=UTF-8&glp=1&uule=w+CAIQIFISCQs2MuSEtepUEUK33kOSuTsc",
 "serp_item_types": [],
 "se_results_count": 115000000,
 "last_updated_time": "2024-08-04 08:25:36 +00:00",
 "previous_updated_time": "2024-06-22 17:54:36 +00:00"
 },
 "avg_backlinks_info": {
 "se_type": "google",
 "backlinks": 4739.3,
 "dofollow": 2334.9,
 "referring_pages": 4121.3,
 "referring_domains": 210.3,
 "referring_main_domains": 184.2,
 "rank": 113.1,
 "main_domain_rank": 512.4,
 "last_updated_time": "2024-08-04 08:25:38 +00:00"
 },
 "search_intent_info": {
 "se_type": "google",
 "main_intent": "transactional",
 "foreign_intent": null,
 "last_updated_time": "2023-12-14 04:27:21 +00:00"
 },
 "keyword_info_normalized_with_bing": {
 "last_updated_time": "2024-08-17 06:05:32 +00:00",
 "search_volume": 2893,
 "is_normalized": true,
 "monthly_searches": []
 },
 "keyword_info_normalized_with_clickstream": {
 "last_updated_time": "2024-08-17 06:05:32 +00:00",
 "search_volume": 197,
 "is_normalized": true,
 "monthly_searches": []
 }
 }
 ]
 }
 ]
 }
 ]
}

错误处理 ​

建议对以下两层状态进行同时处理：

  1. 顶层状态
  • status_code
  • status_message
  1. 任务层状态
  • tasks[].status_code
  • tasks[].status_message

完整错误码与状态说明可参考 /v3/appendix/errors。 生产环境中建议为时、参数错误、限流、空结果、分页令牌失效等建立专门处理逻辑。

使用建议 ​

  • 需要获取种子词本身的数据时，开启 include_seed_keyword
  • 需要分析 SERP 特征时，开启 include_serp_info
  • 需要更真实的搜索需求估算时，可开启 include_clickstream_data，但应注意费用翻倍
  • 获取海量结果时优使用 offset_token，不要依赖大 offset
  • 若要减少高度相似词干扰，可设置 ignore_synonyms=true

实用场景 ​

  • 挖掘长尾词库：围绕核心词批量扩展该词的搜索词，快速搭建选题池与 SEO 词库。
  • 筛选高潜力：结合 search_volume、cpc、competition 和 keyword_difficulty，优找出流量价值高且优化难度可控的词。
  • 分析搜索意图：利用 search_intent_info 区分信息型、商业型、交易型，提升页与落地页匹度。
  • 识别 SERP 机会位：通过 serp_info.serp_item_types 判断是否存在精选摘要、本地、问答等展示位，制定抢占策略。
  • 评估竞争强度：结合 avg_backlinks_info 与难度，预估首页所需的与外链，支持 SEO 资源分。

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

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