네이버 뉴스 검색

채널 코드 naver_news_search · 수집 환경 linux

네이버 뉴스 통합검색에서 키워드로 기사를 정렬별(최신/관련도/오래된순)·기간별로 수집합니다. 로그인 불필요(공개 검색). 기본은 제목·언론사·요약(스니펫)·작성시각·링크를 가져오며, '본문 수집'을 켜면 기사 링크로 한 번 더 들어가 전체 본문과 정확한 발행시각까지 보강합니다(네이버뉴스 제휴 기사는 균일 파싱, 그 외 언론사는 범용 추출 — best-effort). 입력은 키워드 하나면 됩니다. ⚠️ 한 키워드·필터 조합으로 접근 가능한 기사는 최대 약 2,000건입니다(네이버 검색 깊이 제한) — 더 많이 모으려면 기간을 나눠 수집하세요. 목록 시각은 상대표기('N분 전')라 수집 시각 기준으로 역산하며(원문은 posted_at_raw에 보존), 본문 수집을 켜면 상세의 정확 시각으로 보정됩니다. 차단·캡차가 감지되면 바로 멈추고 더 요청하지 않습니다(다시 시도·다른 IP 우회 없음) — 받은 데까지 결과에 담기고 warnings.blocked 가 붙으며, 받은 글이 없으면 실패로 끝납니다. result_count가 limit보다 적으면 오류가 아니라 가용 기사 부족(깊이 한도/기간 필터) 또는 일시 차단입니다.

요청 파라미터

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

키	타입	필수	기본	설명
keyword	text	예	—	네이버 뉴스 검색어(예: KT)
sort	enum	—	latest	네이버 뉴스검색 정렬(실측): 최신순=latest(sort=1) · 관련도순=relevance(sort=0) · 오래된순=oldest(sort=2)
limit	number	—	50	최대 수집 기사 수. 한 키워드·필터 조합당 최대 약 2,000개 접근 가능(네이버 검색 깊이 제한) — 초과분은 기간을 나눠 수집
start_date	date (YYYY-MM-DD)	—	—	비우면 제한 없음. 지정하면 네이버 검색 기간 필터로 그 이후 기사만 수집
end_date	date (YYYY-MM-DD)	—	—	당일 포함. 비우면 오늘까지. 시작·종료 중 하나만 넣어도 됩니다
collect_body	bool	—	false	켜면 기사마다 링크로 들어가 전체 본문 + 정확한 발행시각을 보강(기사당 요청 1회 추가 → 느려지고 호출량↑). 끄면 검색 결과의 제목·요약(스니펫)만 수집
exclude_keywords	text	—	—	이 단어가 제목에 들어간 기사는 수집 단계에서 제외(상세 요청 전 → 빠르고 상한 미차감). 쉼표로 여러 개, 한 단어 안 띄어쓰기 허용. 본문 수집을 켜면 받아온 본문에서도 한 번 더 제외
refresh	enum	—	incremental	incremental(기본): 허브가 이미 수집한 글 중 규칙에 맞는 것은 다시 쓸 수 있습니다(게시 7일 미만 글은 항상 새로 수집). full: 이번 요청은 전부 새로 수집합니다. 결과 형식은 같습니다

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

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

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

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

요청 예시

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_news_search",
    "params": {
        "keyword": "KT",
        "sort": "latest",
        "limit": 50,
        "start_date": "2026-06-01",
        "end_date": "2026-06-15",
        "collect_body": false,
        "exclude_keywords": "광고, 협찬",
        "refresh": "incremental"
    }
}'

응답 (202 Accepted)

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

{ "success": true, "data": { "request_id": 42, "channel": "naver_news_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_news_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": "list"
        },
        "elapsed_ms": 85000
    }
}

완료 (done)

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

{
    "success": true,
    "data": {
        "request_id": 42,
        "channel": "naver_news_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": "nv/656/0000181473",
                "url": "https://www.daejonilbo.com/news/articleView.html?idxno=2287999",
                "title": "KT, 국가정보자원관리원 AI 인프라 혁신 밑그림 맡는다",
                "author": "대전일보",
                "posted_at": "2026-07-14T14:49:11+09:00",
                "views": null,
                "comment_count": 0,
                "recommends": null,
                "body": "KT가 국가정보자원관리원의 AI 인프라 고도화 사업 우선협상대상자로 선정됐다 ...",
                "source": "네이버뉴스 / 대전일보",
                "extra": {
                    "press": "대전일보",
                    "snippet": "KT가 국가정보자원관리원의 AI 인프라 고도화 사업 우선협상대상자로 ...",
                    "naver_url": "https://n.news.naver.com/mnews/article/656/0000181473?sid=101",
                    "orig_url": "https://www.daejonilbo.com/news/articleView.html?idxno=2287999",
                    "sort": "latest",
                    "posted_at_approx": null,
                    "via_proxy": null
                }
            }
        ]
    }
}

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

실패 (failed)

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

{
    "success": true,
    "data": {
        "request_id": 42,
        "channel": "naver_news_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 — 네이버뉴스 제휴 기사면 `nv/언론사코드/기사번호`, 그 외 원문 기사면 `u/URL해시`. 재수집 중복 제거 키
url	기사 원문 URL(추적 파라미터 제거). 네이버뉴스 링크는 `extra.naver_url`에 별도 제공
title / body	`title`=기사 제목 / `body`는 기본(`collect_body=false`)이면 검색 요약(스니펫), `collect_body=true`면 기사 본문 전체(제휴 기사는 네이버뉴스에서, 그 외는 원문 사이트에서 추출 — 본문 없는 사이트는 스니펫 유지)
author	언론사명(`extra.press`와 동일)
posted_at	작성 시각 (ISO8601, KST) — 목록의 상대표기(`posted_at_raw`: "3분 전")를 수집 시각 기준으로 역산한 값. `collect_body=true`면 기사 상세의 정확 발행시각으로 보정
views / comment_count	뉴스는 조회수·댓글이 없어 `views=null` / `comment_count=0`
recommends	미제공 — 항상 `null`
source	`네이버뉴스 / 언론사명`
extra.press	언론사명
extra.snippet	검색 결과 요약문
extra.naver_url	네이버뉴스 링크(제휴 기사만, 아니면 `null`)
extra.orig_url	기사 원문 URL(정규화 전 원본)
extra.sort	정렬 값(요청값)
extra.posted_at_approx	상대시각 역산이 근사치면 `true`("N일 전"·"N주 전" 등 시각까지 정확하지 않음), 아니면 `null`
extra.via_proxy	레지덴셜 프록시로 우회 수집됐으면 `true`(평소엔 `null`)

채널 참고

한 키워드·필터 조합으로 접근 가능한 기사는 최대 약 2,000건입니다(네이버 검색 깊이 제한). 더 많이 모으려면 기간(start_date~end_date)을 나눠 수집하세요.
posted_at은 목록의 상대표기를 역산한 값이라 오래된 기사는 오차가 있습니다(extra.posted_at_approx=true). 정확한 발행시각이 필요하면 collect_body=true로 켜면 기사 상세 시각으로 보정됩니다.
본문 수집(collect_body=true)은 기사마다 원문을 1회 더 받아 느려지고 호출량이 늘어납니다. 네이버뉴스 제휴 기사는 안정적으로 본문이 채워지고, 그 외 언론사는 사이트 구조에 따라 스니펫만 남을 수 있습니다.
result_count가 요청 limit보다 적으면 오류가 아니라 가용 기사 부족(깊이 한도/기간 필터)이거나 일시 차단입니다.

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