YouTube Search
YouTube 검색 결과는 키워드나 문구에 일치하는 일반 공개 동영상으로, 제목, 채널, 썸네일, 재생 시간, 게시 정보, 공개된 참여 지표를 담고 있습니다. 이러한 레코드는 주제 탐색, 콘텐츠 조사, 경쟁사 추적, 기회 분석에 활용할 수 있습니다.
YouTube Search API 주요 기능
- URL 없이 동영상 탐색URL을 미리 알지 못해도 공개된 일반 동영상을 찾아냅니다.
- 결과 정렬관련도, 게시일, 평점, 공개 조회수 기준으로 결과를 정렬합니다.
- 게시 기간지난 1시간·1일·1주·1개월·1년 단위의 게시 기간으로 결과를 필터링합니다.
- 재생 시간 및 자막 필터짧은(short)·중간(medium)·긴(long) 재생 시간으로 필터링하고, 필요하면 자막이 있는 동영상만 요구합니다.
- 정규화된 동영상 결과정규화된 동영상 메타데이터, 채널 정보, 썸네일, 재생 시간, 게시 데이터, 공개 지표를 반환합니다.
YouTube Search API 매개변수
| 매개변수 | 필수 | 설명 |
|---|---|---|
query | 필수 | 공개 동영상을 찾는 데 사용하는 키워드 또는 문구입니다. |
results_limit | 선택 | 요청할 공개 동영상 결과의 최대 개수입니다. 양의 정수여야 하며 기본값은 100입니다. |
sort_by | 선택 | 결과 정렬 방식입니다. 기본값은 relevance입니다. |
published_within | 선택 | 현재 요청 시점을 기준으로 하는 선택적 게시 기간입니다. |
duration | 선택 | 선택적 YouTube 재생 시간 카테고리입니다. |
has_captions | 선택 | 자막 제공 여부로 거르는 선택적 필터입니다. 이 필터를 쓰지 않으려면 건드리지 마세요. |
YouTube Search API 사용 방법
쿼리를 단순한 키워드가 아니라 검색 전략으로 작성하세요. 전체 상황을 살펴볼 수 있을 만큼 넓게 시작한 뒤 필터를 하나씩 추가하면, 어떤 결정이 후보를 걸러냈는지 알 수 있습니다.
- 주제와 질문을 정합니다. 가장 잘 맞는 주제 일치, 최신 보도, 조회수가 높은 항목, 스크립트를 바로 쓸 수 있는 후보 중 무엇이 필요한지 정하세요.
- query와 results_limit, 그리고 해당 질문에 필요한 정렬과 필터만 /v1/youtube/search로 POST합니다.
- 전체 요청을 task_id와 함께 저장하고, 탐색이 성공하거나 실패할 때까지 /v1/tasks/{task_id}를 폴링합니다.
- 동영상 ID로 결과의 중복을 제거하고, 순위 컨텍스트와 collected_at을 보존하며, has_more가 true인 동안 페이지네이션합니다.
curl -X POST "https://api.socq.ai/v1/youtube/search" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"NASA Artemis","results_limit":10,"sort_by":"date","published_within":"month","duration":"medium","has_captions":true}'
# Poll GET /v1/tasks/{task_id}
# Read GET /v1/tasks/{task_id}?limit=50YouTube Search API 추천 활용 사례
- 주제·시장 조사: 제품, 산업, 조직, 이벤트, 새로 떠오르는 주제에 관한 공개 동영상을 찾아냅니다.
- 크리에이터·경쟁사 발굴: 검색 결과와 게시 채널 정보를 활용해 관련 크리에이터, 브랜드, 경쟁사를 파악합니다.
- 최신 동영상 모니터링: 날짜순 정렬과 게시 기간을 조합해 검토나 분석을 위한 최신 동영상을 수집합니다.
- 스크립트 준비용 데이터셋: 자막이 있는 동영상만 요구해 스크립트 수집, 요약, 분류, 검색에 쓸 동영상을 찾습니다.
YouTube Search API 활용 팁
- 모든 개념을 긴 문구 하나에 담지 말고, 정확한 쿼리 변형 두세 개를 테스트하세요. 겹치는 부분이 차이점만큼 많은 정보를 주는 경우가 많습니다.
- 필터는 단계적으로 추가하세요. 게시 기간, 재생 시간, 자막을 한꺼번에 지정하면 결과가 비었을 때 어떤 조건이 너무 좁았는지 알기 어렵습니다.
- 모니터링에는 published_within과 함께 date를 사용하세요. 기간 없이 relevance를 쓰면 다른, 더 넓은 조사 질문에 답하게 됩니다.
- 순위는 안정적이지 않습니다. 표본의 위치나 구성이 중요하다면 요청, 작업 ID, 동영상 ID, collected_at을 저장하세요.
- results_limit은 상한일 뿐 완전성을 보장하지 않습니다. 공개 자격 여부와 선택한 필터에 따라 레코드가 더 적게 나올 수 있습니다.
- 쿼리 변형 사이의 중복은 동영상 ID로 제거하되, 이후 관련도 분석을 위해 각 결과가 어떤 쿼리에서 나왔는지는 보관하세요.
- URL을 알게 된 뒤에는 반복해서 검색하지 말고, 최신 상세 정보는 Videos로, 사용 가능한 자막 텍스트는 Transcripts로 조회하세요.
관련 API
YouTube Search API 외에 YouTube의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.
- YouTube Comments API — 공개 댓글, 작성자, 참여도, 원본 동영상, 대화 맥락을 수집합니다.
- YouTube Transcripts API — 제공되는 일반 텍스트 스크립트를 가져오며, 언어를 선택할 수 있습니다.
- YouTube Channels API — 공개 채널 정보, 이미지, 인증 여부, 공개된 오디언스 통계를 가져옵니다.
- YouTube Videos API — 알고 있는 동영상 또는 쇼츠 URL의 메타데이터, 썸네일, 길이, 참여도를 가져옵니다.
- YouTube Hashtag Search API — 해시태그 피드에서 공개 동영상을 찾으며, 전체 콘텐츠 또는 쇼츠만 선택해 수집할 수 있습니다.
- YouTube Channel Search API — 키워드로 채널을 찾으며, 채널 이름, 구독자 수, 아바타, 설명 일부를 포함합니다.
- YouTube Channel Videos API
- YouTube Shorts API
- YouTube Channel Live Videos API
- YouTube Comment Replies API
- YouTube Community Posts API
- YouTube Playlist Videos API
- YouTube Trending Shorts API
- YouTube Community Post API
- YouTube Community Post Comments API
- YouTube Related Videos API
- YouTube Shorts Search API
- YouTube Search Suggestions API
- YouTube Email Finder API
- YouTube Trending Videos API