Naver Ad Performance
Businessnaver-ad-performanceNaver Ad Performance is an Agent Skill for business published in the NomaDamas/k-skill repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
네이버 검색광고(키워드광고)의 노출수·클릭수·광고비·CTR·CPC·전환수를 조회한다. 캠페인/광고그룹/키워드 목록, 기간별 성과, 연관키워드·월간 조회수 도구 포함. 읽기 전용, 로컬 실행 전용.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/NomaDamas/k-skill/blob/HEAD/naver-ad-performance/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/naver-ad-performance, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
네이버 검색광고 성과 조회
What this skill does
네이버 검색광고 API(HMAC-SHA256 서명 인증)를 감싸서 광고 계정의 성과 지표를 조회한다. 읽기 전용이며 입찰가·캠페인·키워드를 바꾸는 쓰기 작업은 하지 않는다.
- 캠페인/광고그룹/키워드 목록 조회
- 기간별 성과(노출수·클릭수·광고비·CTR·CPC·평균노출순위·전환수) 조회
- 연관키워드·월간 조회수·경쟁정도 조회 (키워드 도구)
- 키 셋업 여부와 네이버 API 도달성 진단(
doctor)
When to use
- "네이버 광고 노출수/클릭수/광고비/CTR 보여줘"
- "이번달 캠페인 성과 어때"
- "이 키워드 CTR·CPC 얼마야"
- "연관키워드랑 월간 조회수 뽑아줘"
- "네이버 검색광고 키 셋업이 됐는지 확인해줘"
When not to use
- 클라우드 샌드박스 환경: 네이버 검색광고 API는 로컬 egress가 필요하다. 클라우드 실행 에이전트(허용 도메인 목록 방식)에서는 도달하지 못할 수 있다 — 먼저
doctor로 확인한다. - 입찰가 변경, 캠페인/키워드 생성·수정·삭제: 이 스킬은 조회 전용이다. 광고 운영에 영향을 주는 쓰기 작업은 이 스킬 범위 밖이며 구현돼 있지 않다.
- 네이버 검색(블로그/뉴스/쇼핑) 결과 조회는
naver-blog-research,naver-news-search,naver-shopping-search스킬을 쓴다 — 이 스킬과는 다른 API다.
Prerequisites
- Python 3.9+
- 네이버 검색광고 계정 (searchad.naver.com) → 도구 > API 사용 관리에서 API 키/시크릿 발급
- 환경변수 3개:
NAVER_AD_API_KEY,NAVER_AD_SECRET_KEY,NAVER_AD_CUSTOMER_ID
키는 사용자가 직접 발급해 credential resolution order(docs/security-and-secrets.md)에 따라 공급한다. 에이전트가 값을 대신 입력하지 않는다.
Workflow
1. 진단
python3 naver-ad-performance/scripts/naver_ad_performance.py doctor
키 3개 존재 여부와 api.searchad.naver.com 도달 가능 여부를 보여준다. reachable: false면 로컬(클로드 코드/코덱스 CLI) 환경에서 다시 실행하도록 안내한다.
2. 구조 조회 (id가 필요할 때)
python3 naver-ad-performance/scripts/naver_ad_performance.py campaigns
python3 naver-ad-performance/scripts/naver_ad_performance.py adgroups --campaign <nccCampaignId>
python3 naver-ad-performance/scripts/naver_ad_performance.py keywords --adgroup <nccAdgroupId>
3. 성과 조회 (핵심)
python3 naver-ad-performance/scripts/naver_ad_performance.py stats --ids <id1,id2> --since 2026-06-01 --until 2026-06-30
python3 naver-ad-performance/scripts/naver_ad_performance.py stats --ids <id> --since 2026-06-01 --until 2026-06-30 --by day
ids는 캠페인/광고그룹/키워드 id를 콤마로 구분해 섞어 넣을 수 있다. --since/--until을 생략하면 네이버 기본 기간(최근)으로 조회된다.
4. 키워드 도구
python3 naver-ad-performance/scripts/naver_ad_performance.py keywordtool --keywords "제주여행,게스트하우스"
Signing (참고)
요청마다 X-Timestamp(ms epoch), X-API-KEY, X-Customer, X-Signature 헤더가 필요하다.
message = "{timestamp}.{method}.{uri_path_only}" # 쿼리스트링 제외, method는 대문자
signature = base64(HMAC_SHA256(message, SECRET_KEY))
Output fields
stats: impCnt(노출수), clkCnt(클릭수), salesAmt(광고비), ctr(CTR, 없으면 클릭수/노출수로 계산), cpc(CPC, 없으면 광고비/클릭수로 계산), avgRnk(평균노출순위), ccnt(전환수). 각 행에 한글 라벨(labels)을 덧붙인다.
keywordtool: relKeyword(연관키워드), monthlyPcQcCnt/monthlyMobileQcCnt(월간 PC/모바일 조회수), compIdx(경쟁정도) 등.
Scope (읽기 전용 — 이 경계를 넘지 않는다)
허용: /ncc/campaigns, /ncc/adgroups, /ncc/keywords, /stats, /keywordstool GET 조회.
금지 (구현하지 않음): 입찰가 변경, 캠페인/광고그룹/키워드 생성·수정·삭제, 예산 변경, 상태(운영중지 등) 토글. 돈이 직접 나가는 쓰기 작업과 조회를 안전 경계로 분리하기 위해 의도적으로 뺐다. 쓰기 기능이 필요해지면 별도 스킬/별도 승인 흐름으로 분리한다.
Failure modes
| 증상 | 원인 |
|---|---|
missing required env var(s): ... | 환경변수 미설정. 정확히 어떤 이름이 빠졌는지 출력됨 |
| HTTP 401 | 서명 실패 — 키 값 또는 시스템 시계 확인 |
| HTTP 403 | 이 customer_id에 조회 권한 없음 |
| HTTP 404 | campaign/adgroup id가 잘못됨 |
| HTTP 429 | 호출 한도 초과 — 잠시 후 재시도 |
egress unreachable | 클라우드 샌드박스 등에서 네이버로 나가는 네트워크가 막힘 — 로컬 실행 필요 |
Done when
stats명령이 지정한 id·기간에 대해 노출수·클릭수·광고비·CTR·CPC를 반환한다.- 입찰가/캠페인/키워드를 바꾸는 어떤 요청도 보내지 않았다.
- 키가 없을 때 우회하지 않고 정확한 환경변수 이름을 안내했다.
Notes
- 대용량 기간 리포트(TSV 비동기 생성,
/stat-reports)는 이번 v1 범위 밖이다. 필요해지면 별도로 추가한다. - 참고 구현:
NariP/naver-searchad(MIT) — 서명 방식과 명령 설계를 참고했다.