1. API 개요
이 문서는 각 엔드포인트에 대한 기능, 요청 및 응답 데이터 구조를 요약하여 설명합니다.
- API 명: ListeningMind Data API
- OpenAPI Version: v0.0.36
- Base URL: https://listeningmind-data-api.ascentlab.io
- 인증 방식: Header,LM-API-KEY
- Source: OpenAPI JSON
- 과금 구조: Credit 기반 (input/output cost)
- Website: https://www.listeningmind.com
2. API 항목 요약
| Category | API Name | Method | Path | 핵심 기능 |
| Keyword | Keyword Info | POST | /keyword_info | 키워드 메타 + 검색/광고 데이터 |
| Intent | Intent Finder | POST | /intent_finder/keyword_list | 연관 키워드 리스트 |
| Journey | Path Finder | POST | /path_finder | 검색 경로 분석 |
| Journey | Path Finder List | POST | /path_finder/keyword_list | 경로 키워드 리스트 |
| Network | Cluster Finder | POST | /cluster_finder | 키워드 관계/클러스터 |
| Network | Cluster Finder List | POST | /cluster_finder/keyword_list | 관계 키워드 리스트 |
3. Request 파라미터
3.1. 전 엔드포인트 공통 파라미터
| 파라미터 | 타입 | 필수 | 설명 |
| keyword/keywords | string, string[] | V | 분석 대상 키워드(단일 또는 배열). 영어 키워드는 소문자 권장 |
| gl | string | V | 국가 코드. 반드시 “kr”, “jp”, “us” 중 하나 |
- gl(geolocation) 기준 국가 설정 : 검색량, SERP, 의도, 관계, 커뮤니티 모두 gl(kr/jp/us) 기준으로 계산
- keywords vs keyword
- 배열: /keyword_info, /intent_finder
- 단일: /path_finder, /cluster_finder
3.2. 데이터 범위·시점 관련 공통 파라미터
| 파라미터 | 타입 | 기본값 | 사용 API | 설명 |
| time_point | string | “curr” | path_finder, cluster_finder | 데이터 기준 시점 curr / 3m / 6m / 9m / 12m |
- curr : 현재 시점 소비자 인식 / 검색 구조
- 3m~12m : 과거 인식·행동 변화 비교용
3.3. 결과 크기·범위 제어 공통 파라미터
| 파라미터 | 타입 | 기본값 | 최대 | 사용 API | 설명 |
| limit | integer | API별 상이 | API별 상이 | intent / path / cluster | 반환 결과 개수 제한 |
| hop | integer | 2 | 3 | cluster_finder | 관계 확장 깊이 |
limit
- 작게 → 빠른 탐색 / 비용 절감
- 크게 → 구조 분석 / 네트워크 파악
hop
- 1 : 직접 연관만
- 2 : 실무에서 가장 많이 쓰는 기본값
- 3 : 탐색용 (복잡, 비용↑)
3.4. 데이터 종류 선택 파라미터
| 파라미터 | 사용 API | 기본값 | 설명 |
| data_type | keyword_info | “ads_metrics” | 반환 데이터 범위 선택 |
| cluster_finder | “communities” | 반환 구조 선택 |
keyword_info 기준
| 값 | 포함 데이터 |
| ads_metrics | 검색량, CPC, 경쟁도 |
| ads_info | ads_metrics + 월별 검색량 |
| all | 전체 (SERP, 의도, 인구통계 포함) |
cluster_finder 기준
| 값 | 의미 |
| communities | 소비자 인식/맥락 클러스터 |
| rels | 키워드 관계 엣지 |
| all | 둘 다 |
3.5. 정렬·필터 공통 파라미터
| 파라미터 | 타입 | 기본값 | 설명 |
| volume_threshold | integer | 100 | 최소 검색량 필터 |
| sort | string | volume_avg | 정렬 기준 |
| order | string | desc | 정렬 방향 |
Sort 옵션
- volume_avg : 월평균 검색량
- volume_total : 연간 총 검색량
- volume_trend : 증감률
- cpc : 광고 단가
- competition_index : 광고 경쟁도
3.6. 관계 방향성 파라미터
| 파라미터 | 타입 | 기본값 | 설명 |
| orientation | string | “UNDIRECTED” | 관계 방향성 |
| 값 | 기술적 의미 | 해석 |
| UNDIRECTED | Undirected Edge | 양방향 관계 |
| NATURAL | Directed (forward) | 실제 검색 흐름 |
| REVERSE | Directed (reverse) | 역방향 흐름 |
4. Request / Response schema
4.1. 엔드포인트별 필수 파라미터/주요 응답 데이터 구조
| 엔드포인트 | Request | Response |
| /keyword_info | Keywords : 조회할 키워드 목록 [ 1~1000 ] gl : (geolocation, 필수) 국가 코드 (kr/jp/us) Data_type : 데이터 타입 Enum: “ads_metrics” “ads_info” “all” ads_metrics: ads_metrics ads_info: ads_metrics, monthly_volume all: 전체 | Data [ ] 배열에 각 키워드에 대한 상세 정보 포함 ① ads_metrics: 광고 경쟁도, CPC, 검색량 등 competition/competition_index/cpc/입찰가/검색량(volume_avg, total, trend) + 구글/네이버 각 검색량(gg_/nv_) *volume_avg, total, trend 지표는 한국만 구글과 네이버 검색량 합계 산출 ② features: SERP 노출 타입 카운트 ③ intents: 검색 의도(정보형, 이동형, 상업형, 거래형 구분) i(infomational)/n(navigational)/c(commercial)/t(transactional) ④ demography: 성별·연령 flag + *_ratio ⑤ monthly_volume(*데이터 타입을 ads_info/all 선택시에만 출력): 월별 검색량(gg/nv/total) *월별 검색량은 구글(gg), 네이버(nv), 구글 네이버 합계(total) |
| /intent_finder/keyword_list | Keywords : 검색에 사용할 키워드 목록 [ 1~100 ] gl : (geolocation, 필수) 국가 코드 (kr/jp/us) volume_threshold : 검색량 임계값 설정 limit : 키워드 수 제한(1~10,000) sort : 정렬 기준 설정 volume_avg: 월 평균 검색량 volume_total: 연간 총 검색량 volume_trend: 증감률 cpc: CPC(USD) competition_index: 광고 경쟁도 order : 내림차순(desc)/오름차순(asc) | data: string[] (연관 키워드 리스트) [default] 검색량 임계값(volume_threshold) : 100 이상 키워드 수 제한(limit) : 100 정렬 기준(sort) : 월평균 검색량(volume_avg) 정렬 순서(order) : 내림차순(desc) *키워드의 검색량(volume_avg, total, trend) 상세 지표를 포함하지 않음. |
| /path_finder | keyword: (필수) 경로 분석의 중심이 될 키워드[1] gl : (geolocation, 필수) 국가 코드 (kr/jp/us) time_point: 데이터 조회 시점 curr: 현재 3m: 3개월 전 6m: 6개월 전 9m: 9개월 전 12m: 12개월 전 limit : 관계 수 제한(1~10,000) | data: string[][] (검색 경로 시퀀스) — 검색 여정 흐름(이전→현재→이후) 기반, 반복 등장 키워드는 주요 탐색 단계/의도 후보 [default] 데이터 조회 시점(time_point) : 현재(curr) 경로 수 제한(limit) : 300 |
| /path_finder/keyword_list | keyword: (필수) 경로 분석의 중심이 될 키워드[1] gl : (geolocation, 필수) 국가 코드 (kr/jp/us) time_point: 데이터 조회 시점 curr: 현재 3m: 3개월 전 6m: 6개월 전 9m: 9개월 전 12m: 12개월 전 limit : 관계 수 제한(1~10,000) | data: string[] (경로에 등장하는 키워드 리스트) — 경로 분석 키워드 풀을 빠르게 확보(확장/필터링 용) [default] 데이터 조회 시점(time_point) : 현재(curr) 경로 수 제한(limit) : 300 |
| /cluster_finder | keyword: (필수) 관계를 분석할 중심 키워드[1] gl : (geolocation, 필수) 국가 코드 (kr/jp/us) time_point: 데이터 조회 시점 curr: 현재 3m: 3개월 전 6m: 6개월 전 9m: 9개월 전 12m: 12개월 전 limit : 관계 수 제한(1~10,000) hop: 확장의 깊이 (1~3) orientation : 관계 방향 설정 undirected: 무방향 natural: 순방향(이후 네트워크) reverse: 역방향(이전 네트워크) Data_type : 데이터 타입 Enum: “communities” “rels”, “all” communities: 커뮤니티 rels : 관계 all : 전체 | data: {rels, communities} ① rels: [source,target][] 관계 엣지 사용자의 검색 행동으로 생긴 연결선으로 같이 연결해서 검색한 한 쌍의 키워드 목록 출력 *출력되는 데이터는 서로 연결되어 있을 뿐, 순서와는 무관함. ② communities: {cluster_id: string[]} 여러 개의 키워드가 한 그룹(string 배열)로 묶인 데이터 출력, 소비자 인식 속 하나의 주제 덩어리로 해석 hop=확장 깊이, orientation=방향, data_type=반환 범위 옵션 설정에 따라 출력 [default] 데이터 조회 시점(time_point) : 현재(curr) 관계 수 제한(limit) : 500 확장 깊이(hop) : 2 관계 방향(orientation) : 무방향(undirected) 데이터 타입(data_type) : 커뮤니티(communities) |
| /cluster_finder/keyword_list | keyword: (필수) 관계를 분석할 중심 키워드[1] gl : (geolocation, 필수) 국가 코드 (kr/jp/us) time_point: 데이터 조회 시점 curr: 현재 3m: 3개월 전 6m: 6개월 전 9m: 9개월 전 12m: 12개월 전 limit : 관계 수 제한(1~10,000) hop: 확장의 깊이 (1~3) orientation : 관계 방향 설정 undirected: 무방향 natural: 순방향(이후 네트워크) reverse: 역방향(이전 네트워크) | data: string[] (관계 기반 키워드 리스트) — rels/communities 상세 전에 후보 키워드 빠른 확보 [default] 데이터 조회 시점(time_point) : 현재(curr) 관계 수 제한(limit) : 500 확장 깊이(hop) : 2 관계 방향(orientation) : 무방향(undirected) |
4.2. 엔드포인트별 요청/반환 기준
| API | 요청 키워드 최대 | 반환 기본값 | 반환 최대값 | 비고 |
| keyword_info | 1,000 | 요청 수와 동일 | 요청 수와 동일 | 대량 분석 핵심 |
| intent_finder | 100 | 100 | 10,000 | 키워드 확장 |
| path_finder | 1 | 300 | 1,000 | 검색 여정 |
| cluster_finder | 1 | 500 | 10,000 | 관계/인식 분석 |
/keyword_info
| 구분 | 값 |
| 요청 키워드 수 | 최소 1개 / 최대 1,000개 |
| 반환 단위 | 키워드 단위 결과 |
| 반환 개수 | 요청 키워드 수와 동일 |
| 기본 data_type | ads_metrics |
| data_type별 반환 범위 | ads_metrics / ads_info / all |
- 키워드 1,000개를 넣으면 → 결과도 1,000개
- 반환 개수 제한은 keywords 배열 크기로 제어
- 대량 분석용 핵심 API
/intent_finder/keyword_list
| 구분 | 값 |
| 요청 키워드 수 | 최소 1개 / 최대 100개 |
| 반환 단위 | 연관 키워드 리스트 |
| 반환 개수 기본값 | 100개 |
| 반환 개수 최대값 | 10,000개 |
| 반환 제어 파라미터 | limit |
| 정렬 기본값 | volume_avg desc |
- 1개의 seed 키워드 → 최대 10,000개 연관 키워드
- 실무에서는 100~500 권장
- 키워드 확장 / SEO / 콘텐츠 기획용
/path_finder
| 구분 | 값 |
| 요청 키워드 수 | 1개 (단일) |
| 반환 단위 | 검색 경로(path) |
| 반환 개수 기본값 | 300개 |
| 반환 개수 최대값 | 1,000개 |
| 반환 제어 파라미터 | limit |
- 결과 1개 = 하나의 검색 여정 시퀀스
- limit ↑ → 비용·응답 크기 증가
- 300이 실무 기본값
/cluster_finder
| 구분 | 값 |
| 요청 키워드 수 | 1개 (단일) |
| 반환 단위 | 관계 엣지(rels) 또는 커뮤니티 |
| 반환 개수 기본값 | 500개 |
| 반환 개수 최대값 | 10,000개 |
| 반환 제어 파라미터 | limit |
| 관계 확장 깊이 | hop (기본 2 / 최대 3) |
| 기본 data_type | communities |
- limit = 관계 수(엣지 수 또는 키워드 수) 기준
- hop이 커질수록 결과 폭발적으로 증가
- hop=2 + limit=300~500이 실무 안전 구간
5. Metrics
5.1. 검색 수요 · 광고 메트릭스 (ads_metrics)
| Category | Metric | 설명 | Value (예시) |
| ads_metrics | competition | 광고 경쟁 강도(LOW, MEDIUM, HIGH) | HIGH |
| competition_index | 광고 경쟁도_수치(0~100) | 100 | |
| cpc | 클릭당 비용 (CPC, USD 기준) | 1.41 | |
| low_bid_micros | CPC_경쟁도낮음(낮은 입찰가) | 389992 | |
| high_bid_micros | CPC_경쟁도높음(높은 입찰가) | 3283108 | |
| volume_avg | 월 평균 검색량_최근 3개월 월별 검색량 평균 | 275133 | |
| volume_total | 연간 총 검색량_최근 12개월 월별 검색량 합산 | 3301900 | |
| volume_trend | 트렌드_3개월 전 대비 최근 월 검색량 증감률 | 0.19 | |
| gg_volume_avg | 구글 월 평균 검색량_최근 3개월 월별 검색량 평균 | 36033 | |
| gg_volume_total | 구글 연간 검색량_최근 12개월 월별 검색량 합산 | 432396 | |
| gg_volume_trend | 구글 트렌드_3개월 전 대비 최근 월 검색량 증감률 | ||
| nv_volume_avg | 네이버 월 평균 검색량_최근 3개월 월별 검색량 평균 | 239100 | |
| nv_volume_total | 네이버 연간 검색량_최근 12개월 월별 검색량 합산 | 2869200 | |
| nv_volume_trend | 네이버 트렌드_3개월 전 대비 최근 월 검색량 증감률 |
5.2. SERP 노출 메트릭스 (features)
해당 키워드 검색 시, 구글 검색결과 페이지에 어떤 형태의 콘텐츠가 얼마나 노출되는지 확인
| Category | Metric | 설명 | Value (예시) |
| 생성형 AI 요약 Features | f_ai_overview | Google SERP 상단에 AI Overview(생성형 요약) 블록 노출 | 1 |
| 광고(Ads) Features | f_ads_top | 검색 결과 상단 광고 블록(복수) 노출 | 1 |
| f_ads_bottom | 검색 결과 하단 광고 블록(복수) 노출 | 1 | |
| 오가닉 결과 (Organic Results) Features | f_organic_results | 오가닉 검색결과(Organic Results) 노출 수, 광고 및 특수 SERP feature를 제외한 일반 웹 문서(organic link) 결과 수 | 17 |
| f_organic_results_rating | 별점(rich rating)이 포함된 오가닉 결과 수 | 3 | |
| f_organic_results_video | 비디오가 포함된 오가닉 결과 수 | 2 | |
| Featured Snippet | f_featured_snippet | Featured Snippet 노출 여부 | 1 |
| f_featured_snippet_ordered_list | 순서형 리스트 스니펫 | 0 | |
| f_featured_snippet_unordered_list | 비순서 리스트 스니펫 | 1 | |
| f_featured_snippet_table | 테이블 형태 스니펫 | 0 | |
| f_featured_snippet_video_exist | 스니펫 내 비디오 포함 | 0 | |
| 질문·연관 탐색 Feature | f_people_also_ask_for | People Also Ask(PAA) 노출 | 1 |
| f_people_also_search_for | People Also Search For 노출 | 1 | |
| f_related_searches | SERP 하단 연관 검색어 노출 | 1 | |
| f_spell_check | 오타 교정/대체 쿼리 제안 | 0 | |
| 미디어·콘텐츠 타입 Feature | f_images | 이미지 블록 노출 | 2 |
| f_video_results | 비디오 결과 노출 | 1 | |
| f_video_carousels | 비디오 캐러셀 노출 | 0 | |
| f_articles | 뉴스/기사 결과 노출 | 0 | |
| f_sns | SNS 결과 노출 | 1 | |
| 엔티티·브랜드·로컬 Feature | f_knowledge_panel | Knowledge Panel 노출 | 1 |
| f_sitelinks | Sitelinks 확장 결과 | 1 | |
| f_local_results | 로컬(Map Pack) 결과 | 0 | |
| f_google_play | Google Play 결과 | 0 | |
| f_app_results | 앱 결과 노출 | 0 |
5.4. 검색 의도 메트릭스 (intents)
해당 의도가 유의미하게 나타났는지 여부(1/0) 확인
| Category | Metric | 설명 | Value (예시) |
| Intents | I (Informational) | 정보형(Informational) 의도 | 1 |
| N (Navigational) | 이동형(Navigational) 의도 | 0 | |
| C (Commercial) | 상업형(Commercial) 의도 | 0 | |
| T (Transactional) | 거래형(Transactional) 의도 | 1 |
5.5. 사용자 인구 통계 메트릭스 (demography)
성별/연령 특성이 유의미하게 나타났는지 여부(1/0) 확인
| Category | Metric | 설명 | Value (예시) |
| Demography | m_gender | 남성 검색 비중이 높을 경우 | 0 |
| f_gender | 여성 검색 비중이 높을 경우 | 1 | |
| a0 | 3세 이하 비중이 높을 경우 | 0 | |
| a13 | 3~19세 비중이 높을 경우 | 0 | |
| a20 | 20~24세 비중이 높을 경우 | 0 | |
| a25 | 25~29세 비중이 높을 경우 | 0 | |
| a30 | 30~39세 비중이 높을 경우 | 1 | |
| a40 | 40~49세 비중이 높을 경우 | 1 | |
| a50 | 50세 이상 비중이 높을 경우 | 0 | |
| m_gender_ratio | 전체 검색량 중 성별특성(남성)의 검색 비율(%) | 44.23 | |
| f_gender_ratio | 전체 검색량 중 성별특성(여성)의 검색 비율(%) | 55.76 | |
| a0_ratio | 전체 검색량 중 연령대별특성(3세 이하) 검색 비율(%) | 0 | |
| a13_ratio | 전체 검색량 중 연령대별특성(3~19세) 검색 비율(%) | 0.53 | |
| a20_ratio | 전체 검색량 중 연령대별특성(20~24세) 검색 비율(%) | 3.08 | |
| a25_ratio | 전체 검색량 중 연령대별특성(25~29세) 검색 비율(%) | 8.60 | |
| a30_ratio | 전체 검색량 중 연령대별특성(30~39세) 검색 비율(%) | 26.12 | |
| a40_ratio | 전체 검색량 중 연령대별특성(40~49세) 검색 비율(%) | 33.40 | |
| a50_ratio | 전체 검색량 중 연령대별특성(50세 이상) 검색 비율(%) | 27.12 |
5.6. 월별 검색량 메트릭스 (monthly_volume)
| Category | Metric | 설명 | Value (예시) |
| Monthly_volume | month | 기준 월 | 2025-07 |
| gg | 구글 검색량 | 110000 | |
| nv | 네이버 검색량 | 262100 | |
| Total | 전체 검색량(구글, 네이버 합계) | 372100 |
5.7. 검색 경로 메트릭스 (path_finder)
| Category | Metric | 설명 | Value (예시) |
| Path_finder | path | 검색 여정 시퀀스 | [“냉장고”, “lg 냉장고”, “lg 냉장고 가격”] |
5.8. 관계 네트워크 메트릭스 (cluster_finder)
| Category | Metric | 설명 | Value (예시) |
| Cluster_finder | rels | 검색 행동 기반 연결 | [“lg 냉장고”, “lg 냉장고 오브제”] |
| communities | 동일 인식의 키워드 묶음 | “1”: [“lg 냉장고 오브제”, “디오스 오브제”, “오브제 컬렉션”] |
6. 데이터프레임 예시 (csv)
| 순서 | 컬럼명 | 설명 | 데이터 예시 |
| 1 | 키워드 | 분석 대상이 되는 핵심 검색어입니다. | 키크는 영양제 |
| 2 | 월 평균 검색량 | 구글과 네이버의 월 평균 검색량을 합산한 수치입니다. | 275133 |
| 3 | 연간 총 검색량 | 최근 12개월 동안의 총 검색량을 나타냅니다. | 3301900 |
| 4 | 3개월 전 대비 증감률(%) | 최근 3개월간의 검색량 변화 추이를 백분율로 보여줍니다. | 0.19 |
| 5 | CPC (USD) | 클릭당 비용(Cost Per Click)으로, 광고 효율성을 파악하는 지표입니다. | 1.41 |
| 6 | 광고경쟁도(%) | 해당 키워드의 구글 검색 광고 경쟁 수준을 나타냅니다. (0~100) | 100 |
| 7 | 검색노출타입 | 구글 검색 결과 페이지(SERP)에 노출되는 스니펫 종류입니다. | 이미지 블록, 동영상 블록 |
| 8 | 검색 인텐트 | 사용자의 검색 의도를 나타냅니다. (정보형, 상업형, 거래형 등) | 정보형, 거래형 |
| 9 | 성별 특성 | 특정 성별에서 검색 비중이 두드러지는 경우 표시됩니다. | 여성 |
| 10 | 남성(%) / 여성(%) | 전체 검색량에서 각 성별이 차지하는 비율을 보여줍니다. | 44.84 / 55.15 |
| 11 | 연령대별 특성 | 특정 연령대에서 검색 비중이 두드러지는 경우 표시됩니다. | 30대, 40대 |
| 12 | 12세 이하(%) ~ 50세 이상(%) | 전체 검색량에서 각 연령대가 차지하는 비율을 보여줍니다. | 26.5 (30대 예시) |
| 13 | YYYY-MM (날짜 형식) | 월별 상세 검색량을 나타내는 컬럼들입니다. (예: 2021-09) | 해당 월의 검색량 (숫자) |
