---
title: 월별 검색량 조회 API(/keyword_info/monthly_volume) 활용 가이드
description: 키워드 1개의 월별 검색량만 받는 API의 요청·응답·과금과 처리할 때 주의할 점을 설명합니다.
url: "https://kr.listeningmind.com/data-api/api-reference/keyword-info-monthly-volume-api/"
updated: "2026-11-05"
category: API 레퍼런스
---

# 월별 검색량 조회 API(/keyword_info/monthly_volume) 활용 가이드

키워드 1개의 월별 검색량만 받는 API입니다. 시즌 그래프를 그리거나 특정 키워드의 추이만 확인할 때, `/keyword_info`의 다른 지표 없이 시계열만 가볍게 받을 수 있습니다.

## 핵심 특징 요약

| **항목** | **상세** |
| --- | --- |
| 엔드포인트 | POST /keyword_info/monthly_volume |
| 요청 키워드 수 | 1개 (문자열 · 배열 아님) |
| 반환 형식 | data: objects[] (keyword, monthly_volume). 표기 변형 행이 함께 올 수 있습니다 |
| 반환 기간 | 최대 48개월 |
| 지원 국가(gl) | kr (한국) / jp (일본) / us (미국) |
| 과금 방식 | 키워드 1개 = 호출 1회, 1 크레딧 · 출력 과금 없음 · 실제 비용은 응답의 total_cost 로 확인 |
| 사용 가능한 키 | DaaS API Key 전용 |

## 언제 이 API를 쓰나요

| **상황** | **쓸 API** |
| --- | --- |
| 키워드 1개의 월별 추이만 필요하다 | /keyword_info/monthly_volume |
| 키워드 여러 개의 월별 추이가 필요하다 | /keyword_info (data_type: ads_info) — 한 번에 최대 1,000개까지 보낼 수 있고, 비용은 키워드 수만큼 듭니다(키워드 1개당 1 크레딧). 광고 지표도 함께 오고, 요청하지 않은 표기 변형 행이 섞일 수 있습니다. 입력 키워드와 공백·대소문자를 무시해 일치하는 행만 쓰세요 |
| 검색 의도·인구통계(kr만)·SERP 노출도 함께 필요하다 | /keyword_info (data_type: all) — 키워드당 10 크레딧 |

API 명세 기준으로 이 API의 값은 [키워드 조회 API](https://kr.listeningmind.com/data-api/api-reference/keyword-info-api/) 응답의 `monthly_volume`과 같습니다. 키워드가 여러 개라면 호출을 나누지 말고 `ads_info`로 묶으세요. 호출 수는 줄지만 크레딧은 키워드 수만큼 듭니다(1,000개면 1,000 크레딧).

## 요청 (Request)

| **파라미터** | **타입** | **필수** | **설명** |
| --- | --- | --- | --- |
| keyword | string | Y | 조회할 키워드 1개 |
| gl | string | Y | 국가 코드: "kr" / "jp" / "us" |
| response_format | string | N | json(기본) 또는 download_url. download_url 이면 data 대신 파일 주소·sha256·크기를 담은 download 가 옵니다 |
| user_query | string | N | 이 호출을 유발한 사용자 질의 원문. 이력에 기록됩니다 |
| is_skills | boolean | N | 스킬 경유 호출 여부(기본 false). 이력에 기록됩니다 |
| skill_desc | object | N | 스킬 경유 호출일 때 스킬 정보. 이력에 기록됩니다 |

```
curl -X POST "https://listeningmind-data-api.ascentlab.io/keyword_info/monthly_volume" 
  -H "Content-Type: application/json" 
  -H "LM-API-KEY: 발급받은 API Key" 
  -d '{"keyword": "에어컨 청소", "gl": "kr"}'
```

인증은 [Data API 기술 자료](https://kr.listeningmind.com/data-api/api-reference/listeningmind-daas-data-api-parameters/)를 참고하세요.

## 응답 (Response)

2026년 11월 조회 예시이고, 최대 48개월 중 최근 3개월만 표시했습니다. 수치는 조회 시점에 따라 달라집니다. 일부 메타 필드는 생략했고 `used_credits`는 예시값입니다. 표에 없는 필드는 무시하도록 파싱하세요.

```
{
  "result": "OK",
  "reason": "SUCCESS",
  "cost_detail": {
    "input_cost": 1,
    "input_count": 1,
    "input_total_cost": 1,
    "output_cost": 0,
    "output_count": 1,
    "output_total_cost": 0,
    "total_cost": 1
  },
  "used_credits": 12500,
  "data": [
    {
      "keyword": "에어컨 청소",
      "monthly_volume": [
        {
          "month": "2026-07",
          "gg": 27100,
          "nv": 89500,
          "total": 116600
        },
        {
          "month": "2026-08",
          "gg": 18100,
          "nv": 43460,
          "total": 61560
        },
        {
          "month": "2026-09",
          "gg": 6600,
          "nv": 28440,
          "total": 35040
        }
      ]
    }
  ]
}
```

| **필드** | **타입** | **설명** |
| --- | --- | --- |
| result · reason | string | 성공하면 OK · SUCCESS |
| data[].keyword | string | 조회된 키워드. 요청 표기와 다를 수 있습니다(예: LG 냉장고 → lg 냉장고). 비교할 때는 공백을 빼고 소문자로 맞추세요 |
| data[].monthly_volume[].month | string | 연월 (YYYY-MM). 확인한 응답은 오래된 달부터 최신 달 순이었습니다. 기준월은 month 값으로 읽으세요 |
| data[].monthly_volume[].gg | integer | 구글 월 검색량. us·jp 응답에는 없습니다 |
| data[].monthly_volume[].nv | integer | 네이버 월 검색량. us·jp 응답에는 없습니다 |
| data[].monthly_volume[].total | integer | 월 검색량 합계. kr 응답에서 gg + nv 와 일치합니다 |
| cost_detail | object | 이번 호출의 과금 내역. 실제 비용은 total_cost 입니다 |
| used_credits | integer | 월간 누적 사용량 (잔여량이 아닙니다) |

###

### 월별 검색량이 없는 키워드

오류가 아니라 빈 배열로 돌아옵니다. 호출 쪽에서 `data`가 비어 있는 경우를 처리하세요. 없는 키워드로 확인한 응답은 `total_cost`가 0입니다.

```
{
  "result": "OK",
  "reason": "SUCCESS",
  "cost_detail": {
    "input_cost": 1,
    "input_count": 0,
    "input_total_cost": 0,
    "output_cost": 0,
    "output_count": 0,
    "output_total_cost": 0,
    "total_cost": 0
  },
  "data": []
}
```

### 요청 오류

`keywords` 배열로 보내거나 지원하지 않는 국가 코드를 넣으면 HTTP 422를 반환합니다. 이 API의 파라미터는 단수형 `keyword`입니다. 인증·공통 오류 처리는 [키워드 조회 API](https://kr.listeningmind.com/data-api/api-reference/keyword-info-api/)의 오류 응답 절을 참고하세요.

## 과금

키워드 1개 = 호출 1회이고 1 크레딧입니다. 출력 과금은 없습니다. 실제 비용은 응답의 `total_cost`로 읽으세요(위 빈 배열 사례 참고). 전체 단가는 [크레딧 산정 기준과 엔드포인트별 단가](https://kr.listeningmind.com/data-api/pricing/credit-and-endpoint-pricing/)를 참고하세요.

## 활용 예시: 시즌 파악

키워드 "에어컨 청소"(한국)의 월별 `total`을 48개월(2022-10~2026-09) 그린 것입니다. 매년 봄에 오르고 겨울에 내려갑니다. 2026년 11월 조회값이고, 이 키워드 한 건의 관측입니다.

세로축 단위 건(만). 점 위 숫자는 그해 최고 달의 검색량이고, 점에 마우스를 올리면 달별 값이 보입니다.

**연도별 최고·최저 달**

| **연도** | **최고 달** | **최고 검색량** | **최저 달** | **최저 검색량** |
| --- | --- | --- | --- | --- |
| 2023 | 2023년 5월 | 345,900건 | 2023년 12월 | 16,110건 |
| 2024 | 2024년 6월 | 335,800건 | 2024년 12월 | 14,040건 |
| 2025 | 2025년 6월 | 274,600건 | 2025년 1월 | 16,610건 |
| 2026 (1~9월) | 2026년 5월 | 279,100건 | 2026년 1월 | 20,030건 |

2022년은 10~12월만 있어 표에서 뺐습니다.

### 따라 하기

1. 응답에서 `keyword`가 요청과 일치하는 행을 고릅니다.
2. `monthly_volume`을 연도별로 나누고, `total`이 가장 큰 달과 작은 달을 찾습니다.
3. 최고 달이 해마다 같은지 봅니다. 이 키워드는 최고 달이 5월 · 6월 · 6월 · 5월로 해마다 조금씩 달라, 특정 달 하나로 고정하지 않는 편이 안전합니다.

받은 기간 전체로 판단하세요. 지수로 계산하려면 [시즌성 지수(SI) 문서](https://kr.listeningmind.com/data-api/data-interpretation/seasonality-index/)를 참고하세요.

## 자주 묻는 질문 (FAQ)

### Q1. 키워드 여러 개를 한 번에 보낼 수 있나요?

아니요. 키워드는 1개만 받습니다. 여러 개라면 `/keyword_info`에 `data_type: ads_info`로 보내세요.

### Q2. 어떤 단위이고 최신 월은 언제인가요?

월 단위입니다. 주간·일간 변화를 보는 용도로는 쓸 수 없습니다. 2026년 11월 5일 조회에서 최신 월은 2026-09였습니다(키워드 1건). 최신 월을 고정값으로 두지 말고 응답의 `month`로 읽으세요.

### Q3. 일본·미국도 구글·네이버 값을 나눠 주나요?

확인한 미국(us)·일본(jp) 응답에는 `month`와 `total`만 있습니다. `gg`·`nv`가 없는 경우를 처리하세요. 지표 해석은 [검색량 지표 읽는 법](https://kr.listeningmind.com/data-api/data-interpretation/search-volume-metrics/)을 참고하세요.