Cluster Finder API는 중심 키워드를 기반으로 소비자 검색 행동에서 형성된 키워드 관계 네트워크(rels)와 소비자 인식 그룹(communities)을 반환합니다. 단순 연관 키워드 목록을 넘어, 키워드 간 연결 구조와 소비자 인식 속의 “개념 덩어리”를 파악할 수 있는 심층 분석 데이터입니다.
두 가지 데이터 타입: rels vs communities
| 구분 | rels (관계) | communities (커뮤니티) |
| 형식 | array of [source, target] | { cluster_id: string[] } 객체 |
| 내용 | 함께 검색된 키워드 쌍 (무방향/방향 가능) | 소비자 인식상 하나의 주제로 묶인 키워드 그룹 |
| 활용 | 그래프·네트워크 분석, 관계 시각화 | CEP 도출, 메시지 세그먼트, 콘텐츠 포지셔닝 |
| 기본 data_type | – | communities (기본값) |
핵심 특징 요약
| 항목 | 상세 |
| 엔드포인트 | POST /cluster_finder |
| 요청 키워드 수 | 1개 (단일 키워드) |
| 반환 형식 | data: { rels: [][], communities: {} } |
| 반환 기본 개수 | 500개 (관계 수 기준) |
| 반환 최대 개수 | 10,000개 |
| 지원 국가(gl) | kr / jp / us |
| 과금 방식 | 입력 150 크레딧 + 출력 50 크레딧/키워드 |
소비자 인식 및 관계 네트워크 분석 API (/cluster_finder)는 언제 사용하나?
| 사용자 질문 | 활용 방향 |
| 소비자가 이 키워드를 어떤 맥락으로 인식하나요? | communities로 인식 그룹 파악 |
| 카테고리 진입점(CEP)이 어디인가요? | communities 클러스터별 주제 분석 |
| 키워드 간 연결 관계를 네트워크로 보고 싶어요. | rels 데이터로 그래프 시각화 |
| 브랜드 포지셔닝 전략을 세우고 싶어요. | 커뮤니티별 소비자 인식 그룹 분석 |
| 경쟁 브랜드와 함께 묶이는 키워드를 알고 싶어요. | NATURAL/REVERSE 방향 분석 |
| 6개월 전과 지금 소비자 인식이 달라졌나요? | time_point 비교 분석 |
요청 파라미터 (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~10,000) |
| hop | integer | N | 2 | 관계 확장 깊이 (1~3) |
| orientation | string | N | UNDIRECTED | 관계 방향: UNDIRECTED / NATURAL / REVERSE |
| data_type | string | N | communities | 반환 데이터: communities / rels / all |
관계 확장의 깊이 설정 – hop
| hop 값 | 의미 | 결과 규모 | 추천 상황 |
| 1 | 중심 키워드와 직접 연결된 키워드만 | 소규모 | 핵심 연관 키워드만 빠르게 확인 |
| 2 (기본) | 직접 연결 + 2단계 확장 | 중규모 | 실무 표준. 대부분의 분석에 적합 |
| 3 | 3단계까지 확장 | 대규모 (비용↑) | 전체 네트워크 탐색, 장기 전략 수립 |
⚠ hop=3은 결과 수가 폭발적으로 증가하여 과금이 크게 늘어납니다. hop=2 + limit=300~500이 실무 안전 구간입니다.
관계 방향성 설정 – orientation
| 값 | 기술적 의미 | 해석 | 활용 |
| UNDIRECTED (기본) | 무방향 관계 | 함께 검색된 쌍 (순서 무관) | 전체 연관 키워드 파악 |
| NATURAL | 순방향 (이후 네트워크) | 중심 키워드 검색 후 탐색한 키워드 | 전환 후 행동, 이탈 경로 파악 |
| REVERSE | 역방향 (이전 네트워크) | 중심 키워드 검색 전에 탐색한 키워드 | 퍼널 상위 진입 경로 파악 |
✔ NATURAL은 “이 키워드 이후 무엇을 찾나?“, REVERSE는 “이 키워드 이전에 무엇을 찾나?“를 보여줍니다. 두 방향을 비교하면 소비자 탐색 흐름의 전체 맥락을 파악할 수 있습니다.
반환 데이터 타입 선택 – data_type
| 값 | 반환 데이터 | 활용 |
| communities (기본) | 소비자 인식 그룹 { cluster_id: keywords[] } | CEP 도출, 메시지 세분화, 포지셔닝 |
| rels | 키워드 쌍 관계 엣지 [source, target][] | 네트워크 그래프 시각화, 관계 분석 |
| all | communities + rels 모두 | 종합 분석 |
요청 예시
커뮤니티 분석
{
"keyword": "OO 냉장고",
"gl": "kr",
"hop": 2, "limit": 300, "data_type": "communities"
}
순방향 관계 분석
{
"keyword": "OO 냉장고",
"gl": "kr",
"orientation": "NATURAL", "data_type": "rels"
}
시점 비교 (6개월 전)
{
"keyword": "OO 냉장고",
"gl": "kr",
"time_point": "6m", "data_type": "communities"
}
응답 데이터 구조 (Response)
data.communities 구조
communities는 cluster_id를 키로 하는 객체입니다. 각 클러스터는 소비자 인식상 하나의 주제를 공유하는 키워드 그룹입니다.
"communities": {
"0": ["OO 냉장고 가격", "OO 냉장고 할인", "OO 냉장고 싸게"],
"1": ["OO 냉장고 오브제", "디오스 오브제", "OO 오브제 컬렉션"],
"2": ["에너지 1등급 냉장고", "전기요금 냉장고", "저전력 냉장고"]
}
| 클러스터 ID | 주요 키워드 | 인식 주제 해석 | 마케팅 시사점 |
| 0 | 가격, 할인, 싸게 | 가격 민감 소비자 그룹 | 프로모션·할인 콘텐츠 전략 |
| 1 | 오브제, 디오스, 컬렉션 | 프리미엄 라인 관심 그룹 | 프리미엄 포지셔닝 강화 |
| 2 | 에너지 1등급, 전기요금 | 에너지 효율 관심 그룹 | 효율성 메시지 콘텐츠 |
data.rels 구조
rels는 [source, target] 쌍의 배열입니다. 두 키워드 사이에 검색 행동 기반 연결이 있음을 나타냅니다.
"rels": [
["냉장고", "OO 냉장고"],
["OO 냉장고", "OO 냉장고 오브제"],
["OO 냉장고", "OO 냉장고 가격"]
]
⚠ rels의 [source, target] 순서는 UNDIRECTED(기본)에서는 순서와 무관합니다. NATURAL 또는 REVERSE 설정 시 방향 의미가 생깁니다.
과금 구조 상세
| 구분 | 기준 | 단가 | 예시 |
| 입력 과금 | 요청 1회당 | 150 크레딧 | 고정 비용 |
| 출력 과금 | 반환 키워드 1개당 | 50 크레딧 | 관계 500개 → 25,000 크레딧 |
| 합계 (기본 limit: 500) | – | 25,150 크레딧 | 150 + 25,000 |
| limit | 총 과금 (추정) | 추천 상황 |
| 100 | 5,150 크레딧 | 초기 탐색, 빠른 아이디어 확인 |
| 300 | 15,150 크레딧 | 실무 분석 표준 |
| 500 (기본) | 25,150 크레딧 | 충분한 네트워크 커버 |
| 1,000 | 50,150 크레딧 | 심층 분석 |
✔ 비용 절감을 원한다면 /cluster_finder/keyword_list로 키워드 목록만 먼저 수집하고, 이후 필요한 시드에만 /cluster_finder를 호출하는 2단계 접근법을 권장합니다.
활용 시나리오
CEP(Category Entry Point) 도출
소비자가 구매를 고민할 때 떠올리는 상황과 맥락을 communities 클러스터에서 파악합니다
| 단계 | 작업 | 활용 데이터 |
| 1. 클러스터 수집 | 중심 키워드로 communities 조회 | data_type: “communities” |
| 2. 주제 해석 | 각 클러스터의 키워드 그룹에서 공통 주제 도출 | 클러스터 내 키워드 패턴 분석 |
| 3. CEP 정의 | 소비자 구매 진입 상황/맥락 명명 | 예: “가격 비교형”, “프리미엄 추구형” |
| 4. 메시지 설계 | CEP별 맞춤 광고·콘텐츠 메시지 개발 | 세그먼트별 크리에이티브 전략 |
orientation 방향별 활용
| 분석 목적 | orientation 설정 | 얻는 인사이트 |
| 전체 연관 네트워크 파악 | UNDIRECTED | 함께 검색되는 전체 키워드 생태계 |
| 이탈·전환 후 행동 분석 | NATURAL | 중심 키워드 이후 소비자가 탐색하는 키워드 |
| 퍼널 상위 진입 경로 파악 | REVERSE | 중심 키워드 이전에 탐색한 키워드 (상위 퍼널) |
오류 응답 처리
| HTTP Status | 주요 원인 | 조치 방법 |
| 401 Unauthorized | API Key 오류 | LM-API-KEY 헤더 확인 |
| 402 Payment Required | 크레딧 부족 | 충전 후 재요청 |
| 422 Unprocessable Entity | hop 범위 초과(3 초과), gl 오류 | 파라미터 값 확인 |
| 429 Too Many Requests | Rate Limit 초과 | 요청 속도 조절 |
| 500 Internal Server Error | 서버 오류 | 기술 지원 문의 |
자주 묻는 질문 (FAQ)
Q1. communities의 cluster_id(0, 1, 2…)는 어떤 기준으로 생성되나요?
cluster_id는 데이터에서 자동 감지된 그룹 번호로, 숫자 자체에 의미는 없습니다. 각 클러스터 내 키워드들의 공통 주제를 직접 분석하여 의미를 부여해야 합니다.
Q2. hop=3 설정 시 결과가 너무 많아서 분석이 어렵습니다.
hop=3은 결과가 폭발적으로 증가합니다. limit을 낮게 설정하거나(예: 100~300) orientation을 NATURAL 또는 REVERSE로 제한하면 관리 가능한 규모로 줄일 수 있습니다.
Q3. rels와 communities를 동시에 받으려면 어떻게 하나요?
data_type: “all”로 설정하면 rels와 communities를 한 번의 요청으로 모두 받을 수 있습니다.
Q4. 같은 키워드로 NATURAL과 REVERSE를 각각 조회하면 크레딧이 두 배 소모되나요?
네. orientation이 다른 두 요청은 별도 API 호출로 처리되므로 각각 과금됩니다.
