data-requirements.md

검색 인텐트 분석기 — 데이터 요구사항 정리

MVP 목업(search_intent_mvp_dashboard.html)을 실제 통합 대시보드로 만들기 위한 데이터 정의 문서. 구현 전 데이터 소스·스키마를 먼저 확정하는 것이 목적이다.

1. 화면 컴포넌트 → 필요 데이터 매핑

#	화면 블록	필요 데이터 (원천 단위)	1차 소스	확보
1	총 검색량 카드	키워드별 PC/모바일 월 검색량	네이버 검색광고 API	✅
2	경쟁강도 카드	키워드별 경쟁정도 지수 (CPC는 보류)	네이버 검색광고 API	✅
3	인텐트 그룹 수 카드	클러스터 개수, 분류 키워드 수	파생	✅
4	의도 비중 도넛	키워드별 의도 라벨	AI 분류(Claude Haiku 4.5)	✅
5	인구통계 막대	시드별 성별×연령 검색 비율(상대지수)	네이버 데이터랩	⚠️
6	클러스터링 테이블	클러스터명, 대표 키워드셋, 그룹 검색량, 대표 의도	파생(S-BERT+HDBSCAN)	✅
7	검색 경로 네트워크	키워드 간 연결, 연관도, 깊이	연관검색어/자동완성 기반 추정	⚠️

2. 데이터 소스 현실성 점검

네이버 검색광고 API — ✅ 광고 집행 불필요

• 검색광고 계정 무료 생성 → 광고비 0원으로 키워드도구 API(RelKwdStat) 호출 가능.
• 제공: 연관키워드, 월간 검색수(PC/모바일 분리), 경쟁정도(낮음/중간/높음), 평균 클릭수·클릭률, 평균 노출 광고수.
• ❌ 미제공: CPC(평균 입찰가)는 키워드도구가 직접 주지 않음. 별도 입찰가 추정 API 필요 + 광고 이력 없으면 품질 낮음 → MVP는 CPC 대신 경쟁정도 지수를 카드 지표로 사용.

구글 Ads API (Keyword Planner) — ⚠️ 반쪽 데이터

• 계정 생성 무료이나 두 가지 벽:
  1. Developer Token 승인 필요 (운영 데이터 호출 시).
  2. 광고비 미지출 시 검색량이 정확 수치가 아니라 구간값(예: "1만~10만")으로만 제공됨. 정확한 월 검색수를 받으려면 활성 캠페인 + 광고비 지출이 사실상 전제.
• → 광고비 없으면 검색량을 구간값 보조 지표로만 활용.

무료 보강 소스

• 네이버 데이터랩: 연령·성별·기기 트렌드. 절대량 아님, 0~100 상대지수. 그룹 내 비율로만 표시.
• 구글 트렌드: 상대지수만.

순차 검색 경로(7번) — 핵심 제약

• 개인 단위 클릭스트림(A 검색 후 B 검색)은 네이버·구글 모두 외부 미제공. SMB가 살 수 없음.
• 대안: 연관검색어 / 자동완성 / 함께 많이 본 키워드로 연결망을 추정.
  • "연관도 76%"는 실제 전환율이 아니라 임베딩 코사인 유사도 또는 동시출현 빈도로 재정의.
  • depth는 시드 키워드로부터의 그래프 거리로 계산.

3. 권장 소스 구성 (SMB 초저비용 MVP)

주력  : 네이버 검색광고 API   → 검색량 · 경쟁정도
보조  : 네이버 데이터랩       → 연령/성별/기기 (상대지수)
보조  : 구글 트렌드 / Ads     → 상대지수 · 검색량 구간값
파생  : Claude Haiku 4.5      → 의도 분류
파생  : S-BERT + HDBSCAN      → 의미 클러스터 · 경로 추정

4. 결측치·이상치 처리 (수집 시점 선처리)

• 검색량 마스킹: 네이버는 검색량 1,000 미만을 < 10으로 마스킹 → NULL 대신 하한 대체값 + is_masked 플래그 보존.
• CPC 0/결측: 광고 미집행 키워드 제외 (포함 시 단가 왜곡). MVP는 CPC 자체를 보류.
• 검색량 이상치: 시즌 폭증 키워드가 평균 왜곡 → 카드 지표는 평균 대신 중앙값/IQR 클리핑.
• 클러스터 노이즈: HDBSCAN -1은 is_noise=true로 보관하되 집계·화면에서 제외.
• 데이터랩 정규화: 상대지수라 채널 간 합산 불가 → 성별/연령은 그룹 내 비율로만 표시.

5. 통합 대시보드 연동

• 모든 테이블에 seed_keyword(또는 seed_id)를 키로 두고 대시보드는 이 값으로 필터.
• 수집을 배치(주 1회)로 돌리고 collected_date 스냅샷을 누적하면 "전월 대비 %" 추세 자동 계산.
• 대용량 적재 시 chunksize=20,000 배치 insert.

6. 미결정 사항

1. 검색 경로(7번)를 "추정 경로"로 대체할지, 블록 보류할지.
2. 구글 Ads 구간값 데이터를 포함할지, 네이버 단일 소스로 시작할지.