Intent Finder API는 입력한 시드(seed) 키워드와 함께 실제로 검색되는 연관 키워드 리스트를 반환합니다. 소비자가 동일한 검색 세션에서 함께 탐색하는 키워드를 기반으로 하므로, 단순 유사 키워드가 아닌 실제 검색 의도를 반영한 확장 키워드를 확보할 수 있습니다.
핵심 특징 요약
| 항목 | 상세 |
| 엔드포인트 | POST /intent_finder/keyword_list |
| 요청 키워드 수 | 최소 1개 / 최대 100개 (배열) |
| 반환 형식 | data: string[] (단순 키워드 문자열 배열) |
| 반환 기본 개수 | 100개 |
| 반환 최대 개수 | 10,000개 (limit 파라미터로 제어) |
| 지원 국가(gl) | kr (한국) / jp (일본) / us (미국) |
| 과금 방식 | 입력 키워드 1개당 30 크레딧 + 출력 키워드 1개당 2 크레딧 |
연관 쿼리 추출 API(/intent_finder/keyword_list) 는 언제 사용하나
| 사용자 질문 | 활용 방향 |
| 이 키워드와 함께 자주 검색되는 키워드가 뭔가요? | 시드 키워드 기반 연관 키워드 확장 |
| SEO 롱테일 키워드를 찾고 싶어요. | volume_threshold를 낮춰 틈새 키워드 발굴 |
| 광고 그룹을 세분화할 키워드가 필요해요. | 복수 시드 키워드로 광고 그룹별 확장 |
| 콘텐츠 주제를 넓히고 싶어요. | 연관 키워드 풀 확보 후 클러스터링 |
| 트렌드 상승 중인 연관 키워드를 찾고 싶어요. | 최근 3개월 증감율 기준으로 내림차순으로 정렬해 sort: volume_trend, order: desc 설정 |
요청 파라미터 (Request)
파라미터 상세
| 파라미터 | 타입 | 필수 | 기본값 | 설명 |
| keywords | array[string] | Y | – | 시드 키워드 목록 (1~100개). 영어는 소문자 권장 |
| gl | string | Y | – | 국가 코드: “kr” / “jp” / “us” |
| volume_threshold | integer | N | 100 | 반환 키워드의 최소 검색량 필터. 이 값 미만 키워드 제외 |
| limit | integer | N | 100 | 반환 키워드 수 제한 (1~10,000) |
| sort | string | N | volume_avg | 정렬 기준: volume_avg / volume_total / volume_trend / cpc / competition_index |
| order | string | N | desc | 정렬 방향: desc (내림차순) / asc (오름차순) |
탐색 범위 조절 – volume_threshold (검색량 임계값) 설정
| 설정값 | 효과 | 추천 상황 |
| 100 (기본) | 일정 수요 이상 키워드만 반환 | 실무 광고·SEO 키워드 확보 |
| 10 이하 | 소량 검색 롱테일까지 포함 | 틈새 시장 탐색, 신조어 발굴 |
| 1,000 이상 | 고수요 키워드만 반환 | 대형 카테고리 핵심 키워드만 필요할 때 |
반환 개수 조절 – limit
| 설정값 | 효과 | 출력 과금 |
| 100 (기본) | 빠른 탐색, 비용 절감 | 200 크레딧 |
| 500 | 실무 SEO/광고 키워드 충분 확보 | 1,000 크레딧 |
| 10,000 (최대) | 전체 연관 키워드 풀 수집 | 20,000 크레딧 |
✔ 실무에서는 limit: 100~500이 비용 대비 효율이 높습니다. 초기 탐색은 기본값(100)으로 시작하고, 키워드 풀 확장이 필요할 때 늘리세요.
목적에 따른 정렬 기준 설정 – sort
| sort 값 | 정렬 기준 | 추천 상황 |
| volume_avg (기본) | 월 평균 검색량 높은 순 | 주요 대형 키워드 우선 확인 |
| volume_total | 연간 총 검색량 높은 순 | 시즌성 있는 키워드 포함 시 |
| volume_trend | 검색량 증감률 높은 순 | 급상승 트렌드 키워드 발굴 |
| cpc | 클릭당 비용 높은 순 | 상업적 가치 높은 키워드 우선 |
| competition_index | 광고 경쟁도 높은 순 | 경쟁 키워드 파악 |
요청 예시
기본 요청
{
"keywords": ["OO 냉장고"],
"gl": "kr"
}
복수 시드 키워드 + 상세 옵션
{
"keywords": ["OO 냉장고", "{경쟁사} 냉장고"],
"gl": "kr",
"volume_threshold": 500,
"limit": 300,
"sort": "volume_avg",
"order": "desc"
}
응답 데이터 구조 (Response)
응답 데이터 구조 개요
| 필드 | 타입 | 설명 |
| result | string | “OK” 또는 “FAILED” |
| cost_detail | object | 입력 크레딧(30 × 시드 수) + 출력 크레딧(2 × 반환 키워드 수) |
| used_credits | integer | 요청 후 잔여 크레딧 |
| data | array[string] | 연관 키워드 문자열 배열 (핵심 결과) |
응답 예시
{
"result": "OK",
"cost_detail": { "input_cost": 30, "output_cost": 20, "total_cost": 50 },
"remain_credits": 99950,
"data": [
"OO 냉장고 오브제", "OO 냉장고 가격",
"OO 냉장고 추천", "OOO 냉장고",
"OO 냉장고 후기"
]
과금 구조 상세
| 구분 | 기준 | 단가 | 계산 예시 |
| 입력 과금 | 시드 키워드 1개당 | 30 크레딧 | 시드 3개 → 90 크레딧 |
| 출력 과금 | 반환 키워드 1개당 | 2 크레딧 | 결과 100개 → 200 크레딧 |
| 합계 예시 | 시드 3개, 결과 100개 | 290 크레딧 | 90 + 200 = 290 크레딧 |
✔ 4xx/5xx 오류 시 입력·출력 모두 과금되지 않습니다. 200 정상 응답이지만 결과가 빈 배열인 경우 입력 과금은 발생합니다.
| 시나리오 | 시드 수 | limit | 예상 총 크레딧 (결과 full 가정) |
| 빠른 탐색 | 1 | 100 | 230 크레딧 |
| 실무 SEO 작업 | 5 | 300 | 3,150 크레딧 |
| 대규모 수집 | 10 | 1,000 | 20,300 크레딧 |
활용 시나리오
SEO 롱테일 키워드 발굴
| 단계 | 작업 | 파라미터 설정 |
| 1. 시드 설정 | 카테고리 핵심 키워드 1~5개 | keywords: [“키워드1”, …] |
| 2. 필터 조정 | 낮은 threshold로 롱테일 포함 | volume_threshold: 50, limit: 500 |
| 3. 트렌드 우선 | 상승 중인 키워드 선별 | sort: “volume_trend”, order: “desc” |
| 4. 심층 분석 | 유망 키워드 상세 조회 | /keyword_info에 결과 키워드 입력 |
후속 분석 연계 워크플로우
| 연계 API | 활용 방법 | 얻는 인사이트 |
| /keyword_info | Intent Finder 결과를 keywords[]에 입력 | 검색량, CPC, SERP, 의도, 인구통계 확인 |
| /cluster_finder | 연관 키워드를 클러스터 분석 시드로 활용 | 키워드 관계망 및 소비자 인식 그룹 파악 |
| /path_finder | 연관 키워드로 검색 여정 분석 | 해당 키워드 전후 탐색 경로 확인 |
✔ 추천 워크플로우: ① Intent Finder로 키워드 풀 수집 → ② /keyword_info로 우선순위 선별 → ③ /cluster_finder로 인식 그룹화 → 콘텐츠·광고 세그먼트 도출
오류 응답 처리
| HTTP Status | 주요 원인 | 조치 방법 |
| 401 Unauthorized | API Key 미입력 또는 무효 | LM-API-KEY 헤더 확인 |
| 402 Payment Required | 크레딧 부족 | 잔여 크레딧 확인 후 충전 |
| 422 Unprocessable Entity | gl 값 오류, 파라미터 형식 오류 | detail 필드의 오류 위치 확인 |
| 429 Too Many Requests | Rate Limit 초과 | 요청 속도 조절 후 재시도 |
| 500 Internal Server Error | 서버 내부 오류 | 기술 지원 문의 |
자주 묻는 질문 (FAQ)
Q1. 시드 100개 입력 시 각각의 연관 키워드가 따로 반환되나요?
아니요. 복수 시드 입력 시 통합된 단일 배열로 반환됩니다. 시드별 개별 결과가 필요하면 API를 여러 번 호출하세요.
Q2. 반환된 키워드에 무관 키워드가 다수 포함되어 있어요.
경우에 따라 포함될 수 있습니다. 현재 API 레벨에서 필터링은 불가합니다. 호출 후 필터링 작업을 권장합니다.
Q3. 결과 정렬 기준(sort)이 실제로 반환 순서를 보장하나요?
네. sort 파라미터 기준으로 정렬된 순서로 반환됩니다. 배열 앞부분에 위치한 키워드가 해당 기준에서 높은 값을 가집니다. 정확한 수치 확인이 필요하면 /keyword_info를 추가 호출하세요.
