API 명세서 - Server Dashboard

전체 API 요약

메서드	엔드포인트	단수/복수	설명
GET	/api/blog-status/check	복수	블로그 활성화 일괄 확인
GET	/api/blog-status/check-single	단수	블로그 활성화 단일 확인
GET	/api/naver-blog/extract-place-id	단수	블로그 포스트에서 플레이스ID 추출
GET	/api/naver-blog/check-rank	단수	블로그 포스트 검색 순위
GET	/api/naver-place/check-rank	단수	플레이스 검색 순위 확인
GET	/api/naver-place/info	단수+복수	플레이스 상세 정보 조회
GET	/api/naver-place/top-places	단수+복수	상위 10개 플레이스 조회
GET	/api/naver-place/check-ad-rank	단수	플레이스 광고 순위 확인 (모바일)
GET	/api/naver-place/top-ads	단수	키워드 광고 상위 목록
GET	/api/naver-place/search-list	단수	오가닉+광고 통합 검색 리스트
GET	/api/agent-config/check-cafe	단수	네이버 카페 정지 여부 확인
GET	/api/agent-config/check-cafe-bulk	복수	네이버 카페 정지 여부 일괄 확인

블로그 API

GET /api/blog-status/check 복수

여러 블로그의 활성화 상태를 일괄 확인합니다. 100ms 간격으로 순차 처리됩니다.

Parameters

이름	위치	타입	필수	설명
blog_ids	query	string	O	쉼표 구분 블로그 ID

Request

GET /api/blog-status/check?blog_ids=user123,user456,user789

Response 200

[
  { "blog_id": "user123", "status_code": 200 },
  { "blog_id": "user456", "status_code": 404 }
]

Error 400

{
  "success": false,
  "error": "blog_ids 파라미터가 필요합니다",
  "example": "?blog_ids=user123,user456"
}

GET /api/blog-status/check-single 단수

단일 블로그의 활성화 상태를 확인합니다. status_code만 반환합니다.

Parameters

이름	위치	타입	필수	설명
blog_id	query	string	O	블로그 ID

Request

GET /api/blog-status/check-single?blog_id=user123

Response 200

{ "status_code": 200 }

Error 400

{
  "success": false,
  "error": "블로그 아이디를 입력해주세요",
  "example": "?blog_id=user123"
}

GET /api/naver-blog/extract-place-id 단수

네이버 블로그 포스트 URL에서 연결된 플레이스 ID를 추출합니다.

Parameters

이름	위치	타입	필수	설명
post_url	query	string	O	네이버 블로그 포스트 URL

Request

GET /api/naver-blog/extract-place-id?post_url=https://blog.naver.com/example/123456789

Response 200

{ "placeId": "1234567890" }

Error 400

{
  "success": false,
  "message": "post_url 파라미터가 필요합니다."
}

GET /api/naver-blog/check-rank 단수

특정 키워드 검색 결과에서 블로그 포스트의 순위를 확인합니다.

Parameters

이름	위치	타입	필수	설명
search_query	query	string	O	검색 키워드
post_url	query	string	O	블로그 포스트 URL

Request

GET /api/naver-blog/check-rank?search_query=서초구 맛집&post_url=https://blog.naver.com/example/123

Response 200

{ "post_rank": 5 }

Error 400

{
  "success": false,
  "message": "search_query와 post_url 파라미터가 모두 필요합니다."
}

플레이스 API

GET /api/naver-place/check-rank 단수

키워드 검색에서 특정 플레이스의 순위를 확인합니다. 최대 300위까지 탐색합니다.

Parameters

이름	위치	타입	필수	설명
keyword	query	string	O	검색 키워드
place_url	query	string	O	네이버 플레이스 URL

지원 URL 형식

https://pcmap.place.naver.com/place/{placeId}
https://map.naver.com/p/entry/place/{placeId}

Request

GET /api/naver-place/check-rank?keyword=서초구 맛집&place_url=https://pcmap.place.naver.com/place/1106978299

Response 200

{
  "rank": 3,
  "keyword": "서초구 맛집",
  "timestamp": "2026-02-24 09:00:00"
}

* rank가 0이면 300위 내에 없음을 의미합니다.

Error 400

{
  "success": false,
  "message": "keyword와 place_url 파라미터가 모두 필요합니다."
}

GET /api/naver-place/info 단수 + 복수

네이버 플레이스의 상세 정보를 조회합니다. 단수/복수 요청을 모두 지원하며, 복수 요청 시 3개씩 배치 병렬처리합니다.

Parameters (단수) - 하나만 사용

이름	위치	타입	설명
place_url	query	string	플레이스 URL
place_id	query	string	플레이스 ID (숫자)

Parameters (복수) - 하나만 사용

이름	위치	타입	설명
place_urls	query	string	쉼표 구분 플레이스 URL
place_ids	query	string	쉼표 구분 플레이스 ID

Request (단수)

GET /api/naver-place/info?place_id=1106978299

Response (단수) 200

{
  "storeName": "세광양대창 양재점",
  "category": "한식",
  "roadAddress": "서울 서초구 양재동 123",
  "address": "서울 서초구 양재동 456-78",
  "phoneNumber": "0507-1234-5678",
  "blogReviewCount": 1072,
  "visitorReviewCount": 1391,
  "post_type": "restaurant"
}

Request (복수)

GET /api/naver-place/info?place_ids=1106978299,11702941,9876543

Response (복수) 200

{
  "total": 3,
  "success": 2,
  "failed": 1,
  "results": [
    {
      "placeUrl": "https://map.naver.com/p/entry/place/1106978299",
      "storeName": "세광양대창 양재점",
      "category": "한식",
      "success": true
    },
    {
      "placeUrl": "https://map.naver.com/p/entry/place/9876543",
      "error": "유효한 플레이스 ID를 찾을 수 없습니다",
      "success": false
    }
  ]
}

GET /api/naver-place/top-places 단수 + 복수

키워드 검색 결과에서 상위 10개 플레이스를 조회합니다. 복수 요청 시 2개씩 배치 처리하며 배치 간 2~3초 딜레이가 있습니다.

Parameters (단수)

이름	위치	타입	필수	설명
keyword	query	string	O	검색 키워드

Parameters (복수)

이름	위치	타입	필수	설명
keywords	query	string	O	쉼표 구분 검색 키워드

Request (단수)

GET /api/naver-place/top-places?keyword=서초구 맛집

Response (단수) 200

[
  {
    "rank": 1,
    "id": "1106978299",
    "name": "세광양대창 양재점",
    "url": "https://map.naver.com/p/entry/place/1106978299",
    "category": "한식",
    "roadAddress": "서울 서초구 양재동 123",
    "phone": "0507-1234-5678"
  },
  {
    "rank": 2,
    "id": "11702941",
    "name": "다른 음식점",
    "url": "https://map.naver.com/p/entry/place/11702941"
  }
]

Request (복수)

GET /api/naver-place/top-places?keywords=서초구 맛집,강남구 맛집,역삼동 카페

Response (복수) 200

{
  "total": 3,
  "success": 3,
  "failed": 0,
  "results": [
    {
      "keyword": "서초구 맛집",
      "success": true,
      "places": [
        { "rank": 1, "id": "...", "name": "..." }
      ]
    },
    {
      "keyword": "강남구 맛집",
      "success": true,
      "places": [...]
    }
  ]
}

GET /api/naver-place/check-ad-rank 단수

특정 플레이스가 해당 키워드 검색 시 광고로 몇 번째에 노출되는지 확인합니다. 광고가 아니면 rank=0 입니다. 모바일 m.place 리스트의 adBusinesses를 파싱하며, 키워드에서 지역을 추출해 네이버 클라우드 Maps 지오코딩으로 중심 좌표를 구합니다. (기존 check-rank는 PC 오가닉 순위로, 광고와 완전히 별개 경로입니다.)

Parameters

이름	위치	타입	필수	설명
keyword	query	string	O	검색 키워드 (예: 서초구 맛집)
place_url	query	string	O	플레이스 URL 또는 플레이스 ID(mid)

Request

GET /api/naver-place/check-ad-rank?keyword=서초구 맛집&place_url=1822726228

Response 200

{
  "rank": 3,
  "isAd": true,
  "totalAds": 5,
  "keyword": "서초구 맛집",
  "location": {
    "x": "127.0328110",
    "y": "37.4837121",
    "matched": "서초구",
    "address": "서울특별시 서초구"
  },
  "matched": {
    "rank": 3,
    "mid": "1822726228",
    "name": "세광양대창 양재점",
    "adId": "nsa-...",
    "category": "한식",
    "distance": "1.2km"
  },
  "timestamp": "2026-07-02 18:53:19"
}

광고에 노출되지 않으면 rank: 0, isAd: false, matched: null 로 응답합니다. location은 지오코딩 결과(x=경도, y=위도, matched=실제 지오코딩된 지역어)입니다.

GET /api/naver-place/top-ads 단수

해당 키워드로 검색 시 노출되는 광고 플레이스 전체를 순위와 함께 반환합니다. (광고 슬롯 상위 최대 12개, ads[].rank = 광고 노출 순서)

Parameters

이름	위치	타입	필수	설명
keyword	query	string	O	검색 키워드

Request

GET /api/naver-place/top-ads?keyword=서초구 맛집

Response 200

{
  "keyword": "서초구 맛집",
  "total": 5,
  "location": { "x": "127.0328110", "y": "37.4837121", "matched": "서초구", "address": "서울특별시 서초구" },
  "ads": [
    {
      "rank": 1,
      "mid": "1106978299",
      "name": "세광양대창 양재점",
      "adId": "nsa-...",
      "category": "한식",
      "distance": "0.8km",
      "url": "https://map.naver.com/p/entry/place/1106978299"
    }
  ],
  "timestamp": "2026-07-02 18:53:19"
}

GET /api/naver-place/search-list 단수

오가닉(placeList)과 광고(adBusinesses)를 모바일 응답 한 번으로 함께 조회해 서로의 순위를 교차 표기합니다. 광고 항목에는 오가닉 순위(organicRank, 0=오가닉 조회범위 밖 또는 광고전용), 오가닉 항목에는 광고 여부(isAd)가 붙습니다. 프론트 뷰어 페이지(/naver-place)가 사용하는 엔드포인트입니다.

Parameters

이름	위치	타입	필수	설명
keyword	query	string	O	검색 키워드 (예: 서초구 누수탐지)
org_limit	query	number	X	오가닉 최대 개수 (기본 전체, 최대 100)

Request

GET /api/naver-place/search-list?keyword=서초구 누수탐지&org_limit=30

Response 200

{
  "keyword": "서초구 누수탐지",
  "location": { "x": "127.0328110", "y": "37.4837121", "matched": "서초구", "address": "서울특별시 서초구" },
  "adCount": 2,
  "ads": [
    {
      "rank": 1,
      "mid": "1822726228",
      "name": "OO누수탐지",
      "adId": "nsa-...",
      "category": "누수탐지",
      "distance": "1.5km",
      "organicRank": 5,
      "url": "https://map.naver.com/p/entry/place/1822726228"
    }
  ],
  "organicShown": 30,
  "organicTotal": 87,
  "organic": [
    {
      "rank": 1,
      "mid": "1106978299",
      "name": "XX설비",
      "category": "누수탐지",
      "distance": "0.3km",
      "isAd": false,
      "url": "https://map.naver.com/p/entry/place/1106978299"
    }
  ],
  "timestamp": "2026-07-02 18:53:19"
}

카페 API

GET /api/agent-config/check-cafe 단수

네이버 카페가 살아있는지(정상) 또는 정지/폐쇄되었는지 확인합니다. cafe.naver.com 페이지를 직접 요청해 #cafe-body-skin 엘리먼트 존재 여부로 판정합니다.

Parameters

cafe_id 또는 cafe_url 중 하나는 반드시 전달해야 합니다.

이름	위치	타입	필수	설명
cafe_id	query	string	△	카페 ID (예: `wlswkakdma`)
cafe_url	query	string	△	카페 전체 URL (cafe_id 보다 우선 적용)

Request

GET /api/agent-config/check-cafe?cafe_id=wlswkakdma

Response — 카페 정상 200

{
  "isSuccess": true,
  "cafe_url": "https://cafe.naver.com/wlswkakdma",
  "alive": true,
  "suspended": false,
  "reason": "cafe-body-skin 존재 - 카페 정상"
}

Response — 카페 정지 200

{
  "isSuccess": true,
  "cafe_url": "https://cafe.naver.com/dogoodmore",
  "alive": false,
  "suspended": true,
  "reason": "cafe-body-skin 없음 - 카페 정지 확인"
}

Error 400

{
  "isSuccess": false,
  "message": "cafe_id 또는 cafe_url 중 하나는 필수입니다."
}

GET /api/agent-config/check-cafe-bulk 복수

여러 네이버 카페의 정지 여부를 한 번에 확인합니다. cafe_ids 또는 cafe_urls 를 콤마로 구분해 전달하며, 둘 다 전달하면 모두 합쳐서 순차적으로 확인합니다 (요청 간 100ms 딜레이).

Parameters

cafe_ids 또는 cafe_urls 중 하나는 반드시 전달해야 합니다.

이름	위치	타입	필수	설명
cafe_ids	query	string (csv)	△	카페 ID 목록 콤마구분 (예: `wlswkakdma,dogoodmore,housecreature`)
cafe_urls	query	string (csv)	△	카페 전체 URL 목록 콤마구분

Request

                GET /api/agent-config/check-cafe-bulk?cafe_ids=wlswkakdma,dogoodmore,housecreature
              

Response 200

{
  "isSuccess": true,
  "total": 3,
  "alive": 2,
  "suspended": 1,
  "results": [
    {
      "cafe_url": "https://cafe.naver.com/wlswkakdma",
      "alive": true,
      "suspended": false,
      "reason": "cafe-body-skin 존재 - 카페 정상"
    },
    {
      "cafe_url": "https://cafe.naver.com/dogoodmore",
      "alive": false,
      "suspended": true,
      "reason": "cafe-body-skin 없음 - 카페 정지 확인"
    },
    {
      "cafe_url": "https://cafe.naver.com/housecreature",
      "alive": true,
      "suspended": false,
      "reason": "cafe-body-skin 존재 - 카페 정상"
    }
  ]
}

Error 400

{
  "isSuccess": false,
  "message": "cafe_ids 또는 cafe_urls 중 하나는 필수입니다.",
  "example": "?cafe_ids=id1,id2 또는 ?cafe_urls=https://cafe.naver.com/a,https://cafe.naver.com/b"
}