按类别获取（Legacy）

GET /v3/dataforseo_labs/locations_and_languages

本接口使用 POST /v3/dataforseo_labs/keywords_for_categories/live，根据指定的商品或服务类别返回。响应最近一个月的搜索量、过去 12 个月的搜索趋势、竞争度、每次点击费用（CPC），以及广告展示次数、点击次数和 CPC 的最小值、最大值与平均值。

> 本接口为旧版（Legacy）接口。平台 API 已于 2022-03-19 更新本平台 Labs API 的请求与响应结构，但仍继续支持本容版本。新版本请参考对应的 Google 类别接口文档。

请求信息

请求方法：POST
请求地址：https://api.seermartech.cn/v3/dataforseo_labs/keywords_for_categories/live
请求格式：application/json，UTF-8 编码
请求体格式：JSON 数组，最多可提交一个或多个任务平台限流以认证说明中的 30/60/120 次/分钟规则为准
结果控制：支持设置返回数量、偏移量、过滤条件和排序规则

每个任务都放在请求数组中，例如：

json

[
  {
    "category_codes": [12191, 12193],
    "location_name": "United States",
    "language_name": "English",
    "limit": 5
  }
]

计费说明

每次请求均会产生费用。参考价以本平台为准，扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数

参数	类型	填	说明
`category_codes`	array	是	商品或服务类别编码。最多指定 20 个类别。可通过 Google Ads 商品与服务类别列表获取完整编码。
`location_name`	string	条件填	地理位置完整名称。未指定 `location_code` 时填。`location_name` 与 `location_code` 至少指定一个。示例：`United Kingdom`。
`location_code`	integer	条件填	地理位置唯一编码。未指定 `location_name` 时填。`location_name` 与 `location_code` 至少指定一个。示例：`2840`。
`language_name`	string	条件填	语言完整名称。未指定 `language_code` 时填。`language_name` 与 `language_code` 至少指定一个。示例：`English`。
`language_code`	string	条件填	语言唯一编码。未指定 `language_name` 时填。`language_name` 与 `language_code` 至少指定一个。示例：`en`。
`category_intersection`	boolean	否	是否返回同时属于所有指定类别的。默认值：`false`。
`include_serp_info`	boolean	否	是否返回每个的 SERP 数据搜索结果数量、SERP 检查地址和 SERP 特征。默认值：`false`。
`limit`	integer	否	返回的最大数量。默认值：`700`，最大值：`1000`。
`offset`	integer	否	结果偏移量，默认值：`0`。例如设置为 `10` 时，跳过前 10 条结果。
`offset_token`	string	否	后续分页令牌。响应中会返回该字段，可用于获取同一任务的后续结果。指定该参数后，除 `limit` 外的参数将不会参与任务处理。
`filters`	array	否	结果过滤条件。最多支持 8 个过滤条件，条件之间使用 `and` 或 `or` 连接。
`order_by`	array	否	结果排序规则。最多设置 3 条排序规则，可使用与 `filters` 相同的字段和排序表达式。
`tag`	string	否	自定义任务标识，用于请求和响应，最长 255 个字符。响应的 `data` 对象中会返回该值。

可通过以下接口查询可用的地理位置和语言：

text

/v3/dataforseo_labs/locations_and_languages

过滤条件

支持以下运算符：

text

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

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

示例：

json

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

排序规则

排序规则使用以下格式：

json

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

asc：升序
desc：降序

多个排序规则之间使用逗号分隔。单次请求最多设置 3 条排序规则。

响应结构

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

顶层字段

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	通用状态码。完整错误码请参考错误码文档。
`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	请求 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	及数据。

当结果数量单次请求限制时，使用响应中的 offset_token 请求下一页。每个后续任务返回的令牌均唯一性。

`items` 字段

字段	类型	说明
`keyword`	string	返回的。
`location_code`	integer	地理位置编码。
`language_code`	string	语言编码。
`keyword_info`	object	搜索数据。
`keyword_properties`	object	附加信息。
`impressions_info`	object	广告展示与点击数据。
`bing_keyword_info`	object	基于 Bing Ads 的数据。部分地理位置和语言不提供此数据。
`serp_info`	object	SERP 数据。未启用 `include_serp_info`，或数据库中没有对应 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	平均月搜索量，即指定地区该在搜索引擎上的估算搜索次数。
`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 名的难度。该指标会综合分析 SERP 前 10 个页面的链接特征等数据。

`impressions_info`

该对象中的 daily_impressions 数据可作为搜索量数据的补参考。系统使用 999 的出价来尽量降低账户因素对展示次数估算的影响。

字段	类型	说明
`last_updated_time`	string	展示数据更新时间，UTC 格式。
`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	在出价为 `999` 时估算出的最低 CPC。该值不是 CPC。
`cpc_max`	float	在出价为 `999` 时估算出的最高 CPC。该值不是 CPC。
`cpc_average`	float	在出价为 `999` 时估算出的平均 CPC。该值不是 CPC。
`daily_impressions_min`	float / null	估算的最低日展示次数。
`daily_impressions_max`	float / null	估算的最高日展示次数。
`daily_impressions_average`	float / null	估算的平均日展示次数。
`daily_clicks_min`	float / null	最低日点击次数。
`daily_clicks_max`	float / null	最高日点击次数。
`daily_clicks_average`	float / null	平均日点击次数。
`daily_cost_min`	float / null	最低日广告费用。
`daily_cost_max`	float / null	最高日广告费用。
`daily_cost_average`	float / null	平均日广告费用。

cpc_min、cpc_max 和 cpc_average 是基于指定出价的估算值； CPC 应读取 keyword_info.cpc。

`bing_keyword_info`

Bing 数据适用于有限的地理位置和语言组合。

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

monthly_searches 数组：

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

`serp_info`

当请求参数 include_serp_info 设置为 true 且数据库中存在对应数据时返回，否则为 null。

字段	类型	说明
`check_url`	string	对应的搜索结果页地址，可用于核验返回结果。
`serp_item_types`	array	SERP 中出现的结果类型。
`se_results_count`	string / integer	该对应的搜索结果数量。
`last_updated_time`	string	SERP 数据更新时间，UTC 格式。
`previous_updated_time`	string / null	上一次 SERP 数据更新时间。

可能出现的 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 类型返回。

请求示例

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, 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],
    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
  .post(
    "https://api.seermartech.cn/v3/dataforseo_labs/keywords_for_categories/live",
    payload,
    {
      headers: {
        Authorization: "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
      },
    }
  )
  .then((response) => {
    if (response.data.status_code === 20000) {
      console.log(response.data);
    } else {
      console.error(
        `请求失败，状态码：${response.data.status_code}，消息：${response.data.status_message}`
      );
    }
  })
  .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": "task-uuid-example",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "5.2265 sec.",
      "cost": 0.0105,
      "result_count": 1,
      "data": {
        "api": "dataforseo_labs",
        "function": "keywords_for_categories",
        "category_codes": [12191, 12193],
        "language_name": "English",
        "location_code": 2840,
        "include_serp_info": true,
        "limit": 5
      },
      "result": [
        {
          "location_code": 2840,
          "language_code": "en",
          "total_count": 574,
          "items_count": 1,
          "offset": 0,
          "offset_token": "NEXT_PAGE_TOKEN",
          "items": [
            {
              "keyword": "dell optiplex 9020 specs",
              "location_code": 2840,
              "language_code": "en",
              "keyword_info": {
                "last_updated_time": "2022-01-24 08:38:22 +00:00",
                "competition": 1,
                "cpc": 1.065635,
                "search_volume": 880,
                "category_codes": [12191, 12193],
                "monthly_searches": [
                  {
                    "year": 2022,
                    "month": 1,
                    "search_volume": 880
                  }
                ]
              },
              "keyword_properties": {
                "core_keyword": null,
                "keyword_difficulty": 32
              },
              "impressions_info": {
                "last_updated_time": "2021-12-30 09:39:05 +00:00",
                "bid": 999,
                "match_type": "exact",
                "ad_position_min": 1.11,
                "ad_position_max": 1,
                "ad_position_average": 1.06,
                "cpc_min": 21.93,
                "cpc_max": 26.81,
                "cpc_average": 24.37,
                "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-19 16:31:05 +00:00",
                "search_volume": 150,
                "monthly_searches": []
              },
              "serp_info": {
                "check_url": "https://www.google.com/search?q=dell%20optiplex%209020%20specs",
                "serp_item_types": ["organic", "people_also_ask"],
                "se_results_count": 206000,
                "last_updated_time": "2021-12-18 21:18:45 +00:00",
                "previous_updated_time": null
              }
            }
          ]
        }
      ]
    }
  ]
}

错误处理

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

20000：请求成功。
状态码：请求或任务处理异常，应结合 status_message 定位问题。
tasks_error：表示任务数组中返回错误的任务数量。

实用场景

挖掘指定商品类别的，批量发现搜索词，为类目页、产品页和页建立池。
筛选高搜索量且低竞争度的，优安排生产和自然排名优化资源。
分析的月度搜索趋势，识别季节性需求变化，优化选题日历和营销活动排期。
评估的广告展示与点击潜力，结合日展示次数、点击次数和 CPC 估算投放价值。
核验目标的 SERP 结构，识别精选摘要、本地结果、购物结果等搜索特征，制定匹的页面和策略。

按类别获取（Legacy） ​

请求信息 ​

计费说明 ​

请求参数 ​

过滤条件 ​

排序规则 ​

响应结构 ​

顶层字段 ​

任务字段 ​

result 字段 ​

items 字段 ​

keyword_info ​

keyword_properties ​

impressions_info ​

bing_keyword_info ​

serp_info ​

请求示例 ​

curl ​

Python ​

TypeScript ​

响应示例 ​

错误处理 ​

实用场景 ​

按类别获取（Legacy）

请求信息

计费说明

请求参数

过滤条件

排序规则

响应结构

顶层字段

任务字段

`result` 字段

`items` 字段

`keyword_info`

`keyword_properties`

`impressions_info`

`bing_keyword_info`

`serp_info`

请求示例

curl

Python

TypeScript

响应示例

错误处理

实用场景