키워드 검색량 API (KEYWORD_VOLUME)

KEYWORD_VOLUME은 태스크마다 한 나라에 대해 키워드별 최근 12개월 월평균 검색량, 12개월 각각의 값, 광고 경쟁도를 반환합니다.


`taskType`	`KEYWORD_VOLUME`
입력	`keywords`(1~100개, 필수), `country`(필수)
크레딧	키워드 수와 관계없이 태스크당 3
국가	필수. 지원 국가만 받습니다. 아래를 참고하세요.
위치	지원하지 않습니다(`422 LOCATION_UNSUPPORTED`).

요청

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을 호출해 countries.supported를 읽으세요.

응답

예:

{
  "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으로 거절합니다. 지원하지 않는 플래그를 참고하세요.
그 밖의 요청 오류는 오류에 정리되어 있습니다.

시작하기

핵심 개념

답변 엔진

검색과 웹 데이터

요청 옵션

리서치

GEO 모니터링

계정과 데이터

키워드 검색량 API (KEYWORD_VOLUME)

요청

파라미터

데이터 출처와 국가

응답

제한과 오류

관련 문서

​요청

​파라미터

​데이터 출처와 국가

​응답

​제한과 오류

​관련 문서

요청

파라미터

데이터 출처와 국가

응답

제한과 오류

관련 문서