유튜브 검색

채널 코드 youtube_search · 수집 환경 linux

YouTube 검색 결과를 키워드로 정렬별(관련도/최신/인기/평점)·기간별·구분별(동영상/쇼츠/채널/재생목록)로 수집합니다. 로그인 불필요(공개 검색). 수집 서버가 실제 Chrome으로 검색 결과 피드를 스크롤하며 각 영상의 제목·설명(요약)·채널·조회수·업로드시점·재생시간·썸네일·링크를 가져옵니다(쇼츠는 카드에 채널·업로드시점이 표시되지 않아 제목·조회수·링크 위주). 입력은 키워드 하나면 됩니다. 스크롤 방식이라 limit만큼 더 깊이 수집하며 상한은 약 500개입니다(그 이상은 키워드/기간을 나눠 수집). 업로드시점은 상대표기('N시간 전')를 수집 시각 기준으로 역산합니다(원문은 posted_at_raw에 보존). ⚠️ YouTube는 정확 일치가 부족하면 관련성 낮은 영상을 구분 없이 섞어 주므로, 기본으로 '검색어 포함 영상만' 필터가 켜져 있습니다(키워드가 제목/설명/채널명에 없는 영상 제외 — 영상 속 발화로만 관련된 영상까지 보려면 끄세요). 최신순은 YouTube 정렬이 느슨해 수집분을 업로드 시점 기준으로 재정렬합니다 — 진짜 최근만 원하면 기간(이번주/오늘)을 함께 지정하세요.

요청 파라미터

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

키	타입	필수	기본	설명
keyword	text	예	—	YouTube 검색어(예: KT)
sort	enum	—	relevance	YouTube 검색 정렬(sp 필터). 최신순(date)은 YouTube 정렬이 느슨해 수집분을 업로드 시점으로 재정렬 — 기간 필터 병용 권장
date	enum	—	any	업로드 기간 필터(YouTube sp). 최신 영상만 원하면 today/week 등과 최신순을 함께 쓰면 확실합니다
video_type	enum	—	video	결과 구분(YouTube sp 필터, 실측: 동영상=EgIQAQ · 쇼츠=EgIQCQ). 쇼츠는 검색 카드에 채널·업로드시점이 없어 제목·조회수·링크 위주로 수집
limit	number	—	50	최대 수집 영상 수. 스크롤로 더 깊이 수집하며 상한은 약 500개(초과 요청 시 500으로 조정). 넓게 받으려면 키워드/기간 분할 권장
strict_match	bool	—	true	YouTube는 정확 일치가 부족하면 관련성 낮은 영상을 구분 없이 채워 줍니다 → 켜면 키워드가 제목/설명/채널명에 포함된 영상만 수집(공백 무시 비교, 제외분은 상한에 안 세고 백필). 영상 속 발화(자막)로만 관련된 영상까지 필요하면 끄세요
collect_details	bool	—	false	켜면 영상마다 상세를 추가 조회해 좋아요수·댓글수·본문 전문·정확한 업로드시각(쇼츠 포함)·카테고리·태그·채널 구독자수를 보강합니다. 영상당 요청 2회·수 초가 추가되므로 소량 수집에 권장(상세 보강은 상위 200건까지)
exclude_keywords	text	—	—	이 단어가 제목/설명에 들어간 영상은 수집 단계에서 제외. 쉼표로 여러 개, 한 단어 안 띄어쓰기 허용(예: 쇼츠, 라이브)

제외 키워드(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_search",
    "params": {
        "keyword": "KT",
        "sort": "relevance",
        "date": "any",
        "video_type": "video",
        "limit": 50,
        "strict_match": true,
        "collect_details": false,
        "exclude_keywords": "광고, 협찬"
    }
}'

응답 (202 Accepted)

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

{ "success": true, "data": { "request_id": 42, "channel": "youtube_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": "youtube_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": "youtube_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": "aEKu-OtQKYA",
                "url": "https://www.youtube.com/watch?v=aEKu-OtQKYA",
                "title": "[KIA vs KT] 9회 말 5점차 승부를 뒤집은 끝내기",
                "author": "KBO",
                "posted_at": "2026-06-23T15:35:00+09:00",
                "views": 309581,
                "comment_count": 0,
                "recommends": null,
                "body": "프로야구 하이라이트 KIA와 KT의 명승부 ...",
                "source": "YouTube / KBO",
                "extra": {
                    "duration": "11:13",
                    "thumbnail": "https://i.ytimg.com/vi/aEKu-OtQKYA/hqdefault.jpg",
                    "published_raw": "3주 전",
                    "view_text": "조회수 30만회",
                    "sort": "relevance",
                    "is_short": null,
                    "posted_at_approx": true
                }
            }
        ]
    }
}

실패 (failed)

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

{
    "success": true,
    "data": {
        "request_id": 42,
        "channel": "youtube_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(11자 videoId). 재수집 중복 제거 키
url	영상 URL(`youtube.com/watch?v=…` · 쇼츠는 `youtube.com/shorts/…`)
title / body	`title`=영상 제목 / `body`=검색 결과의 설명 요약(있을 때, 쇼츠는 대부분 없어 `null`)
author	채널명
posted_at	작성 시각 (ISO8601, KST) — 업로드 상대표기(`posted_at_raw`: "3주 전")를 수집 시각 기준으로 역산한 값
views / comment_count	`views`=조회수(정수, 쇼츠 포함 — 상세 수집 시 정확값으로 갱신) / `comment_count`=기본 `0`, 상세 수집(`collect_details`) 시 실제 댓글 수
recommends	기본 `null` — 상세 수집(`collect_details`) 시 좋아요 수
source	`YouTube / 채널명`
extra.duration	재생시간(`11:13`, 쇼츠는 `null`일 수 있음)
extra.thumbnail	썸네일 이미지 URL(videoId 기반, 항상 유효)
extra.published_raw	업로드 상대표기 원문("3주 전")
extra.view_text	조회수 원문 텍스트("조회수 30만회")
extra.sort	정렬 값(요청값)
extra.is_short	쇼츠면 `true`(일반 영상은 `null`)
extra.posted_at_approx	업로드시각 역산이 근사치면 `true`("N일 전" 이상) — 상세 수집으로 정확 시각을 얻으면 `null`
extra.like_count	(상세 수집 시) 좋아요 수 — `recommends`와 동일 값
extra.category	(상세 수집 시) YouTube 카테고리(예: `Science & Technology`)
extra.tags	(상세 수집 시) 영상 태그 배열(최대 20개)
extra.subscriber_text	(상세 수집 시) 채널 구독자수 원문(예: `구독자 488만명`)
extra.duration_sec	(상세 수집 시) 재생시간(초)
extra.detail	상세 수집으로 보강된 항목이면 `true`

채널 참고

검색어 포함 영상만(strict_match=true, 기본) — YouTube는 정확 일치가 부족하면 관련성 낮은 영상을 구분 없이 채워 주므로, 키워드가 제목/설명/채널명에 든 영상만 수집합니다. 영상 속 발화(자막)로만 관련된 영상까지 보려면 strict_match:false로 끄세요. 제외분은 limit에 세지 않고 백필합니다.
상세 수집(collect_details:true) — 영상마다 상세를 추가 조회해 좋아요수(recommends)·댓글수(comment_count)·본문 전문(body)·정확한 업로드시각(초 단위, 쇼츠 포함)과 카테고리·태그·구독자수(extra)를 보강합니다. 영상당 요청 2회·수 초가 추가되므로 소량 수집에 권장하며, 상세 보강은 상위 200건까지입니다. 댓글이 꺼진 영상은 댓글수가 0으로 남습니다.
최신순(sort:date)은 YouTube 정렬이 느슨해 수집분을 업로드 시점 기준으로 재정렬합니다(상세 수집 시 정확 시각 기준 정밀 재정렬). 진짜 최근만 원하면 기간(date:today/week 등)을 함께 지정하세요.
쇼츠(video_type:shorts)는 카드에 채널·업로드시점이 표시되지 않아 기본은 제목·조회수·링크 위주 — 상세 수집을 켜면 쇼츠도 채널명·정확 시각·본문·좋아요·댓글수가 채워집니다.
스크롤 방식이라 limit만큼 더 깊이 수집하며 상한은 약 500개입니다(초과 요청 시 500으로 조정).

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