API Reference

YouTube Data API를 사용하면 YouTube 웹사이트에서 일반적으로 실행하는 기능을 사용자의 웹사이트 또는 애플리케이션에 통합할 수 있습니다. 아래 목록에서는 API를 사용하여 검색할 수 있는 다양한 유형의 리소스를 확인합니다. API는 이러한 여러 개의 리소스를 삽입하거나 업데이트 또는 삭제하는 메소드도 지원합니다.

참조 가이드에서는 API로 이러한 모든 작업을 수행하는 방법을 설명합니다. 이 가이드는 리소스 유형별로 정리되어 있습니다. 리소스란 동영상, 재생 목록 또는 구독과 같이 YouTube 환경을 구성하는 항목 유형을 의미합니다. 가이드에는 리소스 유형별로 하나 이상의 데이터 표현이 나와 있으며 리소스는 JSON 개체로 표시됩니다. 또한 리소스 유형별로 지원되는 하나 이상의 메소드(LIST, POST, DELETE 등)와 함께 애플리케이션에서 이러한 메소드를 사용하는 방법에 대해 설명합니다.

API 호출

다음은 YouTube Data API 요청에 적용되는 요구 사항입니다.

  1. 모든 요청은 API 키(key 매개변수 포함)를 지정하거나 OAuth 2.0 토큰을 제공해야 합니다. API 키는 APIs Console에서 프로젝트의 API Access 창에 있습니다.

  2. 모든 삽입, 업데이트 및 삭제 요청 시에는 반드시 인증 토큰을 전송해야 합니다. 또한 인증된 사용자의 비공개 데이터를 검색하는 모든 요청 시에도 인증 토큰을 전송해야 합니다.

    리소스 검색을 위한 일부 API 메소드의 경우 인증이 필요한 매개변수를 지원하거나 요청이 인증될 때 추가 메타데이터를 포함할 수 있습니다. 예를 들어 사용자가 업로드한 동영상을 검색하는 요청에는 특정 사용자가 요청을 인증할 경우 비공개 동영상도 포함될 수 있습니다.

  3. API는 OAuth 2.0 인증 프로토콜을 지원합니다. OAuth 2.0 토큰은 다음 방법 중 하나로 제공할 수 있습니다.

    • access_token 쿼리 매개변수 사용, 예: ?access_token=oauth2-token
    • HTTP Authorization 헤더 사용, 예: Authorization: Bearer oauth2-token

    애플리케이션에 OAuth 2.0 인증을 구현하기 위한 전체 지침은 인증 가이드에 나와 있습니다.

리소스 유형

API는 다음과 같은 유형의 리소스와 상호작용합니다.

  1. activities
  2. channelBanners
  3. channels
  4. guideCategories
  5. playlistItems
  6. playlists
  7. search
  8. subscriptions
  9. thumbnails
  10. videoCategories
  11. videos

activities

activity 리소스에는 특정 채널이나 사용자가 YouTube에서 실행한 작업의 정보가 포함되어 있습니다. 활동 피드로 보고되는 작업에는 동영상 평가, 동영상 공유, 동영상을 즐겨찾기에 추가, 동영상에 댓글 달기, 동영상 업로드 등이 있습니다. 각 activity 리소스를 통해 작업의 유형, 작업에 연결된 채널, 평가되거나 업로드된 동영상 등의 작업을 확인할 수 있습니다.

이 리소스에 대한 자세한 내용은 리소스 표현 및 속성 목록을 참조하세요.

메소드 HTTP 요청 설명
https://www.googleapis.com/youtube/v3의 상대 URI
list GET /activities 요청 기준과 일치하는 채널 활동 이벤트의 목록을 반환합니다. 예를 들어 특정 채널과 관련된 이벤트, 사용자의 구독정보 및 Google+ 친구 또는 사용자별로 맞춤 설정되는 YouTube 홈페이지 피드와 관련된 이벤트를 검색할 수 있습니다.
insert POST /activities 특정 채널의 게시판을 올립니다. (요청을 제출하는 사용자에게 채널을 대신하여 작업할 수 있는 권한이 부여되어야 합니다.)

참고: activity 리소스에 사용자의 동영상 평가 또는 동영상을 즐겨찾기에 추가 같은 작업 정보를 포함시킬 수도 있지만, 이러한 activity 리소스를 생성하려면 다른 API 메소드를 사용해야 합니다. 예를 들어 API의 videos.rate() 메소드를 사용해 동영상을 평가하고 playlistItems.insert() 메소드를 사용해 동영상을 즐겨찾기에 추가할 수 있습니다.

channelBanners

channelBanner 리소스에는 새로 업로드한 이미지를 채널의 배너 이미지로 설정하는 데 사용할 URL이 포함되어 있습니다.

이 리소스에 대한 자세한 내용은 리소스 표현 및 속성 목록을 참조하세요.

메소드 HTTP 요청 설명
https://www.googleapis.com/youtube/v3의 상대 URI
insert POST /channelBanners/insert YouTube에 채널 배너 이미지를 업로드합니다. 이 메소드는 다음과 같이 채널의 배너 이미지를 업데이트하는 3단계 절차 중 처음 두 단계를 나타냅니다.

  1. channelBanners.insert 메소드를 호출하여 YouTube에 바이너리 이미지 데이터를 업로드합니다. 이미지는 화면 비율이 16:9여야 하며 최소 2120x1192픽셀 이상이어야 합니다.
  2. API가 1단계에서 반환한 응답으로부터 url 속성 값을 추출합니다.
  3. channels.update 메소드를 호출해 채널의 브랜드 설정을 업데이트합니다. brandingSettings.image.bannerExternalUrl 속성 값을 2단계에서 확인한 URL로 설정합니다.

channels

channel 리소스에는 YouTube 채널에 대한 정보가 포함되어 있습니다.

이 리소스에 대한 자세한 내용은 리소스 표현 및 속성 목록을 참조하세요.

메소드 HTTP 요청 설명
https://www.googleapis.com/youtube/v3의 상대 URI
list GET /channels 요청 기준과 일치하는 0개 이상의 channel 리소스 집합을 반환합니다.
update PUT /channels 채널의 메타데이터를 업데이트합니다. 이 메소드는 현재 channel 리소스의 brandingSettings 및 invideoPromotion 개체와 해당 하위 속성의 업데이트만 지원합니다.

guideCategories

guideCategory 리소스는 YouTube 알고리즘이 채널의 콘텐츠 또는 인기도와 같은 기타 지표를 바탕으로 지정한 카테고리를 확인합니다. 이 목록은 동영상 카테고리와 유사하나, 동영상 카테고리는 동영상 업로더가 지정할 수 있고 채널 카테고리는 YouTube만 지정할 수 있다는 점이 다릅니다.

이 리소스에 대한 자세한 내용은 리소스 표현 및 속성 목록을 참조하세요.

메소드 HTTP 요청 설명
https://www.googleapis.com/youtube/v3의 상대 URI
list GET /guideCategories YouTube 채널과 관련된 카테고리의 목록을 반환합니다.

playlistItems

playlistItem 리소스는 재생목록에 포함된 동영상과 같은 다른 리소스를 확인합니다. 또한 playlistItem 리소스에는 재생목록에서 리소스가 사용되는 방식과 관련하여 포함된 리소스에 대한 세부정보가 포함되어 있습니다.

YouTube 재생목록은 다음과 같은 채널의 특별한 동영상 모음을 구분합니다.

  • 업로드한 동영상
  • 즐겨찾는 동영상
  • 긍정적 평가(좋아요)를 받은 동영상
  • 감상한 동영상
  • 나중에 볼 동영상
보다 구체적으로 이러한 목록은 개인, 그룹 또는 회사의 동영상, 재생목록 및 기타 YouTube 정보의 모음인 채널과 연결되어 있습니다.

각 목록의 재생목록 ID는 해당 채널의 channel resource 리소스로부터 검색할 수 있습니다. 그런 다음 playlistItems.list 메소드를 사용해 원하는 목록을 검색합니다. playlistItems.insert 및 playlistItems.delete 메소드를 호출해 목록에 항목을 추가하거나 목록에서 항목을 삭제할 수도 있습니다. 예를 들어 사용자가 동영상을 즐겨찾기에 추가한 경우 해당 동영상을 사용자 채널의 즐겨찾기 동영상 재생목록에 넣을 수 있습니다.

이 리소스에 대한 자세한 내용은 리소스 표현 및 속성 목록을 참조하세요.

메소드 HTTP 요청 설명
https://www.googleapis.com/youtube/v3의 상대 URI
delete DELETE /playlistItems 재생목록의 항목을 삭제합니다.
insert POST /playlistItems 재생목록에 리소스를 추가합니다.
list GET /playlistItems API 요청 매개변수와 일치하는 재생목록 항목의 모음을 반환합니다. 지정된 재생목록의 모든 항목을 검색하거나 고유 ID를 통해 하나 또는 여러 개의 재생목록 항목을 검색할 수 있습니다.
update PUT /playlistItems 재생목록의 항목을 수정합니다. 예를 들어 재생목록 내에서 항목의 위치를 변경할 수 있습니다.

playlists

playlist 리소스는 YouTube 재생목록을 나타냅니다. 재생목록은 순서대로 감상하거나 다른 사용자와 공유할 수 있는 동영상의 모음입니다. 재생목록은 최대 200개의 동영상을 포함할 수 있으며 사용자가 만들 수 있는 재생목록의 수에는 제한이 없습니다. 재생목록은 기본적으로 다른 사용자에게 공개되지만 비공개로 설정할 수도 있습니다.

YouTube 재생목록은 다음과 같은 채널의 특별한 동영상 모음을 구분합니다.

  • 업로드한 동영상
  • 즐겨찾는 동영상
  • 긍정적 평가(좋아요)를 받은 동영상
  • 감상한 동영상
  • 나중에 볼 동영상
보다 구체적으로 이러한 목록은 개인, 그룹 또는 회사의 동영상, 재생목록 및 기타 YouTube 정보의 모음인 채널과 연결되어 있습니다. 각 목록의 재생목록 ID는 해당 채널의 channel resource 리소스로부터 검색할 수 있습니다.

그런 다음 playlistItems.list 메소드를 사용해 원하는 목록을 검색합니다. playlistItems.insert 및 playlistItems.delete 메소드를 호출해 목록에 항목을 추가하거나 목록에서 항목을 삭제할 수도 있습니다.

이 리소스에 대한 자세한 내용은 리소스 표현 및 속성 목록을 참조하세요.

메소드 HTTP 요청 설명
https://www.googleapis.com/youtube/v3의 상대 URI
delete DELETE /playlists 재생목록을 삭제합니다.
list GET /playlists API 요청 매개변수와 일치하는 재생목록의 그룹을 반환합니다. 예를 들어 인증된 사용자가 보유한 전체 재생목록을 검색하거나, 고유 ID를 통해 하나 또는 여러 개의 재생목록을 검색할 수 있습니다.
insert POST /playlists 재생목록을 만듭니다.
update PUT /playlists 재생목록을 수정합니다. 예를 들어 재생목록의 제목, 설명, 개인정보 보호 상태를 변경할 수 있습니다.

검색 결과에는 API 요청에 지정된 검색 매개변수와 일치하는 YouTube 동영상, 채널 또는 재생목록의 정보가 포함되어 있습니다. 검색 결과는 동영상과 같이 고유하게 식별할 수 있는 리소스를 보여주지만, 자체적으로는 영구적인 데이터를 가지지 않습니다.

이 리소스에 대한 자세한 내용은 리소스 표현 및 속성 목록을 참조하세요.

메소드 HTTP 요청 설명
https://www.googleapis.com/youtube/v3의 상대 URI
list GET /search API 요청에 지정된 쿼리 매개변수와 일치하는 검색 결과의 모음을 반환합니다. 기본적으로 검색 결과의 집합은 쿼리 매개변수와 일치하는 video, channel, playlist 리소스를 식별하지만, 특정 유형의 리소스만 검색하도록 쿼리를 구성할 수도 있습니다.

subscriptions

subscription 리소스에는 YouTube 사용자의 구독정보가 포함되어 있습니다. 구독정보는 채널에 새 동영상이 추가되거나 다른 사용자가 YouTube에서 동영상 업로드, 동영상 평가 또는 동영상 추천 등의 작업 중 하나를 수행할 때 이를 알려줍니다.

이 리소스에 대한 자세한 내용은 리소스 표현 및 속성 목록을 참조하세요.

메소드 HTTP 요청 설명
https://www.googleapis.com/youtube/v3의 상대 URI
delete DELETE /subscriptions 구독정보를 삭제합니다.
insert POST /subscriptions 인증된 사용자 채널에 대한 구독정보를 추가합니다.
list GET /subscriptions API 요청 기준과 일치하는 구독정보 리소스를 반환합니다.

thumbnails

thumbnail 리소스는 하나의 리소스에 연결된 미리보기 이미지의 서로 다른 크기를 확인합니다. 미리보기 이미지의 특징은 다음과 같습니다.

  • 리소스의 snippet.thumbnails 속성은 해당 리소스에서 사용할 수 있는 미리보기 이미지를 식별하는 개체입니다.
  • thumbnail 리소스에는 일련의 개체가 포함되어 있습니다. 각 개체의 이름(default, medium, high 등)은 미리보기 이미지의 크기를 나타냅니다.
  • 다양한 유형의 리소스를 통해 미리보기 이미지의 다양한 크기를 지원할 수 있습니다.
  • 다양한 유형의 리소스를 통해 동일한 이름을 가진 미리보기 이미지의 크기를 서로 다르게 정의할 수 있습니다. 예를 들어 video 리소스의 default 미리보기 이미지는 보통 120x90픽셀이며, channel 리소스의 default 미리보기 이미지는 보통 88x88픽셀입니다.
  • 미리보기 이미지의 크기는 리소스 유형이 동일하더라도 원본 이미지 또는 YouTube에 업로드된 콘텐츠의 해상도에 따라 달라질 수 있습니다. 예를 들어 HD 동영상은 HD가 아닌 동영상보다 더 높은 해상도의 미리보기 이미지를 지원할 수 있습니다.
  • 미리보기 이미지의 크기 정보가 포함된 개체에는 width 속성과 height 속성이 있습니다. 하지만 해당 이미지의 width와 height 속성은 반환되지 않을 수도 있습니다.
  • 업로드된 미리보기 이미지가 필요한 크기와 일치하지 않는 경우 이미지가 올바른 크기에 맞춰 조정되며 가로세로 비율도 그대로 유지됩니다. 이미지가 잘리지는 않으나 올바른 크기로 맞추기 위해 이미지에 검은색 띠가 포함될 수 있습니다.

이 리소스에 대한 자세한 내용은 리소스 표현 및 속성 목록을 참조하세요.

메소드 HTTP 요청 설명
https://www.googleapis.com/youtube/v3의 상대 URI
set POST /thumbnails/set YouTube에 맞춤 동영상 미리보기 이미지를 업로드하고 이를 동영상에 설정합니다.

videoCategories

videoCategory 리소스는 업로드된 동영상과 연결되었거나 연결할 수 있는 카테고리를 확인합니다.

이 리소스에 대한 자세한 내용은 리소스 표현 및 속성 목록을 참조하세요.

메소드 HTTP 요청 설명
https://www.googleapis.com/youtube/v3의 상대 URI
list GET /videoCategories YouTube 동영상과 연결할 수 있는 카테고리의 목록을 반환합니다.

videos

video 리소스는 YouTube 동영상을 나타냅니다.

이 리소스에 대한 자세한 내용은 리소스 표현 및 속성 목록을 참조하세요.

메소드 HTTP 요청 설명
https://www.googleapis.com/youtube/v3의 상대 URI
insert POST /videos YouTube에 동영상을 업로드하고 동영상의 메타데이터를 선택적으로 설정합니다.
list GET /videos API 요청 매개변수와 일치하는 동영상의 목록을 반환합니다.
delete DELETE /videos YouTube 동영상을 삭제합니다.
update PUT /videos 동영상의 메타데이터를 업데이트합니다.
rate POST /videos/rate 동영상에 좋아요 또는 싫어요 평가를 추가하거나 이러한 평가를 삭제합니다.
getRating GET /videos/getRating 지정된 동영상의 목록에 대해 인증된 사용자가 적용한 평가를 검색합니다.