네이버 노출 추적기
두 센터(리부트 철산 / 팀포이즈 광교)의 네이버 검색 노출을 매일 자동으로 기록하고
GitHub Pages 대시보드로 보여준다. 서버비 0원, GitHub Actions만 사용.
- 플레이스: 지역검색 API로 상위 5위 안에서의 위치 (API가 5개까지만 준다 — 그 밖은 측정 불가)
- 블로그: 블로그 검색 API로 우리 글의 순위 (100개씩 10페이지까지 넘기며 '서로 다른 글 중 몇 번째'로 센다 — API가 뒤 페이지에 앞 글을 다시 섞어 주기 때문)
- 센터별 주간 리포트:
docs/reports/<센터>.html (대시보드에서 링크) — 이번 주 7일과 지난주 7일을 주간 대표 순위(7일 순위의 가운데 값)로 비교한다. 이번 주 요약 · 지표 카드(최근 4주 추이) · 다음 할 일 · 키워드별 주간 순위 · 날짜별 순위 지도 · 우리 글 성과(blog_posts.csv) · 상위 자리 점유(플레이스·블로그). 블로그 확인 범위가 크게 바뀐 날(2026-10-14) 전 기록은 비교하지 않는다
30분 셋업
1. 저장소 만들기
gh repo create naver-rank-tracker --public --source=. --remote=origin # 무료 플랜의 Pages는 공개 저장소에서만
git add . && git commit -m "init"
git push -u origin main
2. 검색 API 키 발급 — NAVER CLOUD PLATFORM
2026-06-25부터 네이버 검색 API는 NAVER API HUB(네이버 클라우드 플랫폼)로 이관됐다.
developers.naver.com 신규 발급은 2026-07-31로 끝났고, 기존 키는 2027-06-30까지만 동작한다.
이 저장소는 둘 다 지원하지만, 새로 시작한다면 HUB 쪽이다.
- https://console.ncloud.com 로그인 (가입 시 결제수단 등록이 필요하다)
- Services → Application Service → NAVER API HUB 이용 신청
- Application 등록 후 Client ID / Client Secret 발급
무료 한도는 하루 25,000회. 이 추적기는 키워드 8개 기준 하루 약 32회를 쓴다.
| 신규 (HUB) | 레거시 |
|---|
| 호스트 | naverapihub.apigw.ntruss.com | openapi.naver.com |
| 지역검색 | GET /search/v1/local | GET /v1/search/local.json |
| 블로그검색 | GET /search/v1/blog | GET /v1/search/blog.json |
| 인증 헤더 | X-NCP-APIGW-API-KEY-ID / X-NCP-APIGW-API-KEY | X-Naver-Client-Id / X-Naver-Client-Secret |
문서: https://api.ncloud-docs.com/docs/naver-api-hub-overview
파라미터 상한 (HUB 문서 기준)
- 지역검색
display 1~5 — 상위 5개까지만 준다. 그 밖의 순위는 이 API로 알 수 없다.
- 블로그검색
display 최대 100, start 최대 1000 — 최대 1000위까지 확인 가능
3. 저장소 Secrets 등록
Settings → Secrets and variables → Actions → New repository secret
| 이름 | 값 |
|---|
NCP_API_KEY_ID | HUB Client ID |
NCP_API_KEY | HUB Client Secret |
기존 developers.naver.com 키를 쓸 거면 대신 NAVER_CLIENT_ID / NAVER_CLIENT_SECRET.
둘 다 있으면 HUB를 우선 사용한다.
4. config/targets.yml 채우기
반드시 바꿔야 하는 값은 blog_ids — blog.naver.com/<여기> 의 아이디다.
place_aliases는 네이버 지역검색에 나오는 업체명과 맞춰야 우리 업체로 인식된다.
keyword_notes(선택)는 순위를 읽을 때 알아야 할 사정을 키워드별로 적는다 — 대시보드 키워드 표에
※ 표시와 각주로 나오고, 그 키워드가 '블로그 1위'·'10위 안' 집계에 들어가면 집계 옆에도 밝힌다.
5. GitHub Pages 켜기
Settings → Pages → Source: Deploy from a branch → Branch: main, 폴더 /docs
→ https://<아이디>.github.io/naver-rank-tracker/
6. 첫 실행
Actions 탭 → "네이버 노출 추적" → Run workflow.
이후 매일 KST 09:00에 자동 실행된다.
로컬 실행
pip install -r requirements.txt
export NCP_API_KEY_ID=... NCP_API_KEY=... # 또는 NAVER_CLIENT_ID / NAVER_CLIENT_SECRET
python src/track.py # data/rankings.csv 에 append
python src/build_dashboard.py # docs/index.html 생성
데이터 형식 — data/rankings.csv
| 컬럼 | 의미 |
|---|
date | KST 날짜 |
center | Reboot / TeamPoise |
keyword | 검색어 |
surface | place / blog |
our_rank | 우리 순위. 빈 값 = 확인 범위 안에 없음 |
our_title | 잡힌 항목 제목 |
rank1~5 | 그날 1~5위 (경쟁사 추적용) |
checked_depth | 어디까지 확인했는지 (블로그는 서로 다른 글 수) |
collected_at | 수집 시각, KST ISO 8601 초 단위 (예: 2026-11-02T09:03:12+09:00) |
api_total | 검색 API 응답의 total(총 결과 수). 블로그는 첫 페이지 요청 값, 플레이스는 지역검색 값 |
collected_at·api_total은 2026-11-02에 끝에 덧붙인 열이라 그 전 줄은 빈 값이다.
API가 돌려주는 결과 범위가 바뀌면(2026-10-14처럼) 순위 숫자를 그 전후로 비교할 수 없는데,
api_total이 같은 키워드에서 하루 만에 크게 바뀌면 그날을 경계로 보면 된다.
한 줄이 하나의 관측이라 그대로 pandas/엑셀로 넘길 수 있다.
니즈·브랜드 키워드는 지역명이 없어 블로그만 기록한다.
블로그에서 잡힌 우리 글은 키워드마다 전부 data/blog_posts.csv에 따로 남는다(rankings.csv에는 가장 높은 1편).
알아둘 한계
- 지역검색 API는 상위 5개까지만 준다 (
display 범위 1~5). 실제 네이버 지도 앱 순위는 사용자 위치로
개인화되므로 이 값과 다를 수 있다. 절대 순위가 아니라 추세 신호로 읽을 것.
- 순위가 비어 있다고 "노출 0"이 아니다. "확인한 범위 안에는 없었다"는 뜻이다.
- 이 도구는 측정만 한다. 순위를 올리는 건 콘텐츠와 실제 이용자 행동이다.
트래픽·리뷰·저장 자동화는 2026년 기준 즉시 제재 대상이라 넣지 않았다.
