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 사용 방법
검색어 앞부분을 보내고 순위가 매겨진 완성 문구를 읽어 옵니다.
- {"query": "iphone 17"}을 /v1/youtube/search-suggestions로 POST합니다. 다른 시장이 필요하면 language와 region을 추가합니다.
- status가 succeeded가 될 때까지 GET /v1/tasks/{task_id}를 폴링합니다.
- 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 값을 고정하세요.
관련 API
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 Transcripts API
- YouTube Channels API
- YouTube 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 Email Finder API
- YouTube Trending Videos API