youtube/
search-suggestions

입력 중인 검색어에 대해 YouTube 검색창이 보여 주는 자동완성 추천어를, 선택한 언어와 지역 기준으로 시청자에게 보이는 순서 그대로 가져옵니다.

YouTube Search Suggestions API

자동완성
언어와 지역
요청당 고정 요금
요청당 0.5 크레딧
준비됨
준비됨

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

README

SocQ 작성 · 업데이트

YouTube Search Suggestions

검색 추천어는 시청자가 아직 입력하는 동안 YouTube 검색창이 제안하는 완성 문구로, 시청자의 언어와 국가에 맞춰 순위가 매겨집니다. 시드 키워드 주변의 실제 수요 표현을 그대로 보여 주므로 키워드 조사, 동영상 제목, 태그, 콘텐츠 아이디어를 얻는 직접적인 출처가 됩니다.

YouTube Search Suggestions API 주요 기능

  • 시청자에게 보이는 순서rank 값에 드롭다운 속 각 추천어의 위치가 기록되며, 맨 위 완성 문구가 1부터 시작합니다.
  • 시장 선택language와 region 값으로 다른 시장의 추천어로 바꿀 수 있습니다. 예를 들어 es와 MX를 지정하면 멕시코 스페인어 검색 기준이 됩니다.
  • 문구마다 검색 링크 제공모든 추천어에는 해당 문구의 YouTube 검색 결과 URL이 붙고, 요청에 사용한 시드 검색어와 시장 정보도 함께 담깁니다.

YouTube Search Suggestions API 매개변수

매개변수필수설명
query필수자동완성할 검색어의 앞부분으로, 최대 100자입니다.
language선택추천어의 언어 코드로, en, es, pt-BR 등을 사용합니다. 기본값은 en입니다.
region선택검색 시장의 두 글자 국가 코드로, US, GB 등을 사용합니다. 기본값은 US입니다.

YouTube Search Suggestions API 사용 방법

검색어 앞부분을 보내고 순위가 매겨진 완성 문구를 읽어 옵니다.

  1. {"query": "iphone 17"}을 /v1/youtube/search-suggestions로 POST합니다. 다른 시장이 필요하면 language와 region을 추가합니다.
  2. status가 succeeded가 될 때까지 GET /v1/tasks/{task_id}를 폴링합니다.
  3. results.items에서 추천어를 순위 순서대로 읽고, has_more가 true인 동안 results.next_cursor로 이어서 가져옵니다.
curl -X POST "https://api.socq.ai/v1/youtube/search-suggestions" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"iphone 17"}'

# Each item is one suggestion: keyword, rank, language and region.

YouTube Search Suggestions API 추천 활용 사례

  • 시드 키워드 확장: 제품이나 주제 이름의 완성 문구를 모아 시청자가 실제로 검색하는 더 긴 표현을 찾습니다.
  • 검색어에 맞춘 제목 작성: 상위 추천어의 표현을 골라 동영상 제목이 사람들이 실제로 입력하는 검색어와 같아지도록 합니다.
  • 시장별 수요 비교: 같은 시드 키워드를 language와 region 값만 바꿔 실행하고, 국가마다 검색 의도가 어떻게 달라지는지 확인합니다.

YouTube Search Suggestions API 활용 팁

  • iphone 17 a처럼 시드 뒤에 글자 하나를 붙이면 그 글자로 이어지는 완성 문구를 가져올 수 있습니다.
  • 시장마다 서로 다른 목록이 반환되므로, 시드 키워드를 장기간 추적할 때는 language와 region 값을 고정하세요.

YouTube Search Suggestions API 외에 YouTube의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.

  • YouTube Channel Videos API — 채널 URL에서 쇼츠와 라이브 방송을 제외한 일반 공개 동영상을 수집합니다.
  • YouTube Comments API — 공개 댓글, 작성자, 참여도, 원본 동영상, 대화 맥락을 수집합니다.
  • YouTube Search API — 키워드로 공개 일반 동영상을 검색하며, 지원되는 메타데이터 필터를 사용할 수 있습니다.
  • YouTube Hashtag Search API — 해시태그 피드에서 공개 동영상을 찾으며, 전체 콘텐츠 또는 쇼츠만 선택해 수집할 수 있습니다.
  • YouTube Channel Search API — 키워드로 채널을 찾으며, 채널 이름, 구독자 수, 아바타, 설명 일부를 포함합니다.
  • YouTube Shorts Search API — 키워드로 쇼츠를 검색하며, 링크, 캡션, 조회수, 세로형 썸네일을 포함합니다.

다른 플랫폼 둘러보기

YouTube 데이터를 지원되는 다른 소셜 플랫폼의 공개 데이터와 함께 활용하세요.

YouTube Search Suggestions API — 자주 묻는 질문

YouTube Search Suggestions API는 입력 중인 검색어에 대한 YouTube 검색 자동완성 추천어를 선택한 언어와 지역 기준으로 가져오는 프로그래밍 인터페이스입니다. 추천 문구마다 순위를 함께 반환합니다.

네. 추천어는 입력하는 동안 YouTube 검색창에 표시되는 완성 문구이며, 같은 순서로 반환됩니다.

해당 검색어에 대해 YouTube가 제안하는 만큼 반환하며, 보통 10여 개입니다.

공식 Data API에는 자동완성이나 입력 추천 엔드포인트가 없습니다. 이 엔드포인트는 YouTube 검색창에 표시되는 추천어를 선택한 언어와 지역 기준의 순위로 반환합니다.

추천어가 몇 개 반환되든 요청 1건당 0.5 크레딧이 고정으로 차감됩니다.