View Categories

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

0:00 5:03

키워드 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 응답의 monthly_volume과 같습니다. 키워드가 여러 개라면 호출을 나누지 말고 ads_info로 묶으세요. 호출 수는 줄지만 크레딧은 키워드 수만큼 듭니다(1,000개면 1,000 크레딧).

요청 (Request)

파라미터타입필수설명
keywordstringY조회할 키워드 1개
glstringY국가 코드: “kr” / “jp” / “us”
response_formatstringNjson(기본) 또는 download_url. download_url 이면 data 대신 파일 주소·sha256·크기를 담은 download 가 옵니다
user_querystringN이 호출을 유발한 사용자 질의 원문. 이력에 기록됩니다
is_skillsbooleanN스킬 경유 호출 여부(기본 false). 이력에 기록됩니다
skill_descobjectN스킬 경유 호출일 때 스킬 정보. 이력에 기록됩니다
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 기술 자료를 참고하세요.

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

월별 검색량이 없는 키워드

오류가 아니라 빈 배열로 돌아옵니다. 호출 쪽에서 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의 오류 응답 절을 참고하세요.

과금

키워드 1개 = 호출 1회이고 1 크레딧입니다. 출력 과금은 없습니다. 실제 비용은 응답의 total_cost로 읽으세요(위 빈 배열 사례 참고). 전체 단가는 크레딧 산정 기준과 엔드포인트별 단가를 참고하세요.

활용 예시: 시즌 파악

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

010만20만30만20232024202520265월 34.6만6월 33.6만6월 27.5만5월 27.9만2022년 10월: 24,440건2022년 11월: 16,460건2022년 12월: 14,080건2023년 1월: 16,520건2023년 2월: 24,570건2023년 3월: 77,600건2023년 4월: 137,100건2023년 5월: 345,900건2023년 6월: 313,600건2023년 7월: 177,900건2023년 8월: 106,700건2023년 9월: 51,970건2023년 10월: 30,650건2023년 11월: 20,400건2023년 12월: 16,110건2024년 1월: 39,840건2024년 2월: 26,750건2024년 3월: 66,700건2024년 4월: 205,600건2024년 5월: 242,200건2024년 6월: 335,800건2024년 7월: 160,400건2024년 8월: 108,900건2024년 9월: 61,100건2024년 10월: 33,840건2024년 11월: 16,890건2024년 12월: 14,040건2025년 1월: 16,610건2025년 2월: 28,570건2025년 3월: 94,700건2025년 4월: 158,100건2025년 5월: 256,300건2025년 6월: 274,600건2025년 7월: 144,700건2025년 8월: 76,130건2025년 9월: 46,860건2025년 10월: 29,560건2025년 11월: 19,530건2025년 12월: 18,970건2026년 1월: 20,030건2026년 2월: 25,370건2026년 3월: 72,500건2026년 4월: 177,100건2026년 5월: 279,100건2026년 6월: 175,300건2026년 7월: 116,600건2026년 8월: 61,560건2026년 9월: 35,040건
세로축 단위 건(만). 점 위 숫자는 그해 최고 달의 검색량이고, 점에 마우스를 올리면 달별 값이 보입니다.

연도별 최고·최저 달

연도최고 달최고 검색량최저 달최저 검색량
20232023년 5월345,900건2023년 12월16,110건
20242024년 6월335,800건2024년 12월14,040건
20252025년 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) 문서를 참고하세요.

자주 묻는 질문 (FAQ)

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

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

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

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

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

확인한 미국(us)·일본(jp) 응답에는 month와 total만 있습니다. gg·nv가 없는 경우를 처리하세요. 지표 해석은 검색량 지표 읽는 법을 참고하세요.

Updated on 2026년 11월 05일

What are your Feelings

  • Happy
  • Normal
  • Sad
지금, 고객의 ‘의사결정 여정’을 데이터로 확인하세요

데모 신청을 통해 우리 브랜드의 고객 여정을 발견하고, 성장 기회를 포착하세요.

무료 브랜드 진단 받기