> ## 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`) | 네이버 검색 수. |
| 그 밖의 지원 국가 | Google 키워드 플래너(`google_ads`) | 그 나라에서 일어난 모든 언어의 Google 검색 수. |

지원 국가는 `KR`과 Google Ads의 국가 타기팅 대상이며, 예외가 둘 있습니다. `CN`과 `RU`는 Baidu와 Yandex가 검색 대부분을 차지하므로 `422 REGION_UNSUPPORTED`를 반환합니다. 출처가 없는 나라도 같은 오류를 반환합니다. 정확한 목록은 [`GET /v1/capabilities?taskType=KEYWORD_VOLUME`](/ko/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"
    }
  ]
}
```

예시는 12개월 중 두 달만 보여줍니다.

| 필드 | 설명 |
| - | - |
| `country`, `source` | 답한 나라와 데이터 출처. |
| `fetchedAt` | 값을 읽은 시각. |
| `keywords` | 요청한 키워드마다 한 행. 0인 키워드도 포함합니다. |
| `keywords[].searchVolume` | `monthlySearches`의 평균. `0`은 측정할 검색이 없는 키워드입니다. `KR`에서 월별 값을 추정할 수 없으면 `null`입니다(아래 참고). |
| `keywords[].monthlySearches` | 최대 12개의 `{ month, searchVolume }` 항목. `month`는 `YYYY-MM`이고 오래된 달부터 옵니다. 출처에 그 키워드의 추이가 없으면 비어 있습니다. |
| `keywords[].last30Days` | `KR`만: 네이버가 센 최근 30일 검색 수. 다른 나라에서는 `null`입니다. |
| `keywords[].competition` | 광고 경쟁도: `low`, `medium`, `high`, 출처가 주지 않으면 `null`. |

`KR`에서 각 달의 값은 네이버의 30일 검색 수를 네이버 일별 검색어트렌드로 나눠 계산합니다. 트렌드가 그 30일 중 25일 미만을 보고하면 `searchVolume`은 `null`, `monthlySearches`는 빈 배열이고, `last30Days`에는 그대로 검색 수가 실립니다.

## 제한과 오류

* `country`가 없거나 형식이 잘못되었을 때, `keywords` 배열이 비었거나 너무 클 때, 80자를 넘는 키워드가 있을 때는 필드를 명시한 `422 VALIDATION_ERROR`를 반환합니다.
* `CN`, `RU`, 출처가 없는 나라는 `422 REGION_UNSUPPORTED`를 반환합니다.
* `KEYWORD_VOLUME`은 `markdown`, `rawResponse`, `searchQueries`를 무시합니다. `html`과 `analysis`는 `422`로, `citationAnalysis`는 `400`으로 거절합니다. [지원하지 않는 플래그](/ko/engines/response-options.md#지원하지-않는-플래그)를 참고하세요.
* 그 밖의 요청 오류는 [오류](/ko/concepts/errors.md)에 정리되어 있습니다.

## 관련 문서

* 주제를 추적할 프롬프트로 바꾸는 [Prompt Research](/ko/research/prompt-research.md)
* [지역과 위치](/ko/engines/capacity.md)


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