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/blog-crawler/target-blogs	복수	대상 블로그 전체 조회
GET	/api/naver-place/check-rank	단수	플레이스 검색 순위 확인
GET	/api/naver-place/info	단수+복수	플레이스 상세 정보 조회
GET	/api/naver-place/top-places	단수+복수	상위 10개 플레이스 조회

블로그 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 파라미터가 모두 필요합니다."
}

GET /api/blog-crawler/target-blogs 복수

크롤링 대상으로 등록된 블로그 전체 목록을 조회합니다.

인증 필요 — X-API-Key 헤더가 필요합니다.

Parameters

없음

Request

GET /api/blog-crawler/target-blogs

Response 200

{
  "success": true,
  "data": {
    "targetBlogs": ["blogId1", "blogId2"],
    "total": 2
  }
}

플레이스 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": [...]
    }
  ]
}