Keyword Info API는 특정 키워드에 대한 검색량, 광고 경쟁도, SERP 구조, 검색 의도, 사용자 인구통계 등 정보를 한 번의 요청으로 종합 조회하는 엔드포인트입니다. 최대 1,000개 키워드를 동시에 처리할 수 있습니다.
핵심 특징 요약
| 항목 | 상세 |
| 엔드포인트 | POST /keyword_info |
| 요청 키워드 수 | 최소 1개 / 최대 1,000개 (배열) |
| 반환 개수 | 요청 키워드 수와 동일 (1:1 대응) |
| 지원 국가(gl) | kr (한국) / jp (일본) / us (미국) |
| data_type | ads_metrics, monthly volume, features(SERP), intents, demography |
| 과금 방식 | 입력 키워드 1개당 10 크레딧 (출력 과금 없음) |
키워드 조회(/keyword_info) API는 언제 사용하나
| 사용자 질문 | 사용 지표 |
| 시장 규모 판단 이 키워드를 사람들이 얼마나 검색하나요? | volume_avg, volume_total |
| 성장/하락 트렌드 파악 (3개월 기준 증감율) 검색량이 늘고 있나요, 줄고 있나요? | volume_trend |
| 구글/네이버 채널 비중 비교 구글과 네이버 중 어디서 더 많이 검색하나요? | gg_volume_avg, nv_volume_avg |
| 광고 난이도·비용 추정 광고를 집행하면 경쟁이 치열한가요? | competition_index, cpc |
| 콘텐츠 SEO 어떤 콘텐츠 포맷이 검색 결과에 노출되나요? | features (f_images, f_video_results 등) |
| 콘텐츠·광고 전략 방향 결정 이 키워드로 검색하는 사람들의 목적은 무엇인가요? | intents (i, n, c, t) |
| 타겟 오디언스 프로파일링 주요 검색 사용자층은 누구인가요? | demography (m/f_gender_ratio, a30_ratio 등) |
| 시즌성 분석, 광고 집행 시점 결정 월별 검색량 추이를 보고 싶어요. | monthly_volume (data_type: ads_info 또는 all) |
요청 파라미터 (Request)
파라미터 상세
| 파라미터 | 타입 | 필수 | 기본값 | 설명 |
| keywords | array[string] | Y | – | 조회할 키워드 목록 (1~1,000개). 영어는 소문자 권장 |
| gl | string | Y | – | 국가 코드. “kr” / “jp” / “us” 중 하나 |
| data_type | string | N | ads_metrics | 반환 데이터 범위 선택 (아래 표 참고) |
data_type 선택 기준
| data_type 값 | 포함 데이터 | 추천 상황 |
| ads_metrics (기본) | 검색량, CPC, 광고 경쟁도 | 빠른 검색량·경쟁도 확인만 필요할 때 |
| ads_info | ads_metrics + 월별 검색량 | 시즌성·트렌드 분석이 필요할 때 |
| all | ads_metrics + 월별 + SERP + 의도 + 인구통계 | 타겟팅·콘텐츠 전략 수립 시 종합 분석 |
data_type별 반환 필드 요약
| 필드 그룹 | ads_metrics | ads_info | all |
| ads_metrics (검색량·광고) | O | O | O |
| monthly_volume (월별 검색량) | X | O | O |
| features (SERP 노출) | X | X | O |
| intents (검색 의도) | X | X | O |
| demography (인구통계) | X | X | O |
요청 예시
단일 키워드 조회
{
"keywords": ["lg 냉장고"],
"gl": "kr"
}
다중 키워드 + 전체 데이터 조회
{
"keywords": ["lg 냉장고", "삼성 냉장고", "냉장고 추천"],
"gl": "kr",
"data_type": "all"
}✔ 영어 키워드는 소문자로 입력하세요.
응답 데이터 구조 (Response)
응답 데이터 구조 개요
| 최상위 필드 | 타입 | 설명 |
| result | string | “OK” 또는 “FAILED” |
| reason | string | “SUCCESS” 또는 오류 메시지 |
| request_detail | object | 요청 파라미터 에코 |
| cost_detail | object | 입/출력 크레딧 상세 (input_cost: 10 × 키워드 수) |
| used_credits | integer | 요청 후 누적 크레딧 |
| data | array | 키워드별 분석 결과 배열 (핵심 데이터) |
data[ ] 내부 구조
| 필드 | 포함 조건 | 설명 |
| keyword | 항상 | 요청 키워드 |
| ads_metrics | 항상 | 검색량·CPC·광고 경쟁도 |
| features | data_type: all | Google SERP 노출 타입 |
| intents | data_type: all | 검색 의도 (I/N/C/T) |
| demography | data_type: all | 성별·연령 분포 |
| monthly_volume | data_type: ads_info 또는 all | 월별 Google/Naver 검색량 (최대 48개월) |
주요 지표 해석
검색 수요 광고 지표 (ads_metrics)
| 지표명 | 설명 | 해석 포인트 |
| volume_avg | 최근 3개월 월 평균 검색량 (구글+네이버 합산) | 10만 이상: 대형 키워드 / 1만 미만: 틈새 키워드 |
| volume_total | 최근 12개월 총 검색량 | 시장 규모 정량화에 활용 |
| volume_trend | 3개월 전 대비 최근 월 증감률 | 양수: 상승 / 음수: 하락 (예: -0.22 = 22% 감소) |
| gg_volume_avg | 구글 월 평균 검색량 | 구글/네이버 비율로 채널 전략 수립 |
| nv_volume_avg | 네이버 월 평균 검색량 | 한국은 네이버 비중이 높은 경우가 많음 |
| competition | 광고 경쟁 강도 레이블 | LOW(0~33) / MEDIUM(34~66) / HIGH(67~100) |
| competition_index | 광고 경쟁도 수치 (0~100) | 높을수록 광고 입찰 경쟁이 치열 |
| cpc | 클릭당 광고 비용 (USD) | 높을수록 상업적 가치가 높은 키워드 |
| low_bid_micros | 낮은 입찰가 (마이크로 단위) | 광고 최소 예산 산정에 참고 |
| high_bid_micros | 높은 입찰가 (마이크로 단위) | 경쟁적 입찰 시 필요 예산 추정 |
✔ 한국(gl: kr) 기준 volume_avg/total/trend는 Google + Naver 합산값입니다. 구글 단독 수치는 gg_, 네이버 단독 수치는 nv_필드를 사용하세요.
SERP 노출 지표 (features)
Google 검색 결과 페이지에 어떤 유형의 콘텐츠가 얼마나 노출되는지 나타냅니다
| 카테고리 | 주요 필드 | 해석 |
| AI Overview | f_ai_overview | 1이면 AI Overview 노출. SEO 전략 재검토 필요 |
| 광고 (Ads) | f_ads_top, f_ads_bottom | 상단/하단 광고 블록 수. 값이 클수록 상업적 키워드 |
| 오가닉 결과 | f_organic_results | 일반 웹 문서 결과 수. SEO 기회 가늠에 활용 |
| Featured Snippet | f_featured_snippet | 1이면 스니펫 점유 중. 블로그/콘텐츠 최적화 기회 |
| People Also Ask | f_people_also_ask_for | 연관 질문 노출. FAQ 콘텐츠 기획에 활용 |
| 이미지·영상 | f_images, f_video_results | 미디어 콘텐츠 수요 존재. 이미지/영상 제작 검토 |
| Knowledge Panel | f_knowledge_panel | 브랜드·인물 관련 키워드 가능성 |
| Local Results | f_local_results | 지역 기반 키워드 특성. 로컬 마케팅 연계 |
검색 의도 (intents) 지표
검색 의도(정보형, 이동형, 상업형, 거래형 구분)를 다음과 같이 구분합니다.
해당 의도가 유의미하게 나타났는지 여부를 1 또는 0으로 반환합니다. 복수 의도가 동시에 존재할 수 있습니다.
| 코드 | 의도 유형 | 설명 | 활용 전략 |
| i (I) | Informational (정보형) | 제품·카테고리 정보 획득 목적 | 블로그, 가이드, FAQ 콘텐츠 |
| n (N) | Navigational (이동형) | 특정 사이트·브랜드·위치 탐색 | 브랜드 검색 최적화 |
| c (C) | Commercial (상업형) | 구매 전 비교·리뷰·추천 탐색 | 비교 페이지, 리뷰 콘텐츠 |
| t (T) | Transactional (거래형) | 구매·신청 목적의 검색 | 랜딩 페이지, 전환 최적화 |
사용자 인구 통계 (demography) 지표
표준편차(1시그마) 이상으로 특정 성별·연령대의 검색 비중이 높은 경우 플래그(1/0)를 반환합니다.
| 필드 유형 | 필드명 예시 | 설명 |
| 플래그 (1/0) | m_gender, f_gender, a20, a30, a40… | 1이면 해당 집단의 검색 비중이 통계적으로 유의미하게 높음 |
| 비율 (%) | m_gender_ratio, f_gender_ratio, a30_ratio… | 전체 검색량 중 해당 집단의 비율 (단위: %) |
연령대별 코드 대응표
| 필드명 | 연령 범위 |
| a0 | 12세 이하 |
| a13 | 13~19세 |
| a20 | 20~24세 |
| a25 | 25~29세 |
| a30 | 30~39세 |
| a40 | 40~49세 |
| a50 | 50세 이상 |
월별 검색량 (monthly_volume) 지표
최대 48개월(4년)간의 월별 구글·네이버 검색량을 제공합니다. 시즌성·성장성 분석에 활용합니다.
| 필드 | 설명 |
| month | 기준 월 (형식: YYYY-MM, 예: 2025-08) |
| gg | 해당 월 구글 검색량 |
| nv | 해당 월 네이버 검색량 |
| total | 구글 + 네이버 합산 검색량 |
✔ 월별 검색량 데이터는 시즌별 수요 예측, 광고 예산 배분, 콘텐츠 발행 시점 결정에 유용합니다. 예: 여름철 에어컨 키워드의 5~7월 급증 패턴 확인.
활용 시나리오별 파라미터 조합
목적에 따라 data_type을 선택하면 불필요한 데이터 수신과 분석 복잡도를 줄일 수 있습니다.
| 목적 | 권장 data_type | 핵심 확인 지표 | 과금 (키워드당) |
| 시장 규모 빠른 파악 | ads_metrics | volume_avg, volume_total | 10 Credits |
| 광고 효율 사전 분석 | ads_metrics | competition_index, cpc, high_bid_micros | 10 Credits |
| 플랫폼별 채널 전략 | ads_metrics | gg_volume_avg vs nv_volume_avg | 10 Credits |
| 시즌성·트렌드 분석 | ads_info | monthly_volume, volume_trend | 10 Credits |
| SEO 콘텐츠 기획 | all | f_organic_results, f_ai_overview, f_featured_snippet | 10 Credits |
| 타겟 오디언스 설정 | all | demography (f_gender_ratio, a30_ratio 등) | 10 Credits |
| 검색 의도 기반 메시지 설계 | all | intents (i, c, t 조합) | 10 Credits |
| 종합 키워드 전략 수립 | all | 전체 지표 통합 분석 | 10 Credits |
⚠ 과금은 data_type에 관계없이 입력 키워드당 동일하게 10 크레딧입니다. 단, 한 번의 요청으로 모든 데이터를 수집할 수 있으므로 “all”로 1회 수집 후 분석 목적에 따라 필드를 선택적으로 사용하면 효율적입니다.
전체 응답 예시
아래는 “OO 냉장고” 키워드에 대한 실제 응답 구조 예시입니다.
Request
{
"keywords": ["OO 냉장고"],
"gl": "kr",
"data_type": "all"
}Response
{
"result": "OK",
"reason": "SUCCESS",
"cost_detail": { "input_cost": 10, "total_cost": 10 },
"remain_credits": 99990,
"data": [{
"keyword": "OO 냉장고",
"ads_metrics": {
"competition": "HIGH", "competition_index": 93,
"cpc": 0.87,
"volume_avg": 304333, "volume_total": 3271400, "volume_trend": -0.22,
"gg_volume_avg": 56833, "nv_volume_avg": 247500
},
"features": {
"f_ai_overview": 1, "f_organic_results": 18,
"f_ads_top": 2, "f_featured_snippet": 1
},
"intents": { "i": 1, "n": 0, "c": 0, "t": 1 },
"demography": {
"f_gender": 1, "f_gender_ratio": 55.76,
"a30": 1, "a40": 1, "a30_ratio": 26.12, "a40_ratio": 33.40
},
"monthly_volume": [
{ "month": "2025-08", "gg": 108000, "nv": 261000, "total": 369000 },
{ "month": "2025-09", "gg": 112000, "nv": 268000, "total": 380000 }
]
}]
}
응답 데이터 해석 요약 (위 예시 기준)
| 분석 영역 | 해석 (추정 포함) | 비고 |
| 시장 규모 | 월 평균 약 30.4만 건 검색 (구글+네이버) | 사실: API 반환값 기준 |
| 플랫폼 비중 | 네이버 약 81% (247,500 / 304,333) | 추정: 구글+네이버 합산 기준 산출 |
| 검색 추세 | 3개월 전 대비 약 22% 감소 (volume_trend: -0.22) | 사실: API 반환값 기준 |
| 광고 경쟁 | 매우 치열 (competition_index: 93/100) | 사실: API 반환값 기준 |
| 광고 비용 | 클릭당 약 $0.87 USD | 사실: API 반환값 기준 |
| SERP 특이사항 | AI Overview 노출 중 → 오가닉 클릭률 영향 가능성 | 추정: SERP 구조 변화 관련 |
| 검색 의도 | 정보 탐색(i=1)과 구매(t=1) 의도 공존 | 사실: API 반환값 기준 |
| 주요 사용자 | 여성(55.76%), 30~40대 (합산 약 59.5%) | 사실: API 반환값 기준 |
⚠ “추정” 표시 항목은 API 반환값을 조합·계산한 결과로, 실제 시장 상황과 다를 수 있습니다. “사실” 표시 항목만 API 직접 반환값입니다.
오류 응답 처리
4xx/5xx 오류 발생 시 크레딧은 과금되지 않습니다.
| HTTP Status | 오류 유형 | 주요 원인 | 조치 방법 |
| 401 Unauthorized | 인증 실패 | API Key 미입력 또는 유효하지 않은 Key | LM-API-KEY 헤더 값 확인 |
| 402 Payment Required | 크레딧 부족 | remain_credits 부족 | 크레딧 충전 후 재요청 |
| 403 Forbidden | 권한 없음 | 해당 엔드포인트 접근 권한 없음 | 계약 플랜 확인 |
| 422 Unprocessable Entity | 파라미터 오류 | gl 값 오류, keywords 형식 오류 등 | detail 필드의 오류 메시지 확인 |
| 429 Too Many Requests | Rate Limit 초과 | 단시간 과다 요청 | 요청 속도 조절 후 재시도 |
| 500 Internal Server Error | 서버 오류 | 리스닝마인드 서버 내부 문제 | 리스닝마인드 기술 지원 문의 |
자주 묻는 질문 (FAQ)
Q1. keywords 배열에 1,000개를 넣으면 응답도 1,000개인가요?
네. Keyword Info는 요청 키워드 수와 응답 수가 1:1로 대응합니다. 단, keywords 배열 크기가 반환 개수를 결정하며 별도 limit 파라미터는 지원하지 않습니다.
Q2. volume_avg는 어떤 기간을 기준으로 하나요?
최근 3개월의 월별 검색량 평균값입니다. volume_total은 최근 12개월 합산입니다. 과거 특정 시점 데이터가 필요하면 monthly_volume 필드(data_type: ads_info 또는 all)를 활용하세요.
Q3. 구글과 네이버 검색량 합산 기준은 한국(kr)만 해당되나요?
네. 현재 구글+네이버 합산 검색량(volume_avg, volume_total, volume_trend)은 한국(gl: kr) 기준에서만 제공됩니다. 일본(jp), 미국(us)은 구글만 제공합니다.
Q4. features, intents, demography가 응답에 없는데요.
data_type을 “ads_metrics” (기본값) 또는 “ads_info”로 설정한 경우, features/intents/demography 필드는 반환되지 않습니다. 이 데이터가 필요하면 data_type: “all”을 명시해야 합니다.
Q5. 에러가 발생해도 크레딧이 과금되나요?
아니요. 4xx 또는 5xx HTTP 응답 코드로 오류가 발생한 경우 입력·출력 모두 과금되지 않습니다. 단, 200 정상 응답이지만 특정 키워드의 데이터가 null이나 빈 배열인 경우는 과금이 발생합니다.
Q6. monthly_volume은 최대 몇 개월치를 받을 수 있나요?
최대 48개월(4년)치 데이터를 제공합니다. 단, 데이터 수집 시작 시점에 따라 실제 반환되는 월 수가 다를 수 있습니다.
