youtube/
search

키워드로 공개 YouTube 동영상을 검색하며, 정렬·날짜·재생 시간·자막 필터를 지원하고 정규화된 메타데이터, 채널 컨텍스트, 썸네일, 참여도를 반환합니다.

YouTube Search API

동영상 검색
탐색
범용 필터
결과당 0.5 크레딧
준비됨
준비됨

매개변수를 입력하고 요청을 전송하세요. 작업 상태와 정규화된 결과가 여기에 표시됩니다.

README

SocQ 작성 · 업데이트

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 사용 방법

쿼리를 단순한 키워드가 아니라 검색 전략으로 작성하세요. 전체 상황을 살펴볼 수 있을 만큼 넓게 시작한 뒤 필터를 하나씩 추가하면, 어떤 결정이 후보를 걸러냈는지 알 수 있습니다.

  1. 주제와 질문을 정합니다. 가장 잘 맞는 주제 일치, 최신 보도, 조회수가 높은 항목, 스크립트를 바로 쓸 수 있는 후보 중 무엇이 필요한지 정하세요.
  2. query와 results_limit, 그리고 해당 질문에 필요한 정렬과 필터만 /v1/youtube/search로 POST합니다.
  3. 전체 요청을 task_id와 함께 저장하고, 탐색이 성공하거나 실패할 때까지 /v1/tasks/{task_id}를 폴링합니다.
  4. 동영상 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=50

YouTube Search API 추천 활용 사례

  • 주제·시장 조사: 제품, 산업, 조직, 이벤트, 새로 떠오르는 주제에 관한 공개 동영상을 찾아냅니다.
  • 크리에이터·경쟁사 발굴: 검색 결과와 게시 채널 정보를 활용해 관련 크리에이터, 브랜드, 경쟁사를 파악합니다.
  • 최신 동영상 모니터링: 날짜순 정렬과 게시 기간을 조합해 검토나 분석을 위한 최신 동영상을 수집합니다.
  • 스크립트 준비용 데이터셋: 자막이 있는 동영상만 요구해 스크립트 수집, 요약, 분류, 검색에 쓸 동영상을 찾습니다.

YouTube Search API 활용 팁

  • 모든 개념을 긴 문구 하나에 담지 말고, 정확한 쿼리 변형 두세 개를 테스트하세요. 겹치는 부분이 차이점만큼 많은 정보를 주는 경우가 많습니다.
  • 필터는 단계적으로 추가하세요. 게시 기간, 재생 시간, 자막을 한꺼번에 지정하면 결과가 비었을 때 어떤 조건이 너무 좁았는지 알기 어렵습니다.
  • 모니터링에는 published_within과 함께 date를 사용하세요. 기간 없이 relevance를 쓰면 다른, 더 넓은 조사 질문에 답하게 됩니다.
  • 순위는 안정적이지 않습니다. 표본의 위치나 구성이 중요하다면 요청, 작업 ID, 동영상 ID, collected_at을 저장하세요.
  • results_limit은 상한일 뿐 완전성을 보장하지 않습니다. 공개 자격 여부와 선택한 필터에 따라 레코드가 더 적게 나올 수 있습니다.
  • 쿼리 변형 사이의 중복은 동영상 ID로 제거하되, 이후 관련도 분석을 위해 각 결과가 어떤 쿼리에서 나왔는지는 보관하세요.
  • URL을 알게 된 뒤에는 반복해서 검색하지 말고, 최신 상세 정보는 Videos로, 사용 가능한 자막 텍스트는 Transcripts로 조회하세요.

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 데이터를 지원되는 다른 소셜 플랫폼의 공개 데이터와 함께 활용하세요.

YouTube Search API — 자주 묻는 질문

YouTube Search API는 키워드나 문구로 일반 공개 동영상을 찾으며, 지원되는 정렬과 필터를 사용할 수 있습니다. 정규화된 메타데이터, 채널 정보, 썸네일, 재생 시간, 게시일, 참여 지표, 수집 시각을 반환합니다.

주제, 인물, 제품, 조직, 브랜드, 캠페인, 이벤트처럼 비어 있지 않은 키워드나 문구를 제출합니다.

sort_by는 relevance, date, rating, view_count를 받으며 기본값은 relevance입니다.

published_within, duration, has_captions로 필터링할 수 있습니다. 게시 기간은 hour, day, week, month, year이고, 재생 시간 값은 short, medium, long입니다.

아니요. 결과는 제한된 공개 표본이며 순위, 신선도, 지역, 언어, 제공 가능 여부, 선택한 필터에 따라 달라질 수 있습니다.

아니요. has_captions는 자막 제공 여부로 거르는 필터입니다. 선택한 동영상 URL의 일반 텍스트 자막은 Transcripts로 가져오세요.

반환된 정규화 검색 결과 1건당 0.5 크레딧이 차감됩니다.