기술

네이버 검색광고 API로 키워드 검색량 직접 호출하는 법

작성 2025.11.20 · 최종수정 2026.04.08 · 읽는 시간 8분

대량 키워드를 자동 분석하거나 자체 도구를 만들려면 네이버 검색광고 API 직접 호출이 필요합니다. HMAC-SHA256 서명이 낯설어 진입 장벽이 있지만, 한번 세팅하면 평생 씁니다. PHP 기준 전체 흐름과 실전 코드.

전체 호출 흐름

서명 생성 → API 호출 → JSON 응답의 3단계.

1단계 — API 키 발급

네이버 검색광고 광고주센터에 가입하고 도구 → API 사용 관리 에서 키를 발급받습니다. 사업자번호가 있어야 광고주 가입 가능.

CUSTOMER_ID — 광고주 고객 번호 (6~8자리)
API_KEY — 액세스 라이선스
SECRET_KEY — 비밀키 (서명용, 절대 노출 금지)

보안. SECRET_KEY 는 코드에 하드코딩하지 말고 환경변수나 서버 비공개 설정 파일에 두세요. GitHub 같은 곳에 실수로 올리면 즉시 재발급해야 합니다.

2단계 — HMAC-SHA256 서명 생성

모든 요청에는 현재 시각 + HTTP 메서드 + URI 를 HMAC-SHA256 으로 서명한 값이 필요합니다. PHP 예시:

function generateSignature($timestamp, $method, $uri, $secretKey) {
    $message = $timestamp . '.' . $method . '.' . $uri;
    return base64_encode(hash_hmac('sha256', $message, $secretKey, true));
}

3단계 — 키워드 도구 호출

/keywordstool 엔드포인트에 GET 요청. hintKeywords 파라미터에 키워드를 넘기면 연관 키워드를 포함한 배열을 받습니다.

function getKeywordVolume($keyword, $apiKey, $secret, $custId) {
    $base = 'https://api.searchad.naver.com';
    $uri = '/keywordstool';
    $timestamp = round(microtime(true) * 1000);
    $signature = generateSignature($timestamp, 'GET', $uri, $secret);

    $headers = [
        'X-Timestamp: ' . $timestamp,
        'X-API-KEY: ' . $apiKey,
        'X-Customer: ' . $custId,
        'X-Signature: ' . $signature,
    ];

    $url = $base . $uri . '?hintKeywords=' . urlencode($keyword) . '&showDetail=1';
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    $response = curl_exec($ch);
    curl_close($ch);

    return json_decode($response, true);
}

4단계 — 응답 파싱

응답은 keywordList 배열입니다. 각 항목의 주요 필드:

relKeyword — 키워드 문자열
monthlyPcQcCnt — 월간 PC 검색량
monthlyMobileQcCnt — 월간 모바일 검색량
monthlyAvePcCtr / monthlyAveMobileCtr — 월 평균 CTR (%)
plAvgDepth — 평균 노출 순위
compIdx — 경쟁 지수 ("높음", "중간", "낮음")

첫번째 항목은 입력 키워드 자체이고, 나머지는 연관 키워드입니다.

주의. 검색량이 10 미만인 경우 "< 10" 문자열로 반환됩니다. 숫자 비교 전 is_numeric() 체크 필수.

5단계 — 에러 처리

주요 에러 케이스:

401 Unauthorized — 서명 불일치. timestamp 밀리초 여부 재확인
403 Forbidden — API 키 권한 문제. 광고주센터에서 활성 확인
429 Too Many Requests — 호출 제한. 초당 1~2회 속도로 제한
500 — 네이버 측 일시 장애. 재시도 로직 필요

Python 버전 샘플

import time, hmac, hashlib, base64, requests

def signature(ts, method, uri, secret):
    msg = f"{ts}.{method}.{uri}"
    return base64.b64encode(
        hmac.new(secret.encode(), msg.encode(), hashlib.sha256).digest()
    ).decode()

def get_volume(keyword, api_key, secret, cust_id):
    ts = str(round(time.time() * 1000))
    uri = "/keywordstool"
    sig = signature(ts, "GET", uri, secret)
    r = requests.get(
        f"https://api.searchad.naver.com{uri}",
        params={"hintKeywords": keyword, "showDetail": 1},
        headers={
            "X-Timestamp": ts,
            "X-API-KEY": api_key,
            "X-Customer": cust_id,
            "X-Signature": sig,
        }
    )
    return r.json()

활용 아이디어

Google Sheets + Apps Script 로 셀에서 키워드 검색량 자동 조회
일일 배치 스크립트 로 관심 키워드 100개 검색량 일괄 저장·변화 알림
자체 도구 제작 — 고객사별 대시보드 구축

직접 하기 귀찮으면

API 세팅·서명·에러 처리가 번거롭다면 마케팅마법사 검색량 조회가 내부적으로 이 API 를 대신 호출해주고 있습니다. 단건·소량 조회용이면 이쪽이 훨씬 빠릅니다.

단건은 바로 조회, 대량은 API

필요 규모에 맞는 선택을 하세요.

마법사 검색량 조회 →

자주 묻는 질문

Q. 광고 집행 없이도 API 를 쓸 수 있나요?

광고주 가입만 하면 API 호출 자체는 무료로 가능합니다. 실제 광고 예산을 태우지 않아도 됩니다.

Q. 초당 몇 번 호출 가능한가요?

공식 문서상 초당 3회 권장. 초과하면 429 에러. 대량 호출 시 sleep(0.5) 정도의 딜레이를 걸어두세요.

Q. Customer ID 를 모르겠어요.

광고주센터 로그인 후 오른쪽 상단 내 정보 영역에 "고객 번호" 로 표시됩니다. 보통 7자리 숫자입니다.