관계 네트워크 기반 키워드 목록 조회 API(cluster_finder/keyword_list)는 소비자 인식 및 관계 네트워크 분석 API(/cluster_finder)와 동일한 파라미터를 지원하지만, 관계 네트워크(rels)와 소비자 인식 그룹(communities) 상세 구조 대신 관계 네트워크에 등장하는 키워드 목록(string[])만을 반환합니다. Cluster Finder 수집 전 단계에서 후보 키워드를 빠르게 수집하거나, 대규모 키워드 풀을 저비용으로 확보할 때 활용합니다.
- 상세 구조 분석 필요 시, /cluster_finder
- 키워드 목록만 필요 시, /cluster_finder/keyword_list
/cluster_finder vs /cluster_finder/keyword_list 비교
| 구분 | /cluster_finder | /cluster_finder/keyword_list |
| 반환 형식 | { rels: [][], communities: {} } | string[] (키워드 목록) |
| 포함 정보 | 관계 구조, 클러스터 그룹 포함 | 키워드 목록만 (구조 정보 없음) |
| 과금 | 150 크레딧 입력 + 50 크레딧/관계 | 30 크레딧 입력 + 2 크레딧/키워드 |
| 주 활용 목적 | 인식 그룹·관계 네트워크 분석 | 키워드 풀 빠른 수집 |
⚠ Cluster Finder List는 키워드 목록만 반환합니다. 클러스터 그룹 구조(communities)나 관계(rels)가 필요하면 반드시 /cluster_finder를 사용하세요.
핵심 특징 요약
| 항목 | 상세 |
| 엔드포인트 | POST /cluster_finder/keyword_list |
| 요청 키워드 수 | 1개 (단일 키워드) |
| 반환 형식 | data: string[] (관계 네트워크 등장 키워드 목록) |
| 반환 기본 개수 | 500개 |
| 반환 최대 개수 | 1,000개 (limit 기준) |
| 과금 방식 | 입력 1회당 30 크레딧 + 출력 키워드 1개당 2 크레딧 |
관계 네트워크 기반 키워드 목록 조회 API(/cluster_finder/keyword_list) 언제 사용하나
| 상황 | 활용 방안 |
| /cluster_finder 수집 전 단계 키워드 사전 탐색 | 상세 클러스터 분석 전 키워드 범위 확인 → 비용 절감 |
| /keyword_info 대량 조회 준비 | 관계 네트워크 키워드를 일괄 수집 후 상세 지표 분석 |
| 경쟁 키워드 커버리지 확인 | 특정 키워드가 네트워크에 포함되는지 빠르게 확인 |
| Intent Finder/keyword_list + Cluster 보완 | 두 API의 연관 키워드를 합산하여 더 넓은 풀 확보 |
요청 파라미터 (Request)
파라미터 상세
| 파라미터 | 타입 | 필수 | 기본값 | 설명 |
| keyword | string | Y | – | 분석 중심 키워드 (단일) |
| gl | string | Y | – | 국가 코드: “kr” / “jp” / “us” |
| time_point | string | N | curr | 데이터 시점: curr / 3m / 6m / 9m / 12m |
| limit | integer | N | 500 | 반환 키워드 수 (1~1,000) |
| hop | integer | N | 2 | 관계 확장 깊이 (1~3) |
| orientation | string | N | UNDIRECTED | 관계 방향: UNDIRECTED / NATURAL / REVERSE |
✔ hop과 orientation 파라미터는 /cluster_finder와 동일하게 적용됩니다. hop=1로 설정하면 직접 연결된 키워드만 빠르게 수집할 수 있어 탐색 초기에 유용합니다.
요청 예시
기본 요청
{
"keyword": "OO 냉장고",
"gl": "kr"
}
hop 축소로 빠른 탐색
{
"keyword": "OO 냉장고",
"gl": "kr",
"hop": 1, "limit": 200
}
순방향 관계 키워드만 수집
{
"keyword": "OO 냉장고",
"gl": "kr",
"orientation": "NATURAL", "limit": 300
}
응답 데이터 구조 (Response)
응답 데이터 구조 요약
| 필드 | 타입 | 설명 |
| result | string | “OK” 또는 “FAILED” |
| cost_detail | object | 입력 30 Cr + 출력 2 Cr × 반환 키워드 수 |
| remain_credits | integer | 요청 후 잔여 크레딧 |
| data | array[string] | 관계 네트워크에 등장한 키워드 목록 |
응답 예시
{
"result": "OK",
"cost_detail": { "input_cost": 30, "output_cost": 100, "total_cost": 130 },
"data": [
"OO 냉장고 오브제", "OO 냉장고 가격",
"디오스 냉장고", "OO 냉장고 후기",
"에너지 1등급 냉장고"
]
}
과금 구조 상세
| 구분 | 기준 | 단가 | 예시 |
| 입력 과금 | 요청 1회당 | 30 크레딧 | 고정 비용 |
| 출력 과금 | 반환 키워드 1개당 | 2 크레딧 | 키워드 500개 → 1,000 크레딧 |
| 합계 (기본 limit: 500) | – | 1,030 크레딧 | 30 + 1,000 |
| /cluster_finder vs /cluster_finder/keyword_list 과금 비교 | |
| /cluster_finder (limit: 500) | 25,150 크레딧 |
| /cluster_finder/keyword_list (limit: 500) | 1,030 크레딧 |
| 절감액 (추정) | 약 24,120 크레딧 (약 96% 절감) |
✔ 클러스터 분석이 처음이라면 /cluster_finder/keyword_list로 네트워크 키워드를 먼저 확인하고, 유망 키워드에 대해서만 /cluster_finder를 호출하는 2단계 전략을 권장합니다.
활용 시나리오
단계별 클러스터 분석 전략
| 단계 | 사용 API | 목적 | 비용 |
| 1단계: 키워드 풀 수집 | /cluster_finder/keyword_list | 관계 네트워크 키워드 목록 확보 | 낮음 |
| 2단계: 관심 키워드 심층 분석 | /cluster_finder 또는 /keyword_info | 클러스터 구조 파악 또는 상세 지표 확인 | 선택적 |
Intent_finder/keyword_list와 Cluster_finder/keyword_list 통합 활용
두 API를 조합하면 더 넓은 키워드 풀을 확보할 수 있습니다. 단, 중복 키워드가 다수 존재하기 때문에 이중 과금이 될 수 있습니다.
| API | 수집 관점 | 특징 |
| Intent Finder Keyword List | 검색 의도 기반 연관 키워드 | 함께 검색된 키워드 (의도 중심) |
| Cluster Finder Keyword List | 관계 네트워크 기반 키워드 | 연결 구조 기반 키워드 (관계 중심) |
| 통합 | 두 결과 합산 + 중복 제거 | 보다 포괄적인 키워드 풀 |
연계 API
| 연계 API | 활용 방법 | 얻는 인사이트 |
| /keyword_info | 수집 키워드를 일괄 입력 | 검색량, CPC, 의도, 인구통계 상세 확인 |
| /cluster_finder | 선별 키워드로 상세 클러스터 분석 | 소비자 인식 그룹 및 관계 네트워크 |
| /path_finder/keyword_list | 경로 키워드와 합산 | 여정+관계 통합 키워드 풀 구성 |
자주 묻는 질문 (FAQ)
Q1. /cluster_finder/keyword_list 결과와 /cluster_finder에서 추출한 키워드는 동일한가요?
동일한 파라미터 기준에서 포함 키워드 집합은 동일합니다. 차이는 /cluster_finder가 rels/communities 구조까지 포함한다는 점입니다.
Q2. orientation: NATURAL과 REVERSE의 키워드 목록이 다르게 반환되나요?
네. NATURAL은 중심 키워드 이후에 탐색된 키워드, REVERSE는 이전에 탐색된 키워드를 기준으로 관계 네트워크를 형성하므로, 반환 키워드 목록이 달라질 수 있습니다.
Q3. hop=3과 hop=2의 결과 키워드 수 차이가 얼마나 되나요?
hop이 1 증가할 때마다 결과 수가 수 배에서 수십 배 증가할 수 있습니다 (추정: 네트워크 밀도에 따라 크게 다름). limit 파라미터로 최대 반환 수를 제한하여 관리하세요.
