유튜브 채널 검색

채널 코드 youtube_channel · 수집 환경 linux

지정한 YouTube 채널의 동영상 탭(또는 쇼츠 탭)에서 영상을 최신순/인기순으로 수집합니다. 로그인 불필요. 입력은 채널 주소 하나면 됩니다 — @핸들(예: @lguplus) 또는 채널 URL(https://www.youtube.com/@lguplus, /channel/UC…, /c/…, /user/… 전부 인식). 영상별로 제목·채널명·조회수·업로드시점·재생시간·썸네일·링크를 가져옵니다(채널 탭 카드에는 설명이 표시되지 않아 본문은 비어 있고, 쇼츠는 업로드시점도 카드에 없어 미수집). 업로드시점은 상대표기('N일 전')를 수집 시각 기준으로 역산합니다(원문 posted_at_raw 보존 — 오래된 영상일수록 오차 큼). 정렬은 YouTube 채널 페이지의 최신순/인기순 필터를 그대로 사용하며(인기순은 페이지 내 전환), 쇼츠 탭은 정렬 필터가 없어 기본 순서(최신순)로 수집됩니다. 시작일을 지정하면 최신순에서 그 날짜 이전 영상을 만날 때 수집을 종료합니다(증분 수집용). 존재하지 않는 채널은 재시도 없이 실패 처리됩니다.

요청 파라미터

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

키	타입	필수	기본	설명
channel	text	예	—	예: @lguplus 또는 https://www.youtube.com/@lguplus (channel/UC…, c/…, user/… 형식도 인식)
sort	enum	—	latest	YouTube 채널 동영상 탭의 정렬 필터(실측: 인기순 전환 시 조회수 상위부터). 쇼츠 탭은 정렬 미지원 — 기본 순서(최신순)로 수집
video_type	enum	—	video	수집할 탭. 쇼츠 탭이 없는 채널은 0건 정상 완료. 쇼츠는 카드에 업로드시점이 없어 시각 미수집(제목·조회수·링크 위주)
limit	number	—	50	최대 수집 영상 수. 스크롤로 더 깊이 수집하며 상한은 약 500개(초과 요청 시 500으로 조정)
start_date	date (YYYY-MM-DD)	—	—	최신순일 때 이 날짜 이전 영상을 만나면 수집 종료(증분 수집). 상대시각 역산이라 오래된 영상은 오차가 있습니다. 인기순에서는 해당 영상만 건너뜀
collect_details	bool	—	false	켜면 영상마다 상세를 추가 조회해 좋아요수·댓글수·본문 전문·정확한 업로드시각(쇼츠 포함)·카테고리·태그·채널 구독자수를 보강합니다. 영상당 요청 2회·수 초가 추가되므로 소량 수집에 권장(상세 보강은 상위 200건까지)
exclude_keywords	text	—	—	이 단어가 제목에 들어간 영상은 수집 단계에서 제외. 쉼표로 여러 개, 한 단어 안 띄어쓰기 허용

시작일(start_date) — 증분 수집
최신순으로 훑어 내려가다 start_date 이전 항목을 만나면 수집을 종료합니다(그 날짜 이후만 수집). 비우면 상한(limit)까지 최신순으로 수집합니다. 인기순에서는 순서가 시간순이 아니라, 이전 날짜 항목을 건너뛰기만 합니다.

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

기본은 제목 기준 — 상세 요청을 보내기 전에 걸러서 빠르고, 수집 상한(limit)도 차감하지 않습니다.
비우면 → 제외 없이 전부 수집.

요청 예시

curl -X POST https://scraper.conbus.co.kr/api/v1/collect \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "youtube_channel",
    "params": {
        "channel": "@lguplus",
        "sort": "latest",
        "video_type": "video",
        "limit": 50,
        "start_date": "2026-06-01",
        "collect_details": false,
        "exclude_keywords": "광고, 협찬"
    }
}'

응답 (202 Accepted)

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

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

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

같은 API 키로 request_id 를 조회합니다. 상태에 따라 응답이 달라집니다.

진행 중 (pending / running)

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

{
    "success": true,
    "data": {
        "request_id": 42,
        "channel": "youtube_channel",
        "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": "youtube_channel",
        "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",
        "channel_info": {
            "url": "https://www.youtube.com/@lguplus",
            "title": "LG유플러스 (LG Uplus)",
            "handle": "@lguplus",
            "channel_id": "UCp3BSINVC7Ggj4kChEUiy7Q",
            "subscribers_text": "구독자 65.8만명",
            "subscribers": 658000,
            "video_count_text": "동영상 3.7천개",
            "video_count": 3700,
            "description": "LG U+ 공식 Youtube 채널",
            "avatar": "https://yt3.googleusercontent.com/…"
        },
        "items": [
            {
                "post_id": "UOYl4xotvKw",
                "url": "https://www.youtube.com/watch?v=UOYl4xotvKw",
                "title": "오늘을 심플하게, Simply. U+",
                "author": "LG유플러스 (LG Uplus)",
                "posted_at": "2025-11-14T00:00:00+09:00",
                "views": 28580000,
                "comment_count": 0,
                "recommends": null,
                "body": null,
                "source": "YouTube / LG유플러스 (LG Uplus)",
                "extra": {
                    "channel_url": "https://www.youtube.com/@lguplus",
                    "tab": "videos",
                    "sort": "popular",
                    "duration": "0:31",
                    "thumbnail": "https://i.ytimg.com/vi/UOYl4xotvKw/hqdefault.jpg",
                    "view_text": "조회수 2858만회",
                    "published_raw": "8개월 전",
                    "is_short": null,
                    "posted_at_approx": true
                }
            }
        ]
    }
}

실패 (failed)

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

{
    "success": true,
    "data": {
        "request_id": 42,
        "channel": "youtube_channel",
        "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(11자 videoId). 재수집 중복 제거 키
url	영상 URL(`youtube.com/watch?v=…` · 쇼츠는 `youtube.com/shorts/…`)
title / body	`title`=영상 제목 / `body`는 `null` — 채널 탭 카드에는 설명이 없습니다
author	채널명(`extra.channel_url`의 채널)
posted_at	작성 시각 (ISO8601, KST) — 업로드 상대표기(`posted_at_raw`: "8개월 전")를 수집 시각 기준으로 역산(오래된 영상일수록 오차 큼). 쇼츠 탭은 카드에 업로드시점이 없어 `null`
views / comment_count	`views`=조회수(정수 — 상세 수집 시 정확값으로 갱신) / `comment_count`=기본 `0`, 상세 수집(`collect_details`) 시 실제 댓글 수
recommends	기본 `null` — 상세 수집(`collect_details`) 시 좋아요 수
source	`YouTube / 채널명`
extra.channel_url	수집 대상 채널 URL(정규화)
extra.tab	수집한 탭 — `videos` 또는 `shorts`
extra.sort	정렬 — `latest`(최신순) 또는 `popular`(인기순)
extra.duration	재생시간(쇼츠는 `null`일 수 있음)
extra.thumbnail	썸네일 이미지 URL
extra.view_text	조회수 원문 텍스트("조회수 2858만회")
extra.published_raw	업로드 상대표기 원문(쇼츠는 `null`)
extra.is_short	쇼츠 탭이면 `true`(동영상 탭은 `null`)
extra.posted_at_approx	업로드시각 역산이 근사치면 `true` — 상세 수집으로 정확 시각을 얻으면 `null`
extra.like_count	(상세 수집 시) 좋아요 수 — `recommends`와 동일 값
extra.category	(상세 수집 시) YouTube 카테고리
extra.tags	(상세 수집 시) 영상 태그 배열(최대 20개)
extra.subscriber_text	(상세 수집 시) 채널 구독자수 원문(예: `구독자 488만명`)
extra.duration_sec	(상세 수집 시) 재생시간(초)
extra.detail	상세 수집으로 보강된 항목이면 `true`

채널 참고

채널 정보(channel_info) — done 응답 최상위에 채널 단위 정보가 1회 옵니다(항목별 중복 없음): title·handle·channel_id·url·subscribers_text/subscribers(정수)·video_count_text/video_count(정수)·description·avatar. 수집 시 이미 여는 채널 페이지에서 추출하므로 추가 비용이 없습니다(항상 포함, 쇼츠 탭이 없어 0건인 경우에도).
입력 channel은 @핸들 또는 채널 URL을 받습니다(@lguplus, youtube.com/@lguplus, /channel/UC…, /c/…, /user/… 모두 인식).
정렬은 채널 페이지의 최신순/인기순을 그대로 씁니다(인기순은 조회수 상위부터). 쇼츠 탭은 정렬 필터가 없어 기본 순서(최신순)로만 수집됩니다.
상세 수집(collect_details:true) — 영상마다 상세를 추가 조회해 좋아요수·댓글수·본문 전문·정확한 업로드시각(초 단위)과 카테고리·태그·구독자수(extra)를 보강합니다. 채널 탭 카드에는 본문이 없고 쇼츠는 업로드시각도 없으므로, 이 옵션을 켜면 특히 쇼츠의 빈 필드(시각·본문·채널명)가 채워집니다. 영상당 요청 2회·수 초가 추가되며 상세 보강은 상위 200건까지입니다.
start_date를 주면 최신순에서 그 날짜 이전 영상을 만날 때 수집을 종료합니다(증분 수집). 인기순에서는 시간순이 아니라 해당 영상만 건너뜁니다.
쇼츠 탭이 없는 채널은 result_count=0으로 정상 완료합니다. 존재하지 않는 채널은 재시도 없이 failed 처리됩니다.
스크롤 방식이라 limit만큼 더 깊이 수집하며 상한은 약 500개입니다(초과 요청 시 500으로 조정).

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

유튜브 채널 검색

요청 파라미터

요청 예시

응답 (202 Accepted)

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

진행 중 (pending / running)

완료 (done)

실패 (failed)

결과 필드 (items[])

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

결과 필드 (`items[]`)