> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 关键词搜索量 API（KEYWORD_VOLUME）

> 获取一个国家最多 100 个关键词的月搜索量，附最近 12 个月数据和广告竞争度。

`KEYWORD_VOLUME` 按每个任务一个国家，返回每个关键词最近 12 个月的平均月搜索量、12 个月的逐月数值以及广告竞争度。

| | |
| - | - |
| `taskType` | `KEYWORD_VOLUME` |
| 输入 | `keywords`（1-100 个，必填）、`country`（必填） |
| 积分 | 每个任务 3 积分，与关键词数量无关 |
| 国家 | 必填。仅限支持的国家，见下文。 |
| 位置 | 不支持（`422 LOCATION_UNSUPPORTED`）。 |

## 请求

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "KEYWORD_VOLUME", "payload": { "keywords": ["sunscreen", "mineral sunscreen"], "country": "US" } }'
```

## 参数

| 字段 | 必填 | 说明 |
| - | - | - |
| `keywords` | 是 | 1 到 100 个关键词的数组，合并空白后每个 1-80 个字符。`KR` 的关键词只能包含字母、数字和空格。 |
| `country` | 是 | 两个字母的国家代码，同时决定数据来源。 |

## 数据来源与国家

| 国家 | 来源（`source`） | 统计内容 |
| - | - | - |
| `KR` | Naver（`naver`） | Naver 上的搜索次数。 |
| 其他所有支持的国家 | Google Keyword Planner（`google_ads`） | 在该国发生的所有 Google 搜索次数，不限语言。 |

支持的国家为 `KR` 和 Google Ads 的国家定位目标，但有两个例外：`CN` 和 `RU` 返回 `422 REGION_UNSUPPORTED`，因为这两个国家的大部分搜索由百度和 Yandex 承担。没有数据来源的国家也返回同样的错误。完整列表请调用 [`GET /v1/capabilities?taskType=KEYWORD_VOLUME`](/zh/engines/capacity#列出各引擎支持的范围) 并读取 `countries.supported`。

## 响应

例如：

```json theme={"theme":"css-variables"}
{
  "country": "US",
  "source": "google_ads",
  "fetchedAt": "2026-10-09T13:05:12.000Z",
  "keywords": [
    {
      "keyword": "sunscreen",
      "searchVolume": 110000,
      "monthlySearches": [
        { "month": "2025-09", "searchVolume": 74000 },
        { "month": "2026-08", "searchVolume": 135000 }
      ],
      "last30Days": null,
      "competition": "high"
    }
  ]
}
```

示例只显示了十二个月中的两个月。

| 字段 | 说明 |
| - | - |
| `country`、`source` | 实际作答的国家和数据来源。 |
| `fetchedAt` | 读取数值的时间。 |
| `keywords` | 每个请求的关键词一行，搜索量为零的也包括在内。 |
| `keywords[].searchVolume` | `monthlySearches` 的平均值。`0` 表示没有可测量的搜索。在 `KR` 中无法估算月度数值时为 `null`（见下文）。 |
| `keywords[].monthlySearches` | 最多 12 个 `{ month, searchVolume }` 条目，`month` 格式为 `YYYY-MM`，从最早的月份开始。来源没有该关键词的数据序列时为空。 |
| `keywords[].last30Days` | 仅 `KR`：Naver 统计的最近 30 天搜索次数。其他国家为 `null`。 |
| `keywords[].competition` | 广告竞争度：`low`、`medium`、`high`，来源未提供时为 `null`。 |

在 `KR` 中，每个月的数值是按 Naver 每日搜索趋势分配 Naver 30 天搜索次数得出的。趋势在这 30 天中覆盖不足 25 天时，`searchVolume` 为 `null`，`monthlySearches` 为空，`last30Days` 仍给出搜索次数。

## 限制与错误

* 缺少或格式错误的 `country`、为空或超出数量的 `keywords` 数组，或超过 80 个字符的关键词，返回 `422 VALIDATION_ERROR` 并指出相应字段。
* `CN`、`RU` 和没有数据来源的国家返回 `422 REGION_UNSUPPORTED`。
* `KEYWORD_VOLUME` 忽略 `markdown`、`rawResponse` 和 `searchQueries`。它以 `422` 拒绝 `html` 和 `analysis`，以 `400` 拒绝 `citationAnalysis`；见[不支持的标志](/zh/engines/response-options.md#不支持的标志)。
* 其他请求错误见[错误](/zh/concepts/errors.md)。

## 相关内容

* [Prompt Research](/zh/research/prompt-research.md)：把一个主题转换为要追踪的提示词
* [地区与位置](/zh/engines/capacity.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.