OpenParable
Skip to content
← Back to skills

Naver Ad Performance

Business
naver-ad-performance

Naver 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·전환수를 조회한다. 캠페인/광고그룹/키워드 목록, 기간별 성과, 연관키워드·월간 조회수 도구 포함. 읽기 전용, 로컬 실행 전용.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
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 404campaign/adgroup id가 잘못됨
HTTP 429호출 한도 초과 — 잠시 후 재시도
egress unreachable클라우드 샌드박스 등에서 네이버로 나가는 네트워크가 막힘 — 로컬 실행 필요

Done when

  • stats 명령이 지정한 id·기간에 대해 노출수·클릭수·광고비·CTR·CPC를 반환한다.
  • 입찰가/캠페인/키워드를 바꾸는 어떤 요청도 보내지 않았다.
  • 키가 없을 때 우회하지 않고 정확한 환경변수 이름을 안내했다.

Notes

  • 대용량 기간 리포트(TSV 비동기 생성, /stat-reports)는 이번 v1 범위 밖이다. 필요해지면 별도로 추가한다.
  • 참고 구현: NariP/naver-searchad (MIT) — 서명 방식과 명령 설계를 참고했다.