API Reference | YouTube Data API - Google Developers

The YouTube Data API lets you incorporate functions normally executed on the YouTube website into your own website or application. YouTube DataAPI English BahasaIndonesia Deutsch Español Français Português–Brasil Русский 中文–简体 日本語 한국어 Signin Home Guides Reference Samples Support YouTube DataAPI Home Guides Reference Samples Support Overview Activities Overviewlistinsert Captions Overviewlistinsertupdatedownloaddelete ChannelBanners Overviewinsert Channels Overviewlistupdate ChannelSections Overviewlistinsertupdatedelete Comments OverviewlistinsertupdatemarkAsSpamsetModerationStatusdelete CommentThreads Overviewlistinsert i18nLanguages Overviewlist i18nRegions Overviewlist Members Overviewlist MembershipsLevels Overviewlist PlaylistItems Overviewlistinsertupdatedelete Playlists Overviewlistinsertupdatedelete Search Overviewlist Subscriptions Overviewlistinsertdelete Thumbnails Overviewset VideoAbuseReportReasons Overviewlist VideoCategories Overviewlist Videos OverviewlistinsertupdaterategetRatingreportAbusedelete Watermarks Overviewsetunset GuideCategories Overviewlist StandardQueryParameters YouTubeDataAPIErrors OverviewGlobalDomainErrors Home Products YouTube DataAPI Reference APIReference TheYouTubeDataAPIletsyouincorporatefunctionsnormallyexecutedontheYouTubewebsiteintoyourownwebsiteorapplication.ThelistsbelowidentifythedifferenttypesofresourcesthatyoucanretrieveusingtheAPI.TheAPIalsosupportsmethodstoinsert,update,ordeletemanyoftheseresources. ThisreferenceguideexplainshowtousetheAPItoperformalloftheseoperations.Theguideisorganizedbyresourcetype.AresourcerepresentsatypeofitemthatcomprisespartoftheYouTubeexperience,suchasavideo,aplaylist,orasubscription.Foreachresourcetype,theguidelistsoneormoredatarepresentations,andresourcesarerepresentedasJSONobjects.Theguidealsolistsoneormoresupportedmethods(LIST,POST,DELETE,etc.)foreachresourcetypeandexplainshowtousethosemethodsinyourapplication. CallingtheAPI ThefollowingrequirementsapplytoYouTubeDataAPIrequests: EveryrequestmusteitherspecifyanAPIkey(withthekeyparameter)orprovideanOAuth 2.0token.YourAPIkeyisavailableintheDeveloperConsole'sAPIAccesspaneforyourproject. Youmustsendanauthorizationtokenforeveryinsert,update,anddeleterequest.Youmustalsosendanauthorizationtokenforanyrequestthatretrievestheauthenticateduser'sprivatedata. Inaddition,someAPImethodsforretrievingresourcesmaysupportparametersthatrequireauthorizationormaycontainadditionalmetadatawhenrequestsareauthorized.Forexample,arequesttoretrieveauser'suploadedvideosmayalsocontainprivatevideosiftherequestisauthorizedbythatspecificuser. TheAPIsupportstheOAuth2.0authenticationprotocol.YoucanprovideanOAuth 2.0tokenineitherofthefollowingways: Usetheaccess_tokenqueryparameterlikethis:?access_token=oauth2-token UsetheHTTPAuthorizationheaderlikethis:Authorization:Beareroauth2-token CompleteinstructionsforimplementingOAuth2.0authenticationinyourapplicationcanbefoundintheauthenticationguide. Resourcetypes Activities Anactivityresourcecontainsinformationaboutanactionthataparticularchannel,oruser,hastakenonYouTube.Theactionsreportedinactivityfeedsincluderatingavideo,sharingavideo,markingavideoasafavorite,uploadingavideo,andsoforth.Eachactivityresourceidentifiesthetypeofaction,thechannelassociatedwiththeaction,andtheresource(s)associatedwiththeaction,suchasthevideothatwasratedoruploaded. Formoreinformationaboutthisresource,seeitsresourcerepresentationandlistofproperties. Method HTTPrequest Description URIsrelativetohttps://www.googleapis.com/youtube/v3 list GET /activities Returnsalistofchannelactivityeventsthatmatchtherequestcriteria.Forexample,youcanretrieveeventsassociatedwithaparticularchannelorwiththeuser'sownchannel. insert POST /activities Note:Thismethodhasbeendeprecatedandisnolonger supported. Captions AcaptionresourcerepresentsaYouTubecaptiontrack.AcaptiontrackisassociatedwithexactlyoneYouTubevideo. Formoreinformationaboutthisresource,seeitsresourcerepresentationandlistofproperties. Method HTTPrequest Description URIsrelativetohttps://www.googleapis.com/youtube/v3 delete DELETE /captions Deletesthespecifiedcaptiontrack. download GET /captions/id Downloadsacaptiontrack.Thecaptiontrackisreturnedinitsoriginalformatunlesstherequestspecifiesavalueforthetfmtparameterandinitsoriginallanguageunlesstherequestspecifiesavalueforthetlangparameter. insert POST /captions Uploadsacaptiontrack. list GET /captions Returnsalistofcaptiontracksthatareassociatedwithaspecifiedvideo.NotethattheAPIresponsedoesnotcontaintheactualcaptionsandthatthecaptions.downloadmethodprovidestheabilitytoretrieveacaptiontrack. update PUT /captions Updatesacaptiontrack.Whenupdatingacaptiontrack,youcanchangethetrack'sdraftstatus,uploadanewcaptionfileforthetrack,orboth. ChannelBanners AchannelBannerresourcecontainstheURLthatyouwouldusetosetanewlyuploadedimageasthebannerimageforachannel. Formoreinformationaboutthisresource,seeitsresourcerepresentationandlistofproperties. Method HTTPrequest Description URIsrelativetohttps://www.googleapis.com/youtube/v3 insert POST /channelBanners/insert UploadsachannelbannerimagetoYouTube.Thismethodrepresentsthefirsttwostepsinathree-stepprocesstoupdatethebannerimageforachannel:CallthechannelBanners.insertmethodtouploadthebinaryimagedatatoYouTube.Theimagemusthavea16:9aspectratioandbeatleast2048x1152pixels.Werecommenduploadinga2560pxby1440pximage.Extracttheurlproperty'svaluefromtheresponsethattheAPIreturnsforstep1.Callthechannels.updatemethodtoupdatethechannel'sbrandingsettings.SetthebrandingSettings.image.bannerExternalUrlproperty'svaluetotheURLobtainedinstep2. ChannelSections AchannelSectionresourcecontainsinformationaboutasetofvideosthatachannelhaschosentofeature.Forexample,asectioncouldfeatureachannel'slatestuploads,mostpopularuploads,orvideosfromoneormoreplaylists.Notethatachannel'ssectionsareonlyvisibleifthechanneldisplayscontentinabrowseview(ratherthanafeedview).Toenableachanneltodisplaycontentinabrowseview,setthebrandingSettings.channel.showBrowseViewpropertytotrueforthespecifiedchannel.Achannelcancreateamaximumof10shelves. Formoreinformationaboutthisresource,seeitsresourcerepresentationandlistofproperties. Method HTTPrequest Description URIsrelativetohttps://www.googleapis.com/youtube/v3 delete DELETE /channelSections Deletesachannelsection. insert POST /channelSections Addsachannelsectiontotheauthenticateduser'schannel.Achannelcancreateamaximumof10shelves. list GET /channelSections ReturnsalistofchannelSectionresourcesthatmatchtheAPIrequestcriteria. update PUT /channelSections Updatesachannelsection. Channels AchannelresourcecontainsinformationaboutaYouTubechannel. Formoreinformationaboutthisresource,seeitsresourcerepresentationandlistofproperties. Method HTTPrequest Description URIsrelativetohttps://www.googleapis.com/youtube/v3 list GET /channels Returnsacollectionofzeroormorechannelresourcesthatmatchtherequestcriteria. update PUT /channels Updatesachannel'smetadata.Notethatthismethodcurrentlyonlysupportsupdatestothechannelresource'sbrandingSettingsandinvideoPromotionobjectsandtheirchildproperties. CommentThreads AcommentThreadresourcecontainsinformationaboutaYouTubecommentthread,whichcomprisesatop-levelcommentandreplies,ifanyexist,tothatcomment.AcommentThreadresourcecanrepresentcommentsabouteitheravideoorachannel.Boththetop-levelcommentandtherepliesareactuallycommentresourcesnestedinsidethecommentThreadresource.ThecommentThreadresourcedoesnotnecessarilycontainallrepliestoacomment,andyouneedtousethecomments.listmethodifyouwanttoretrieveallrepliesforaparticularcomment.Alsonotethatsomecommentsdonothavereplies. Formoreinformationaboutthisresource,seeitsresourcerepresentationandlistofproperties. Method HTTPrequest Description URIsrelativetohttps://www.googleapis.com/youtube/v3 list GET /commentThreads ReturnsalistofcommentthreadsthatmatchtheAPIrequestparameters. insert POST /commentThreads Createsanewtop-levelcomment.Toaddareplytoanexistingcomment,usethecomments.insertmethodinstead. Comments AcommentresourcecontainsinformationaboutasingleYouTubecomment.Acommentresourcecanrepresentacommentabouteitheravideoorachannel.Inaddition,thecommentcouldbeatop-levelcommentorareplytoatop-levelcomment. Formoreinformationaboutthisresource,seeitsresourcerepresentationandlistofproperties. Method HTTPrequest Description URIsrelativetohttps://www.googleapis.com/youtube/v3 list GET /comments ReturnsalistofcommentsthatmatchtheAPIrequestparameters. setModerationStatus POST /comments/setModerationStatus Setsthemoderationstatusofoneormorecomments.TheAPIrequestmustbeauthorizedbytheownerofthechannelorvideoassociatedwiththecomments. insert POST /comments Createsareplytoanexistingcomment.Note:Tocreateatop-levelcomment,usethecommentThreads.insertmethod. markAsSpam POST /comments/markAsSpam Expressesthecaller'sopinionthatoneormorecommentsshouldbeflaggedasspam. delete DELETE /comments Deletesacomment. update PUT /comments Modifiesacomment. GuideCategories AguideCategoryresourceidentifiesacategorythatYouTubealgorithmicallyassignsbasedonachannel'scontentorotherindicators,suchasthechannel'spopularity.Thelistissimilartovideocategories,withthedifferencebeingthatavideo'suploadercanassignavideocategorybutonlyYouTubecanassignachannelcategory. Formoreinformationaboutthisresource,seeitsresourcerepresentationandlistofproperties. Method HTTPrequest Description URIsrelativetohttps://www.googleapis.com/youtube/v3 list GET /guideCategories ReturnsalistofcategoriesthatcanbeassociatedwithYouTubechannels. I18nLanguages Ani18nLanguageresourceidentifiesanapplicationlanguagethattheYouTubewebsitesupports.TheapplicationlanguagecanalsobereferredtoasaUIlanguage.FortheYouTubewebsite,anapplicationlanguagecouldbeautomaticallyselectedbasedonGoogleAccountsettings,browserlanguage,orIPlocation.AusercouldalsomanuallyselectthedesiredUIlanguagefromtheYouTubesitefooter.Eachi18nLanguageresourceidentifiesalanguagecodeandaname.ThelanguagecodecanbeusedasthevalueofthehlparameterwhencallingAPImethodslikevideoCategories.listandguideCategories.list. Formoreinformationaboutthisresource,seeitsresourcerepresentationandlistofproperties. Method HTTPrequest Description URIsrelativetohttps://www.googleapis.com/youtube/v3 list GET /i18nLanguages ReturnsalistofapplicationlanguagesthattheYouTubewebsitesupports. I18nRegions Ani18nRegionresourceidentifiesageographicareathataYouTubeusercanselectasthepreferredcontentregion.Thecontentregioncanalsobereferredtoasacontentlocale.FortheYouTubewebsite,acontentregioncouldbeautomaticallyselectedbasedonheuristicsliketheYouTubedomainortheuser'sIPlocation.AusercouldalsomanuallyselectthedesiredcontentregionfromtheYouTubesitefooter.Eachi18nRegionresourceidentifiesaregioncodeandaname.TheregioncodecanbeusedasthevalueoftheregionCodeparameterwhencallingAPImethodslikesearch.list,videos.list,activities.list,andvideoCategories.list. Formoreinformationaboutthisresource,seeitsresourcerepresentationandlistofproperties. Method HTTPrequest Description URIsrelativetohttps://www.googleapis.com/youtube/v3 list GET /i18nRegions ReturnsalistofcontentregionsthattheYouTubewebsitesupports. Members AmemberresourcerepresentsachannelmemberforaYouTube channel.Amemberprovidesrecurringmonetarysupporttoacreatorandreceivesspecial benefits.Forexample,membersareabletochatwhenthecreatorturnsonmembers-onlymodefor achat. Formoreinformationaboutthisresource,seeits resourcerepresentationandlistof properties. Method HTTPrequest Description URIsrelativetohttps://www.googleapis.com/youtube/v3 list GET /members Listsmembers(formerlyknownas"sponsors")forachannel.TheAPIrequestmustbe authorizedbythechannelowner. MembershipsLevels AmembershipsLevelresourceidentifiesapricinglevelforthe creatorthatauthorizedtheAPIrequest. Formoreinformationaboutthisresource,seeits resourcerepresentationandlistof properties. Method HTTPrequest Description URIsrelativetohttps://www.googleapis.com/youtube/v3 list GET /membershipsLevels ReturnsacollectionofzeroormoremembershipsLevel resourcesownedbythechannelthatauthorizedtheAPIrequest.Levelsarereturnedin implicitdisplayorder. PlaylistItems AplaylistItemresourceidentifiesanotherresource,suchasa video,thatisincludedinaplaylist.Inaddition,theplaylistItemresource containsdetailsabouttheincludedresourcethatpertainspecificallytohowthatresource isusedinthatplaylist. YouTubealsousesaplaylisttoidentifyachannel'slistofuploadedvideos,witheach playlistIteminthatlistrepresentingoneuploadedvideo.Youcanretrievethe playlistIDforthatlistfromthechannelresource foragivenchannel.Youcanthenusethe playlistItems.listmethodtothe list. Formoreinformationaboutthisresource,seeitsresourcerepresentationandlistofproperties. Method HTTPrequest Description URIsrelativetohttps://www.googleapis.com/youtube/v3 delete DELETE /playlistItems Deletesaplaylistitem. insert POST /playlistItems Addsaresourcetoaplaylist. list GET /playlistItems ReturnsacollectionofplaylistitemsthatmatchtheAPIrequestparameters.YoucanretrievealloftheplaylistitemsinaspecifiedplaylistorretrieveoneormoreplaylistitemsbytheiruniqueIDs. update PUT /playlistItems Modifiesaplaylistitem.Forexample,youcouldupdatetheitem'spositionintheplaylist. Playlists AplaylistresourcerepresentsaYouTubeplaylist.Aplaylistisacollectionofvideosthatcanbeviewedsequentiallyandsharedwithotherusers.Aplaylistcancontainupto200videos,andYouTubedoesnotlimitthenumberofplayliststhateachusercreates.Bydefault,playlistsarepubliclyvisibletootherusers,butplaylistscanbepublicorprivate.YouTubealsousesplayliststoidentifyspecialcollectionsofvideosforachannel,suchas:uploadedvideospositivelyrated(liked)videoswatchhistorywatchlaterTobemorespecific,theselistsareassociatedwithachannel,whichisacollectionofaperson,group,orcompany'svideos,playlists,andotherYouTubeinformation.YoucanretrievetheplaylistIDsforeachoftheselistsfromthechannelresourceforagivenchannel.YoucanthenusetheplaylistItems.listmethodtoretrieveanyofthoselists.YoucanalsoaddorremoveitemsfromthoselistsbycallingtheplaylistItems.insertandplaylistItems.deletemethods. Formoreinformationaboutthisresource,seeitsresourcerepresentationandlistofproperties. Method HTTPrequest Description URIsrelativetohttps://www.googleapis.com/youtube/v3 delete DELETE /playlists Deletesaplaylist. list GET /playlists ReturnsacollectionofplayliststhatmatchtheAPIrequestparameters.Forexample,youcanretrieveallplayliststhattheauthenticateduserowns,oryoucanretrieveoneormoreplaylistsbytheiruniqueIDs. insert POST /playlists Createsaplaylist. update PUT /playlists Modifiesaplaylist.Forexample,youcouldchangeaplaylist'stitle,description,orprivacystatus. Search AsearchresultcontainsinformationaboutaYouTubevideo,channel,orplaylistthatmatchesthesearchparametersspecifiedinanAPIrequest.Whileasearchresultpointstoauniquelyidentifiableresource,likeavideo,itdoesnothaveitsownpersistentdata. Formoreinformationaboutthisresource,seeitsresourcerepresentationandlistofproperties. Method HTTPrequest Description URIsrelativetohttps://www.googleapis.com/youtube/v3 list GET /search ReturnsacollectionofsearchresultsthatmatchthequeryparametersspecifiedintheAPIrequest.Bydefault,asearchresultsetidentifiesmatchingvideo,channel,andplaylistresources,butyoucanalsoconfigurequeriestoonlyretrieveaspecifictypeofresource. Subscriptions AsubscriptionresourcecontainsinformationaboutaYouTubeusersubscription.AsubscriptionnotifiesauserwhennewvideosareaddedtoachannelorwhenanotherusertakesoneofseveralactionsonYouTube,suchasuploadingavideo,ratingavideo,orcommentingonavideo. Formoreinformationaboutthisresource,seeitsresourcerepresentationandlistofproperties. Method HTTPrequest Description URIsrelativetohttps://www.googleapis.com/youtube/v3 delete DELETE /subscriptions Deletesasubscription. insert POST /subscriptions Addsasubscriptionfortheauthenticateduser'schannel. list GET /subscriptions ReturnssubscriptionresourcesthatmatchtheAPIrequestcriteria. Thumbnails Athumbnailresourceidentifiesdifferentthumbnailimagesizesassociatedwitharesource.Pleasenotethefollowingcharacteristicsofthumbnailimages:Aresource'ssnippet.thumbnailspropertyisanobjectthatidentifiesthethumbnailimagesavailableforthatresource.Athumbnailresourcecontainsaseriesofobjects.Thenameofeachobject(default,medium,high,etc.)referstothethumbnailimagesize.Differenttypesofresourcesmaysupportdifferentthumbnailimagesizes.Differenttypesofresourcesmaydefinedifferentsizesforthumbnailimageswiththesamename.Forexample,thedefaultthumbnailimageforavideoresourceistypically120pxby90px,andthedefaultthumbnailimageforachannelresourceistypically88pxby88px.ResourcesofthesametypemaystillhavedifferentthumbnailimagesizesforcertainimagesdependingontheresolutionoftheoriginalimageorcontentuploadedtoYouTube.Forexample,anHDvideomaysupporthigherresolutionthumbnailsthannon-HDvideos.Eachobjectthatcontainsinformationaboutathumbnailimagesizehasawidthpropertyandaheightproperty.However,thewidthandheightpropertiesmaynotbereturnedforthatimage.Ifanuploadedthumbnailimagedoesnotmatchtherequireddimensions,theimageisresizedtomatchthecorrectsizewithoutchangingitsaspectratio.Theimageisnotcropped,butmayincludeblackbarssothatthesizeiscorrect. Formoreinformationaboutthisresource,seeitsresourcerepresentationandlistofproperties. Method HTTPrequest Description URIsrelativetohttps://www.googleapis.com/youtube/v3 set POST /thumbnails/set UploadsacustomvideothumbnailtoYouTubeandsetsitforavideo. VideoAbuseReportReasons AvideoAbuseReportReasonresourcecontainsinformationaboutareasonthatavideowouldbeflaggedforcontainingabusivecontent.Whenyourapplicationcallsthevideos.reportAbusemethodtoreportanabusivevideo,therequestusestheinformationfromavideoAbuseReportReasonresourcetoidentifythereasonthatthevideoisbeingreported. Formoreinformationaboutthisresource,seeitsresourcerepresentationandlistofproperties. Method HTTPrequest Description URIsrelativetohttps://www.googleapis.com/youtube/v3 list GET /videoAbuseReportReasons Retrievealistofreasonsthatcanbeusedtoreportabusivevideos. VideoCategories AvideoCategoryresourceidentifiesacategorythathasbeenorcouldbeassociatedwithuploadedvideos. Formoreinformationaboutthisresource,seeitsresourcerepresentationandlistofproperties. Method HTTPrequest Description URIsrelativetohttps://www.googleapis.com/youtube/v3 list GET /videoCategories ReturnsalistofcategoriesthatcanbeassociatedwithYouTubevideos. Videos AvideoresourcerepresentsaYouTubevideo. Formoreinformationaboutthisresource,seeitsresourcerepresentationandlistofproperties. Method HTTPrequest Description URIsrelativetohttps://www.googleapis.com/youtube/v3 insert POST /videos UploadsavideotoYouTubeandoptionallysetsthevideo'smetadata. list GET /videos ReturnsalistofvideosthatmatchtheAPIrequestparameters. delete DELETE /videos DeletesaYouTubevideo. update PUT /videos Updatesavideo'smetadata. rate POST /videos/rate Addalikeordislikeratingtoavideoorremovearatingfromavideo. getRating GET /videos/getRating Retrievestheratingsthattheauthorizedusergavetoalistofspecifiedvideos. reportAbuse POST /videos/reportAbuse Reportavideoforcontainingabusivecontent. Watermarks Awatermarkresourceidentifiesanimagethatdisplaysduringplaybacksofaspecifiedchannel'svideos.Youcanalsospecifyatargetchanneltowhichtheimagewilllinkaswellastimingdetailsthatdeterminewhenthewatermarkappearsduringvideoplaybacksandthelengthoftimeitisvisible. Formoreinformationaboutthisresource,seeitsresourcerepresentationandlistofproperties. Method HTTPrequest Description URIsrelativetohttps://www.googleapis.com/youtube/v3 set POST /watermarks/set UploadsawatermarkimagetoYouTubeandsetsitforachannel. unset POST /watermarks/unset Deletesachannel'swatermarkimage. Exceptasotherwisenoted,thecontentofthispageislicensedundertheCreativeCommonsAttribution4.0License,andcodesamplesarelicensedundertheApache2.0License.Fordetails,seetheGoogleDevelopersSitePolicies.JavaisaregisteredtrademarkofOracleand/oritsaffiliates. Lastupdated2021-07-02UTC. [{ "type":"thumb-down", "id":"missingTheInformationINeed", "label":"MissingtheinformationIneed" },{ "type":"thumb-down", "id":"tooComplicatedTooManySteps", "label":"Toocomplicated/toomanysteps" },{ "type":"thumb-down", "id":"outOfDate", "label":"Outofdate" },{ "type":"thumb-down", "id":"samplesCodeIssue", "label":"Samples/codeissue" },{ "type":"thumb-down", "id":"otherDown", "label":"Other" }] [{ "type":"thumb-up", "id":"easyToUnderstand", "label":"Easytounderstand" },{ "type":"thumb-up", "id":"solvedMyProblem", "label":"Solvedmyproblem" },{ "type":"thumb-up", "id":"otherUp", "label":"Other" }] Blog ThelatestnewsontheYouTubeblog GitHub FindAPIcodesamplesandotherYouTubeopen-sourceprojects. IssueTracker Somethingwrong?Sendusabugreport! StackOverflow Askaquestionundertheyoutube-apitag Videos CheckouttheYouTubeDeveloperRelationsteam'sYouTubechannel Tools GoogleAPIsExplorer YouTubePlayerDemo ConfigureaSubscribeButton IssueTracker Fileabug Requestafeature Seeopenissues ProductInfo TermsofService BrandingGuidelines MonetizationGuidelines APIssubjecttoDeprecationPolicy Android Chrome Firebase GoogleCloudPlatform Allproducts Terms Privacy SignupfortheGoogleDevelopersnewsletter Subscribe English BahasaIndonesia Deutsch Español Français Português–Brasil Русский 中文–简体 日本語 한국어