---
title: 소비자 인식 및 관계 네트워크 분석 API (/cluster_finder) 활용 가이드
description: "Cluster Finder API는 중심 키워드를 기반으로 소비자 검색 행동에서 형성된 키워드 관계 네트워크(rels)와 소비자 인식 그룹(communities)을 반환합니다. 단순 연관 키워드 목록을 넘어, 키워드 간 연결 구조와 소비자 인식 속의 \"개념 덩어리\"를 파악할 수 있는 심층 분석 데이터입니다. ## 두 가지…"
url: "https://kr.listeningmind.com/data-api/api-reference/cluster-finder-api/"
updated: "2026-10-16"
category: API 레퍼런스
tags:
  - 관계 네트워크 분석
  - 데이터 API
  - 리스닝마인드 DaaS
---

# 소비자 인식 및 관계 네트워크 분석 API (/cluster_finder) 활용 가이드

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 호출로 처리되므로 각각 과금됩니다.