네이버 카페(공개) 검색

채널 코드 naver_cafe_search · 수집 환경 linux

네이버 카페 통합검색에서 키워드로 공개 카페 글을 정렬별(최신/정확도)·기간별로 수집합니다. 로그인 불필요(공개 검색). 기본은 제목·카페명·요약(스니펫)·작성시각·링크를 가져오며, '본문 수집'을 켜면 카페 글 공개 API로 한 번 더 들어가 전체 본문과 정확한 등록시각을, '댓글 수집'을 켜면 댓글·대댓글까지 보강합니다(둘 중 하나만 켜도 상세를 1회 조회). ⚠️ 상세 보강은 '전체공개(비회원 열람 허용)' 게시판만 가능합니다 — 회원 전용 게시판 글은 본문/댓글 대신 검색 요약만 담기고 extra.member_only=true 로 표시됩니다(오류 아님). 회원 전용 카페 전체를 수집하려면 '네이버 카페(가입)' 채널(로그인)을 쓰세요. ⚠️ 한 키워드·필터 조합으로 접근 가능한 글은 최대 약 1,020건입니다(네이버 검색 깊이 제한) — 더 많이 모으려면 기간을 나눠 수집하세요. 목록 시각은 상대표기('N분 전')라 수집 시각 기준으로 역산하며(원문은 posted_at_raw 보존), 상세를 켜면 정확 시각으로 보정됩니다. 차단·캡차가 감지되면 바로 멈추고 더 요청하지 않습니다(다시 시도·다른 IP 우회 없음) — 받은 데까지 결과에 담기고 warnings.blocked 가 붙으며, 받은 글이 없으면 실패로 끝납니다. result_count가 limit보다 적으면 오류가 아니라 가용 글 부족(깊이 한도/기간 필터) 또는 일시 차단입니다.

요청 파라미터

아래 값들을 POST /api/v1/collect 의 params 객체에 담아 보냅니다.

키	타입	필수	기본	설명
keyword	text	예	—	네이버 카페 검색어(예: 로얄캐닌)
sort	enum	—	latest	네이버 카페검색 정렬: 최신순=latest(st=date) · 정확도순=relevance(st=rel)
limit	number	—	50	최대 수집 글 수. 한 키워드·필터 조합당 최대 약 1,020개 접근 가능(네이버 검색 깊이 제한) — 초과분은 기간을 나눠 수집
start_date	date (YYYY-MM-DD)	—	—	비우면 제한 없음. 지정하면 네이버 검색 기간 필터로 그 이후 글만 수집
end_date	date (YYYY-MM-DD)	—	—	당일 포함. 비우면 오늘까지. 시작·종료 중 하나만 넣어도 됩니다
collect_body	bool	—	false	켜면 글마다 카페 공개 API로 전체 본문 + 정확한 등록시각을 보강(글당 요청 1회 추가). 회원 전용 게시판 글은 본문 대신 스니펫이 남고 extra.member_only=true로 표시됩니다. 끄면 검색 결과의 제목·요약(스니펫)만 수집
collect_comments	bool	—	false	켜면 댓글·대댓글까지 수집(각 글 extra.comments[]). 본문 수집과 같은 상세 조회 1회로 함께 받아옵니다. 회원 전용 게시판 글은 댓글도 비어 있고 member_only=true로 표시됩니다
exclude_keywords	text	—	—	이 단어가 제목에 들어간 글은 수집 단계에서 제외(상세 요청 전 → 빠르고 상한 미차감). 쉼표로 여러 개, 한 단어 안 띄어쓰기 허용. 본문 수집을 켜면 받아온 본문에서도 한 번 더 제외
refresh	enum	—	incremental	incremental(기본): 허브가 이미 수집한 글 중 규칙에 맞는 것은 다시 쓸 수 있습니다(게시 7일 미만 글은 항상 새로 수집). full: 이번 요청은 전부 새로 수집합니다. 결과 형식은 같습니다

수집 기간(start_date ~ end_date)
검색은 최신순이라 위에서부터 훑어 내려갑니다.

둘 다 비우면 → 가장 최신 글부터 limit 개수까지 수집합니다.
start_date만 → 그 날짜 이후 글만 (그보다 오래된 글을 만나면 수집 종료).
end_date만 → 그 날짜까지(당일 포함). 그보다 최신 글은 건너뜁니다.
둘 다 → 두 날짜 사이 구간만 수집.

제외 키워드(exclude_keywords)
이 단어가 들어간 글은 수집 단계에서 걸러집니다. 쉼표(,)로 여러 개를 넣고, 한 단어 안에 띄어쓰기도 쓸 수 있습니다(예: "무료 나눔, 광고" → 무료 나눔·광고 두 개). 대소문자는 구분하지 않고 부분 일치로 판정합니다.

기본은 제목 기준 — 상세 요청을 보내기 전에 걸러서 빠르고, 수집 상한(limit)도 차감하지 않습니다.
본문 수집(collect_body: true)을 켜면, 이미 받아온 본문에서도 한 번 더 걸러냅니다(추가 요청 없음).
비우면 → 제외 없이 전부 수집.

댓글 수집(collect_comments: true)
기본은 제목·본문만 HTTP로 빠르게 수집합니다. 댓글까지 받으려면 이 값을 켜세요. 댓글은 JS로 로드되어 글마다 Chrome으로 접속하므로 시간이 더 걸립니다(댓글 0개 글은 건너뜀). 수집된 댓글은 각 글의 extra.comments[] 배열에 담깁니다.

상세 수집(본문·댓글)은 전체공개 게시판만 — 회원 전용 글은 member_only로 구분
collect_body 또는 collect_comments를 켜면 글마다 카페 공개 API로 상세를 1회 조회합니다(본문·댓글을 한 번에 받아옵니다).

전체공개(비회원 열람 허용) 게시판 → 본문·댓글·정확한 등록시각까지 정상 수집(extra.member_only=false).
회원 전용 게시판 → 비로그인으로는 열람이 막혀(HTTP 401) 본문/댓글 대신 검색 요약(스니펫)만 담기고 extra.member_only=true가 붙습니다. 오류나 차단이 아니라 정상 동작이며, 그 항목만 표시가 다를 뿐 나머지는 그대로 수집됩니다.
상세 수집을 끄면(collect_body=false·collect_comments=false) 열람 확인을 하지 않으므로 member_only는 null입니다.
회원 전용 카페 전체를 본문·댓글까지 수집하려면 로그인 채널 네이버 카페(가입)을 사용하세요.

요청 예시

curl -X POST https://scraper.conbus.co.kr/api/v1/collect \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "naver_cafe_search",
    "params": {
        "keyword": "로얄캐닌",
        "sort": "latest",
        "limit": 50,
        "start_date": "2026-06-01",
        "end_date": "2026-06-15",
        "collect_body": false,
        "collect_comments": true,
        "exclude_keywords": "광고, 협찬",
        "refresh": "incremental"
    }
}'

응답 (202 Accepted)

요청은 즉시 큐에 적재되고 request_id 를 돌려줍니다. 실제 수집은 워커가 비동기로 처리합니다.

{ "success": true, "data": { "request_id": 42, "channel": "naver_cafe_search",
    "status": "pending", "status_url": "https://scraper.conbus.co.kr/api/v1/requests/42" } }

결과 조회 — `GET /requests/{id}`

같은 API 키로 request_id 를 조회합니다. 상태에 따라 응답이 달라집니다. 결과(items)는 요청별로 보관되므로 같은 글이 다른 요청(다른 키워드·재수집)에 겹쳐도 이 요청의 결과는 그대로입니다 — 여러 요청에 걸친 중복 정리는 post_id로 호출 쪽에서 하세요. 보존 기간은 완료 후 90일입니다. 보존 기간이 지나면 items 는 빈 배열이고 items_expired: true, items_keep_days 가 함께 옵니다(status 는 그대로 done).

진행 중 (pending / running)

아직 끝나지 않았으면 progress 로 진행 상황만 옵니다(items 없음).

{
    "success": true,
    "data": {
        "request_id": 42,
        "channel": "naver_cafe_search",
        "status": "running",
        "external_ref": null,
        "result_count": null,
        "started_at": "2026-06-16T09:00:05+09:00",
        "finished_at": null,
        "duration_ms": null,
        "duration_sec": null,
        "created_at": "2026-06-16T09:00:00+09:00",
        "updated_at": "2026-06-16T09:01:30+09:00",
        "progress": {
            "count": 12,
            "phase": "comments"
        },
        "elapsed_ms": 85000
    }
}

완료 (done) — 댓글 포함

status 가 done 이면 data.items[] 에 결과가 담깁니다. 실패 시엔 status: "failed" 와 error 가 옵니다.

{
    "success": true,
    "data": {
        "request_id": 42,
        "channel": "naver_cafe_search",
        "status": "done",
        "external_ref": null,
        "result_count": 1,
        "started_at": "2026-06-16T09:00:05+09:00",
        "finished_at": "2026-06-16T09:02:00+09:00",
        "duration_ms": 115000,
        "duration_sec": 115,
        "created_at": "2026-06-16T09:00:00+09:00",
        "updated_at": "2026-06-16T09:02:00+09:00",
        "items": [
            {
                "post_id": "ilovecat/8280553",
                "url": "https://cafe.naver.com/ilovecat/8280553",
                "title": "로얄캐닌 헤어 앤 스킨 케어 고양이 습식 할인 꿀팁",
                "author": "catmom****",
                "posted_at": "2026-07-21T14:22:00+09:00",
                "views": 152,
                "comment_count": 2,
                "recommends": null,
                "body": "로얄캐닌 헤어 앤 스킨 케어 고양이 습식 한 달 먹여본 후기 남겨요. 기호성이 좋아서 우리집 냥이가 잘 먹네요 ...",
                "source": "네이버 카페 / 고양이라서 다행이야",
                "extra": {
                    "cafe_name": "고양이라서 다행이야",
                    "club_slug": "ilovecat",
                    "article_no": "8280553",
                    "cafe_id": "15680552",
                    "menu": "자유수다방",
                    "snippet": "로얄캐닌 헤어 앤 스킨 케어 고양이 습식 한 달 먹여본 후기 ...",
                    "sort": "latest",
                    "member_only": false,
                    "posted_at_approx": null,
                    "via_proxy": null,
                    "source_kind": "cafe_search",
                    "comments": [
                        {
                            "comment_id": "12345",
                            "author": "멍멍이",
                            "text": "정보 감사합니다!",
                            "date": "2026-06-10 15:01:00",
                            "is_reply": false
                        },
                        {
                            "comment_id": "12346",
                            "author": "냥집사",
                            "text": "도움 되셨다니 다행이에요",
                            "date": "2026-06-10 15:10:00",
                            "is_reply": true
                        }
                    ]
                }
            }
        ]
    }
}

플랫폼 검색 상한·페이지 상한에 걸려 그 기간에 글이 더 있을 수 있으면 warnings.capped_periods 가 붙습니다 — 덜 모은 기간 경고. 최신순으로 한 달이 넘는 기간은 허브가 달 단위로 나눠 수집해 합칩니다(결과가 limit 보다 많을 수 있음) — 긴 기간 요청. 이미 끝까지 수집한 날짜는 허브 원장으로 답합니다(extra.ledger_at, 새로 수집하려면 refresh=full) — 원장으로 답함.

실패 (failed)

status 가 failed 면 error 에 사유가 옵니다(items 없음). 일시적 실패는 자동 재시도되며, 위 응답은 마지막 시도 기준입니다.

{
    "success": true,
    "data": {
        "request_id": 42,
        "channel": "naver_cafe_search",
        "status": "failed",
        "external_ref": null,
        "result_count": 0,
        "started_at": "2026-06-16T09:00:05+09:00",
        "finished_at": "2026-06-16T09:00:16+09:00",
        "duration_ms": 11000,
        "duration_sec": 11,
        "created_at": "2026-06-16T09:00:00+09:00",
        "updated_at": "2026-06-16T09:00:16+09:00",
        "error": "수집 실패 — 잠시 후 다시 시도하세요"
    }
}

최상위 data에는 항상 request_id·channel·status·external_ref·result_count·started_at·finished_at·duration_ms·duration_sec·created_at·updated_at이 포함되고, 상태에 따라 items(done)·progress+elapsed_ms(진행 중)·error(failed/cancelled)가 추가됩니다. duration_*는 허브가 잰 수집 소요 시간(시작~종료) — 자세히는 비동기 & 콜백. 요청을 잘못 시작했다면 취소 API로 중단할 수 있습니다.

결과 필드 (`items[]`)

필드	설명
post_id	글 고유 ID — `카페슬러그/글번호`. 재수집 중복 제거 키
url	카페 글 주소 `cafe.naver.com/슬러그/글번호`(검색 링크의 추적 토큰 `?art=`는 제거)
title / body	`title`=글 제목 / `body`는 기본(`collect_body=false`)이면 검색 요약(스니펫), `collect_body=true`면 전체 본문 — 단 전체공개 게시판만이고 회원 전용 글은 스니펫이 유지되며 `extra.member_only=true`가 붙습니다
author	작성자 닉네임 — 상세 수집(`collect_body`/`collect_comments`) 시에만 채워집니다(기본 `null`). 상세를 켰는데 `null`이면 회원 전용 글(`extra.member_only = true`)이거나 상세를 못 읽은 글(`extra.detail_error`)입니다
posted_at	작성 시각 (ISO8601, KST) — 목록의 상대표기(`posted_at_raw`: "3분 전")를 수집 시각 기준으로 역산한 값. 상세 수집을 켜면 카페 글의 정확한 등록시각으로 보정(기간 지정 시 목록은 `YYYY.MM.DD.` 절대 날짜)
views / comment_count	`views`=조회수 — 상세 수집 시 채워짐(카페 글 `readCount`), 목록만이면 `null`(회원 전용 글도 `null`) / `comment_count`=기본 `0`, 상세 수집 시 실제 댓글 수
recommends	미제공 — 항상 `null`. 카페 좋아요(추천) 수는 비로그인 공개 API로 제공되지 않습니다(로그인 채널 네이버 카페(가입)도 동일하게 미제공)
source	`네이버 카페 / 카페명`
extra.cafe_name	카페 이름
extra.club_slug	카페 슬러그(주소의 카페 부분)
extra.article_no	글번호
extra.cafe_id	숫자 카페 ID(상세 수집 시 채워짐, 아니면 `null`)
extra.menu	게시판(메뉴) 이름(상세 수집 시)
extra.snippet	검색 결과 요약문
extra.sort	정렬 값(요청값)
extra.member_only	회원 전용 게시판이라 본문/댓글을 못 읽었으면 `true`, 전체공개라 읽었으면 `false`, 상세 수집을 껐거나 상세를 못 읽었으면 `null`(확인 못 함 — 이유는 `detail_error`)
extra.detail_error	상세를 요청했는데 글을 읽지 못한 글만 — 이유(예: `HTTP 404 errorCode …` · 사이트 차단 감지로 받지 않음 · 상세 API 오류가 연달아 받지 않음). 이 글은 목록 값(제목·요약)만 담김
extra.comments	댓글 배열 — `collect_comments`를 켜고 상세를 읽은 글만. 항목: `comment_id` · `author` · `text` · `date`(KST) · `is_reply`(답글) · `parent_id`(답글일 때 부모 댓글 ID) · `deleted`(삭제된 댓글이면 `true`). 등록순이고 답글은 부모 바로 뒤, 글당 최대 1,000개
extra.comments_truncated	댓글이 1,000개를 넘거나 다음 쪽을 받지 못해 일부만 담겼으면 `true`(그 밖엔 키 없음)
extra.posted_at_approx	상대시각 역산이 근사치면 `true` — 상세 수집으로 정확 시각을 얻으면 `null`
extra.via_proxy	레지덴셜 프록시로 우회 수집됐으면 `true`(평소엔 `null`)
extra.source_kind	`cafe_search`
extra.comments	댓글 배열(아래 표) — `collect_comments=true`일 때

채널 참고

상세 수집(collect_body·collect_comments)은 전체공개 게시판만 본문·댓글을 읽습니다. 회원 전용 게시판 글은 본문/댓글 대신 검색 요약(스니펫)만 담기고 extra.member_only=true로 표시됩니다(오류·차단이 아니라 정상). 회원 전용 카페 전체를 수집하려면 네이버 카페(가입) 채널(로그인)을 쓰세요.
본문·댓글은 상세 조회 1회로 함께 받아옵니다 — collect_body·collect_comments 중 하나만 켜도 그 글의 상세를 한 번 조회합니다. 상세 조회는 글당 요청 1회가 추가되어 느려지고 호출량이 늘어납니다. 댓글이 10개를 넘는 글은 collect_comments일 때 댓글 쪽(100개씩)을 더 조회합니다(글당 최대 1,000개 — 2026-10-12부터, 그 전에는 10개까지만 받았습니다).
차단·캡차가 감지되면 바로 멈추고 더 요청하지 않습니다. 그때까지 받은 글은 결과에 담기며, 상세 조회가 막혔으면 그 뒤 글은 제목·요약만(extra.detail_error) 담기고 다음 쪽은 받지 않습니다. 응답에 warnings.blocked = true가 붙고, 받은 글이 하나도 없으면 failed입니다(차단으로 멈춤).
수집 한도 — 최대 약 1,020건. 한 키워드·필터 조합으로 네이버가 내려주는 카페 글은 약 1,020개(페이지당 30건)까지입니다. 더 모으려면 start_date~end_date로 기간을 나눠 수집하세요.

댓글 필드 (`extra.comments[]`)

필드	설명
comment_id	댓글 고유 ID
author	작성자
text	내용 — 글자 없이 이미지·스티커(디시콘 등)만 있는 댓글은 `[이미지]` 같은 대체 텍스트 또는 빈 문자열
date	작성 시각
is_reply	대댓글 여부(true=답글)

결과 수신(폴링·콜백) 방식은 비동기 & 콜백을 참고하세요.

네이버 카페(공개) 검색

요청 파라미터

요청 예시

응답 (202 Accepted)

결과 조회 — GET /requests/{id}

진행 중 (pending / running)

완료 (done) — 댓글 포함

실패 (failed)

결과 필드 (items[])

댓글 필드 (extra.comments[])

결과 조회 — `GET /requests/{id}`

결과 필드 (`items[]`)

댓글 필드 (`extra.comments[]`)