按产品类别获取

POST /v3/dataforseo_labs/google/keywords_for_categories/live

本接口通过 Google 搜索数据，根据指定的产品或服务类别返回。每个最近一个月的搜索量、过去 12 个月的搜索量趋势、平均每次点击费用（CPC）、竞争程度及 SEO 数据。

请求方法与路径：

http

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

计费与调用限制

每次请求均会产生费用。
参考价约 ¥0.0742 / 次（示例费用按原始示例金额折算供参考）。
启用 include_clickstream_data 后，费用按普通请求的 2 倍计算。
实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。
请求体使用 UTF-8 编码的 JSON 格式。
每个 Live API 请求最多 1 个任务。平台限流以认证说明中的 30/60/120 次/分钟规则为准。
同时进行的请求数量最多为 30 个。
可通过 limit、offset 或 offset_token 控制返回结果的数量和分页位置。

认证方式

请求时使用 Bearer Token：

http

Authorization: Bearer smt_live_YOUR_KEY
Content-Type: application/json

请求参数

请求体是 JSON 数组，数组中最多一个任务对象。

参数	类型	填	说明
`category_codes`	array	是	产品和服务类别编码。最多指定 20 个类别。
`location_name`	string	条件填	地理位置完整名称。未指定 `location_code` 时填。
`location_code`	integer	条件填	地理位置唯一编码。未指定 `location_name` 时填。在 `location_name` 与 `location_code` 中选择一个。
`language_name`	string	条件填	语言完整名称。未指定 `language_code` 时填。
`language_code`	string	条件填	语言唯一编码。未指定 `language_name` 时填。在 `language_name` 与 `language_code` 中选择一个。
`category_intersection`	boolean	否	类别匹方式。`true` 表示返回同时属于所有指定类别的；`false` 表示返回属于任意指定类别的。默认值为 `true`。
`include_serp_info`	boolean	否	是否返回每个的 SERP 数据搜索结果数量、查询 URL 和 SERP 特征。默认值为 `false`。
`include_clickstream_data`	boolean	否	是否返回基于点击流计算的指标。设为 `true` 时，会返回 `clickstream_keyword_info`、`keyword_info_normalized_with_clickstream` 和 `keyword_info_normalized_with_bing`。默认值为 `false`。启用后按 2 倍费用计费。
`ignore_synonyms`	boolean	否	是否忽略高度相似的。设为 `true` 时返回核心，并排除高度相似。默认值为 `false`。
`limit`	integer	否	返回的最大数量。默认值为 `100`，最大值为 `1000`。
`offset`	integer	否	结果偏移量。例如设置为 `10`，则跳过前 10 条结果。默认值为 `0`。建议在结果总量不 10,000 条时使用。
`offset_token`	string	否	后续请求使用的分页令牌。适用于获取 10,000 条结果的场景。指定该参数后，除 `limit` 外的请求参数将不参与任务处理。
`filters`	array	否	结果过滤条件。最多设置 8 个过滤器，多个条件之间使用 `and` 或 `or`。
`order_by`	array	否	结果排序规则。最多设置 3 条排序规则。排序方向使用 `asc` 或 `desc`。
`tag`	string	否	用户自定义任务标识，最长 255 个字符。响应中的 `data` 对象会返回该值。

可用位置和语言

可通过以下接口获取支持的地理位置和语言：

http

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

示例：

json

{
  "location_name": "United Kingdom",
  "location_code": 2840,
  "language_name": "English",
  "language_code": "en"
}

类别编码

category_codes 中的编码应使用平台支持的产品或服务类别编码。一个请求最多指定 20 个类别。

示例：

json

[12191, 12193]

过滤器

过滤器通常由“字段、运算符、值”组成：

json

[
  ["keyword_info.search_volume", ">", 100],
  "and",
  ["keyword_info.competition_level", "=", "LOW"]
]

支持的运算符：

text

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

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

排序规则

排序规则使用字段名和排序方向：

json

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

asc：升序
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],
      "location_name": "United States",
      "language_name": "English",
      "filters": [
        ["keyword_info.search_volume", ">", 10]
      ],
      "include_serp_info": true,
      "limit": 3
    }
  ]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/dataforseo_labs/google/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": [
            ["keyword_info.search_volume", ">", 10]
        ],
        "limit": 3,
    }
]

response = requests.post(url, headers=headers, json=payload)
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 payload = [
  {
    category_codes: [12191, 12193],
    location_name: "United States",
    language_name: "English",
    filters: [
      ["keyword_info.search_volume", ">", 10],
    ],
    include_serp_info: true,
    limit: 3,
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/dataforseo_labs/google/keywords_for_categories/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 数组。

json

{
  "version": "0.1.20240801",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.1943 sec.",
  "cost": 0.0742,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "40ceb199-97df-4dfd-832a-8d2b75cedfba",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.1801 sec.",
      "cost": 0.0742,
      "result_count": 1,
      "path": [
        "v3",
        "dataforseo_labs",
        "google",
        "keywords_for_categories",
        "live"
      ],
      "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": [
        {
          "se_type": "google",
          "seed_categories": [12191, 12193],
          "location_code": 2840,
          "language_code": "en",
          "total_count": 11982,
          "items_count": 3,
          "offset": 0,
          "offset_token": "下一页使用的分页令牌",
          "items": [
            {
              "se_type": "google",
              "keyword": "dell optiplex desktop",
              "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,
                "low_top_of_page_bid": 0.63,
                "high_top_of_page_bid": 1.54,
                "categories": [12191, 12193],
                "monthly_searches": [
                  {
                    "year": 2024,
                    "month": 7,
                    "search_volume": 18100
                  }
                ],
                "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=dell%20optiplex%20desktop",
                "serp_item_types": ["organic", "paid", "people_also_ask"],
                "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"
              }
            }
          ]
        }
      ]
    }
  ]
}

> 说明：示例中的 cost 用于展示字段结构，扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

顶层响应字段

字段	类型	说明
`version`	string	当前 API 版本。
`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	本次请求对应的 API 路径。
`data`	object	请求中提交的任务参数。
`result`	array	任务结果数组。

结果字段

字段	类型	说明
`se_type`	string	搜索引擎类型，通常为 `google`。
`seed_categories`	array	请求中提交的类别编码。
`location_code`	integer	地理位置编码。
`language_code`	string	语言编码。
`total_count`	integer	数据库中符合条件的结果总数。
`items_count`	integer	本次 `items` 数组返回的结果数量。
`offset`	integer	当前结果偏移量。
`offset_token`	string	获取后续结果使用的分页令牌。每个后续任务对应唯一令牌。
`items`	array	及数据。

`items` 字段

字段	类型	说明
`se_type`	string	搜索引擎类型。
`keyword`	string	返回的。
`location_code`	integer	地理位置编码。
`language_code`	string	语言编码。
`keyword_info`	object	搜索量、竞争度和 CPC 等指标。
`clickstream_keyword_info`	object / null	点击流数据。在 `include_clickstream_data=true` 时返回。
`keyword_properties`	object	附加信息。
`serp_info`	object / null	SERP 数据。在 `include_serp_info=true` 且存在对应数据时返回。
`avg_backlinks_info`	object	排名前 10 个自然结果页面的平均外链数据。
`search_intent_info`	object	搜索意图数据。
`keyword_info_normalized_with_bing`	object	使用 Bing 搜索量归一化后的数据。
`keyword_info_normalized_with_clickstream`	object	使用点击流数据归一化后的数据。

`keyword_info` 字段

字段	类型	说明
`se_type`	string	搜索引擎类型。
`last_updated_time`	string	数据更新时间，UTC 格式：`yyyy-mm-dd hh-mm-ss +00:00`。
`competition`	float	Google Ads 竞争度，取值范围为 `0`–`1`。
`competition_level`	string / null	付费搜索结果中的竞争等级，可选值为 `LOW`、`MEDIUM`、`HIGH`；未知时为 `null`。
`cpc`	float	历史平均每次点击费用。
`search_volume`	integer	Google 每月平均搜索量。
`low_top_of_page_bid`	float	广告展示在首页顶部所需的较低参考出价。
`high_top_of_page_bid`	float	广告展示在首页顶部所需的较高参考出价。
`categories`	array	所属的产品和服务类别。
`monthly_searches`	array	最近 12 个月的月度搜索量。
`search_volume_trend`	object	搜索量趋势变化。

`monthly_searches` 字段

字段	类型	说明
`year`	integer	年份。
`month`	integer	月份。
`search_volume`	integer	指定月份的平均搜索量。

`search_volume_trend` 字段

字段	类型	说明
`monthly`	integer	相比上个月的搜索量变化百分比。
`quarterly`	integer	相比上一季度的搜索量变化百分比。
`yearly`	integer	相比上一年的搜索量变化百分比。

`clickstream_keyword_info` 字段

启用 include_clickstream_data=true 后返回。

字段	类型	说明
`search_volume`	integer	基于点击流数据计算的月平均搜索量。
`last_updated_time`	string	点击流数据更新时间，UTC 格式。
`gender_distribution`	object	按性别划分的估算点击流指标分布。
`age_distribution`	object	按年龄划分的估算点击流指标分布。
`monthly_searches`	array	按月份划分的点击流搜索量。

`gender_distribution`

字段	类型	说明
`female`	integer	点击流数据集中的女性用户数量。
`male`	integer	点击流数据集中的男性用户数量。

`age_distribution`

字段	类型	说明
`18-24`	integer	18–24 岁用户数量。
`25-34`	integer	25–34 岁用户数量。
`35-44`	integer	35–44 岁用户数量。
`45-54`	integer	45–54 岁用户数量。
`55-64`	integer	55–64 岁用户数量。

`keyword_properties` 字段

字段	类型	说明
`se_type`	string	搜索引擎类型。
`core_keyword`	string / null	同义词分组中的核心。无法识别同义词时为 `null`。
`synonym_clustering_algorithm`	string / null	同义词聚类算法。可选值为 `keyword_metrics` 和 `text_processing`。
`keyword_difficulty`	integer	难度，取值范围为 `0`–`100`，用于估算自然搜索结果前 10 名的难度。
`detected_language`	string / null	系统识别出的语言。
`is_another_language`	boolean / null	识别语言是否与请求中指定的语言不同。
`words_count`	integer	的单词数量。

`serp_info` 字段

未设置 include_serp_info=true，或数据库中没有该的 SERP 数据时，serp_info 为 null。

字段	类型	说明
`se_type`	string	搜索引擎类型。
`check_url`	string	可直接访问的搜索结果页 URL，用于核验 SERP 数据。
`serp_item_types`	array	SERP 中出现的结果类型。
`se_results_count`	string / integer	该对应的搜索结果数量。
`last_updated_time`	string	SERP 数据最近更新时间，UTC 格式。
`previous_updated_time`	string	SERP 数据上一次更新时间，UTC 格式。

支持识别的 SERP 类型：

text

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

`avg_backlinks_info` 字段

该对象提供自然搜索结果前 10 个页面的平均外链和排名指标。

字段	类型	说明
`se_type`	string	搜索引擎类型。
`backlinks`	float	平均外链数量。
`dofollow`	float	平均 Dofollow 链接数量。
`referring_pages`	float	平均引用页面数量。
`referring_domains`	float	平均引用域名数量。
`referring_main_domains`	float	平均引用主域名数量。
`rank`	float	平均页面排名。
`main_domain_rank`	float	平均主域名排名。
`last_updated_time`	string	外链数据更新时间，UTC 格式。

`search_intent_info` 字段

字段	类型	说明
`se_type`	string	搜索引擎类型，通常为 `google`。
`main_intent`	string	主要搜索意图。可选值：`informational`、`navigational`、`commercial`、`transactional`。
`foreign_intent`	array	补搜索意图，取值同 `main_intent`。
`last_updated_time`	string	搜索意图数据更新时间，UTC 格式。

归一化数据

`keyword_info_normalized_with_bing`

字段	类型	说明
`last_updated_time`	string	数据集更新时间。
`search_volume`	integer	使用 Bing 搜索量归一化后的当前搜索量。
`is_normalized`	boolean	是否已使用 Bing 数据归一化。
`monthly_searches`	array	归一化后的月度搜索量， `year`、`month` 和 `search_volume`。

`keyword_info_normalized_with_clickstream`

字段	类型	说明
`last_updated_time`	string	数据集更新时间。
`search_volume`	integer	使用点击流数据归一化后的当前搜索量。
`is_normalized`	boolean	是否已使用点击流数据归一化。
`monthly_searches`	array	归一化后的月度搜索量， `year`、`month` 和 `search_volume`。

分页说明

当响应中的 offset_token 不为空时，可将用于后续请求：

json

[
  {
    "category_codes": [12191, 12193],
    "location_code": 2840,
    "language_code": "en",
    "offset_token": "上一次响应返回的 offset_token",
    "limit": 100
  }
]

使用 offset_token 时：

limit 参数会继续生效；
任务参数将以初始任务参数为准；
每个后续任务的 offset_token 都是唯一的；
获取 10,000 条结果时，建议使用 offset_token，而不是 offset。

错误处理

建议根据顶层和任务级别的 status_code 判断请求是否成功：

json

{
  "status_code": 20000,
  "status_message": "Ok."
}

20000：请求成功。
状态码：请求或任务处理失败，应结合 status_message 定位问题。
应用程序应同时检查 tasks_error 和每个任务对象中的 status_code。

实用场景

挖掘产品类别：根据多个产品类别获取交集或并集，扩 SEO 词库并发现新的主题。
筛选高需求低竞争词：使用 filters 过滤搜索量、竞争度和 CPC，优识别更自然排名或广告投放价值的。
制定与落地页计划：结合 search_volume_trend 和 12 个月搜索量，判断季节性并安排发布时间。
评估商业价值：分析 cpc、competition_level 和 search_intent_info，区分信息型、商业型和交易型。
评估 SERP 竞争环境：启用 include_serp_info 和 avg_backlinks_info，分析 SERP 特征及排名页面的外链强度，为 SEO 难度评估和链接建设提供依据。

按产品类别获取 ​

计费与调用限制 ​

认证方式 ​

请求参数 ​

可用位置和语言 ​

类别编码 ​

过滤器 ​

排序规则 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应结构 ​

顶层响应字段 ​

任务字段 ​

结果字段 ​

items 字段 ​

keyword_info 字段 ​

monthly_searches 字段 ​

search_volume_trend 字段 ​

clickstream_keyword_info 字段 ​

gender_distribution ​

age_distribution ​

keyword_properties 字段 ​

serp_info 字段 ​

avg_backlinks_info 字段 ​

search_intent_info 字段 ​

归一化数据 ​

keyword_info_normalized_with_bing ​

keyword_info_normalized_with_clickstream ​

分页说明 ​

按产品类别获取

计费与调用限制

认证方式

请求参数

可用位置和语言

类别编码

过滤器

排序规则

请求示例

cURL

Python

TypeScript

响应结构

顶层响应字段

任务字段

结果字段

`items` 字段

`keyword_info` 字段

`monthly_searches` 字段

`search_volume_trend` 字段

`clickstream_keyword_info` 字段

`gender_distribution`

`age_distribution`

`keyword_properties` 字段

`serp_info` 字段

`avg_backlinks_info` 字段

`search_intent_info` 字段

归一化数据

`keyword_info_normalized_with_bing`

`keyword_info_normalized_with_clickstream`

分页说明