---
task_id: task-2101
type: context
scope: task
created: 2026-04-22
updated: 2026-04-22
status: in-progress
---

# 맥락 노트: task-2101

**task**: task-2101

---

## 결정 근거

### 네이버 SearchAd API로 전환 (DataLab → SearchAd /keywordstool)
- DataLab API는 검색 트렌드(상대 비율)만 제공, 프론트가 기대하는 검색량(monthlyPcQcCnt 등) 미제공
- 대시보드(`server_utils.py`)에서 동일 API 이미 동작 확인됨
- 대안: 네이버 DataLab + 블로그 검색 조합 → 기각 (검색량 데이터 부정확)

### 3 Step Why

**1st Why**: "왜 이 설계가 필요한가?"
→ 현재 DataLab API는 검색 트렌드(상대 비율)만 반환하여 keywordList 형식(relKeyword, monthlyPcQcCnt 등)이 없음. 프론트가 빈 결과를 표시하는 버그의 근본 원인.

**2nd Why**: "왜 SearchAd /keywordstool API가 최선인가?"
→ 네이버 공식 키워드 도구 API이며, 대시보드에서 이미 안정적으로 동작 중. relKeyword, monthlyPcQcCnt, monthlyMobileQcCnt, compIdx 등 프론트가 기대하는 정확한 필드를 반환함.

**3rd Why**: "왜 SearchAd API가 다른 대안보다 나은가?"
→ 대안1(DataLab 유지+변환): 상대 비율 → 절대 검색량 변환 불가. 대안2(제3자 API): 추가 비용 + 데이터 품질 미보증. SearchAd API는 무료, 공식, 정확한 데이터 제공.

## 참조 자료

- 대시보드 SearchAd 구현: `/home/jay/workspace/dashboard/server_utils.py:175-228`
- 네이버 SearchAd API 키: `/home/jay/workspace/.env.keys` (NAVER_SEARCHAD_*)
- Codex 사전 검증: `/home/jay/workspace/memory/events/task-2101.codex-gate`

## 주의사항

- SearchAd API는 HMAC-SHA256 서명 필요 (timestamp + method + path)
- API 키 3종 필요: CUSTOMER_ID, API_KEY, SECRET_KEY
- .env.keys에서 키 로딩 필요 (환경변수 fallback)