Developer reference / v1

검색 순위 API.
당신의 서비스 안으로.

엔터프라이즈 이용권 승인 후 API 콘솔에서 키를 발급하세요.
키는 서버에서 X-API-KEY 헤더로 전송합니다.

01. 조회 접수

POST https://shop.rankmoni.com/api/v1/rank.php
X-API-KEY: YOUR_API_KEY
Content-Type: application/json

{
  "action": "lookup",
  "domain": "smartstore.naver.com/mystore/products/1234567890",
  "keyword": "브랜드 컨설팅"
}

대상 URL과 키워드의 정확한 쌍을 조회합니다. 블로그·업체·개별 상품의 식별자로 구분합니다. 같은 날 같은 쌍은 기존 접수를 반환하며, 새 날짜의 요청은 우선순위 100으로 접수합니다.

02. 상태·결과 확인

POST /api/v1/rank.php
X-API-KEY: YOUR_API_KEY
Content-Type: application/json

{
  "action": "status",
  "domain": "smartstore.naver.com/mystore/products/1234567890",
  "keyword": "브랜드 컨설팅"
}

30초 이상 간격으로 조회하세요. 상태 확인은 사용량을 추가 차감하지 않습니다. 신규 작업을 재접수할 필요가 없습니다.

응답 예시 · 완료

{
  "success": true,
  "status": "ready",
  "rank": 3,
  "checked_at": "2026-10-31 10:00:00",
  "worker": "WORKERCAB-02105",
  "basis": "naver_shopping_product",
  "queue": null,
  "usage": { "used": 1, "limit": 10000, "remaining": 9999 }
}

문서 이해를 위한 응답 예시입니다. 실제 순위·워커·시각은 측정 결과에 따라 달라집니다.

상태의 의미

status	의미
ready	최근 24시간 내 측정값
queued / running	대기 / 워커 처리 중
retry_wait	실패 후 재시도 대기
not_found	측정 범위 내 미발견
failed / stale	재시도 한도 도달 / 24시간이 지난 기록
not_tracking / unmeasured	미접수 / 측정 기록 없음

순위 기준은 네이버 쇼핑 일반 결과입니다. 미발견을 네이버 전체 미색인으로 해석하지 마세요. last_rank는 과거 참고값이며 현재 순위가 아닙니다.

일일 한도와 비용

하루 10,000쌍 · 월 2,200,000원
하루 10,000쌍 추가마다 월 330,000원

KST 날짜별 서로 다른 대상 URL + 키워드 쌍의 접수를 계산합니다. 같은 날 재조회·상태 확인은 중복 차감하지 않습니다. 접수 후 실패·재시도도 같은 쌍으로 집계합니다. 다음 날 다시 조회 접수하면 새 날짜 사용량으로 계산됩니다.

GET /api/v1/rank.php?action=usage
X-API-KEY: YOUR_API_KEY

401: 키 인증 실패 · 403: 이용권 만료/권한/IP 제한
429: 일일 한도 소진 · 500: 응답 불명, status부터 확인

API 요청은 우선 처리되지만 이미 진행 중인 작업, 검색 요청 간 간격, 검색 제한에 따른 재시도 대기를 건너뛰지 않습니다. 일정 시간 내 측정 완료를 보장하지 않습니다.