개발자 문서

랭크프리 API

네이버 플레이스 순위추적, 경쟁분석, 키워드분석 데이터를 REST API로 제공합니다. API 키는 콘솔 → API 키에서 발급하며, 키마다 권한(scope)·허용기간·일일 호출 한도·허용 IP를 설정할 수 있습니다.

인증

모든 요청에 Authorization: Bearer 헤더(또는 X-API-KEY)로 키를 전달합니다.

curl -H "Authorization: Bearer rk_xxxxxxxxxxxxxxxx" \
     "https://rankfree.kr/api/v1/rank/slots"

항목	값
Base URL	`https://rankfree.kr/api/v1`
인증 헤더	`Authorization: Bearer rk_…` 또는 `X-API-KEY: rk_…`
응답 형식	JSON (UTF-8)
호출 한도	키에 설정한 일일 한도. 한도 설정 키는 응답에 `X-RateLimit-Limit` / `X-RateLimit-Remaining` 헤더 포함

오류 코드

코드	의미
`401`	키 없음/잘못됨 · 비활성화됨 · 유효기간 만료
`403`	허용되지 않은 IP · 키에 없는 권한(scope)의 엔드포인트 호출
`404`	리소스 없음 (내 소유가 아닌 슬롯 포함)
`422`	요청 파라미터 검증 실패
`429`	일일 호출 한도 초과 · 네이버 조회 일시 제한(blocked)

순위추적 scope: rank

키워드 × 플레이스 슬롯을 등록하면 매일 순위가 기록됩니다. rank 값 0/300=순위밖, -429=일시 차단.

엔드포인트	설명
GET `/rank/slots`	추적 슬롯 목록 + 일자별 순위 이력(`history`)
POST `/rank/slots`	슬롯 등록 — `place`(URL/ID, 필수), `keyword` 또는 `keywords[]`, `label`(선택)
GET `/rank/resolve?place=`	플레이스 메타 조회(업체명·카테고리·정규 URL) — 슬롯 생성 없음
POST `/rank/slots/{id}/run`	즉시 순위 갱신(당일 기록 upsert)
DELETE `/rank/slots/{id}`	슬롯 삭제
POST `/rank/check`	1회성 순위 조회(슬롯 없이) — `keyword`, `place`

POST https://rankfree.kr/api/v1/rank/slots
{"place": "https://m.place.naver.com/hairshop/1145161001", "keywords": ["강남 미용실", "역삼 미용실"]}

HTTP/1.1 201
{
  "place": {"place_id": "1145161001", "place_name": "라온헤어 강남점", "category": "hairshop"},
  "created": [{"id": 12, "keyword": "강남 미용실", "last_rank": null, "history": []}],
  "skipped": []
}

경쟁분석 scope: compete

키워드 상위 노출 경쟁 업체와 내 플레이스의 SEO 신호를 비교·점수화합니다. N1/N2/N3·D1~D10 점수는 랭크프리 자체 추정치이며 네이버 공식 지표가 아닙니다.

엔드포인트	설명
GET `/compete/tracks`	슬롯별 최신 분석 요약(N1/N2/N3·순위)
GET `/compete/{slotId}`	최신 분석 상세 — 경쟁셋 비교(`rows`), 내 점수 해설(`explain`), 추이(`series`)
POST `/compete/{slotId}/analyze`	분석 실행 — `detail_top`(기본 10). 동기 처리로 수십 초 소요, 차단 시 `429 blocked`

키워드분석 scope: keyword · keyword_detail

경량 분석과 상세 분석은 별도 권한(scope)으로 분리되어 있어 키를 상품별로 발급하고 기간·일일 한도를 따로 관리할 수 있습니다.

엔드포인트	설명
GET `/keyword?keyword=`	경량 — 월간 검색량(PC/모바일)·경쟁강도·연관 키워드 scope: keyword
GET `/keyword/detail?keyword=`	상세 — 경량 지표 + 성별·연령 분포, 최근 12개월 검색량 트렌드 scope: keyword_detail. 소스 일시 장애 시 `503`

GET https://rankfree.kr/api/v1/keyword?keyword=강남+미용실

HTTP/1.1 200
{
  "data": {
    "keyword": "강남미용실",
    "monthly_pc": 1200, "monthly_mobile": 8800, "monthly_total": 10000,
    "comp_idx": "높음",
    "related": [{"keyword": "강남역미용실", "monthly_total": 4300}]
  }
}

GET https://rankfree.kr/api/v1/keyword/detail?keyword=강남+미용실

HTTP/1.1 200
{
  "data": {
    "keyword": "강남미용실",
    "monthly_pc": 1200, "monthly_mobile": 8800, "monthly_total": 10000,
    "comp_idx": "높음",
    "related": [ … ],
    "detail": {
      "gender": {"female": 7200, "male": 2800, "female_pct": 72.0, "male_pct": 28.0},
      "age": [{"age": "20", "total": 3100, "pct": 31.0}, {"age": "30", "total": 4200, "pct": 42.0}],
      "monthly": [{"label": "2025-08", "pc": 1100, "mobile": 8300, "total": 9400}, … ],
      "buckets": [{"gender": "f", "age": "20", "pc": 300, "mobile": 2500, "total": 2800}, … ]
    }
  }
}

API 키가 필요하신가요?

콘솔에서 직접 발급하고 권한·기간·한도·IP를 설정할 수 있습니다.

API 키 발급