این صفحه تغییرات YouTube Data API (v3) و بهروزرسانیهای اسناد را فهرست میکند. در این تغییرات ثبت نام کنید .
13 مارس 2024
توجه: این یک اعلامیه منسوخ شدن است.
این به روز رسانی شامل تغییرات زیر است:
پارامتر sync
برای روشهای captions.insert
و captions.update
منسوخ شده است. YouTube از ۱۲ آوریل ۲۰۲۴ پشتیبانی از این پارامتر را متوقف خواهد کرد.
در نتیجه این تغییر، برنامهنویسان باید هنگام درج یا بهروزرسانی تراکهای شرح، اطلاعات زمانبندی را درج کنند وگرنه آپلود با شکست مواجه میشود.
12 مارس 2024
این به روز رسانی شامل تغییرات زیر است:
اسناد منبع captions
به روز شده است تا توجه داشته باشید که حداکثر طول مجاز برای فیلد snippet.name
150 کاراکتر است. اگر نام آهنگ طولانیتر از آن باشد، API یک خطای nameTooLong
را برمیگرداند.
7 مارس 2024
توجه: این یک اعلامیه منسوخ شدن است.
ویژگی منبع channel
brandingSettings.channel.moderateComments
منسوخ شده است. YouTube از ۷ مارس ۲۰۲۴ پشتیبانی از این پارامتر را متوقف خواهد کرد.
31 ژانویه 2024
این به روز رسانی شامل تغییرات زیر است:
پارامتر جدید forHandle
روش channels.list
شما را قادر می سازد تا اطلاعات یک کانال را با تعیین دسته YouTube آن بازیابی کنید.
9 نوامبر 2023
همه ارجاعها به منبع videoId
در زیر Comments
حذف شدهاند زیرا منبع videoId
با استفاده از تماس API بازگردانده نمیشود.
12 سپتامبر 2023
توجه: این یک اعلامیه منسوخ شدن است.
روش comments.markAsSpam
چندین سال است که منسوخ شده است. این روش قبلاً در YouTube پشتیبانی نمیشود و دیگر از طریق API پشتیبانی نمیشود.
یک اخطار منسوخ شدن به همه اسنادی که به روش comments.markAsSpam
ارجاع میدهند اضافه شده است.
22 اوت 2023
اکنون روش search.list
از پارامتر videoPaidProductPlacement
پشتیبانی می کند. این پارامتر به شما امکان میدهد نتایج جستجو را فیلتر کنید تا فقط ویدیوهایی را که سازنده آنها را دارای تبلیغات پولی معرفی کرده است، شامل شود.
18 آگوست 2023
تعریف liveStreamingDetails.concurrentViewers
منبع video
بهروزرسانی شده است تا توجه داشته باشد که بیننده همزمان حساب میکند که YouTube Data API برمیگرداند ممکن است با تعداد بینندگان همزمان پردازششده و ناخواسته موجود در YouTube Analytics متفاوت باشد. مرکز راهنمایی YouTube اطلاعات بیشتری درباره معیارهای پخش زنده ارائه می دهد.
7 آگوست 2023
همانطور که در 12 ژوئن 2023 اعلام شد ، پارامتر relatedToVideoId
روش search.list
منسوخ شده است. آن پارامتر دیگر پشتیبانی نمی شود و ارجاعات به پارامتر از اسناد API حذف شده است.
28 ژوئن 2023
روش thumbnails.set اکنون از خطای uploadRateLimitExceeded
پشتیبانی میکند، که نشان میدهد کانال در 24 ساعت گذشته تصاویر کوچک زیادی را آپلود کرده است و باید بعداً دوباره امتحان کنید.
12 ژوئن 2023
توجه: این یک اعلامیه منسوخ شدن است.
پارامتر relatedToVideoId
روش search.list منسوخ شده است. YouTube از ۷ اوت ۲۰۲۳ پشتیبانی از این پارامتر را متوقف خواهد کرد.
در حال حاضر، یک اخطار منسوخ شدن به مستندات روش search.list
اضافه شده است. این پارامتر در تاریخ 7 اوت 2023 یا پس از آن به طور کامل از اسناد search.list
حذف خواهد شد.
علاوه بر این، نمونهای که نحوه بازیابی ویدیوهای مرتبط را نشان میدهد از راهنمای اجرای API حذف شده است.
22 اوت 2022
یادداشتهای نوع تصحیح شده برای فیلدهای video.statistics به رشتههایی از طولانی بدون امضا.
5 آگوست 2022
YouTube نحوه تولید شناسههای شرح را تغییر داده است و به عنوان بخشی از این تغییر، شناسههای زیرنویس جدید را به همه آهنگهای زیرنویس اختصاص میدهد. این تغییر ممکن است برای برنامههایی که مقادیر caption_id
را ذخیره میکنند یک تغییر ناسازگار با عقب باشد، اگرچه روی برنامههایی که مقادیر caption_id
را ذخیره نمیکنند تأثیری نخواهد داشت.
از هماکنون تا اول دسامبر 2022، روشهای captions.list
، captions.update
، captions.download
و و captions.delete
از شناسههای تراک شرح قدیمی و جدید پشتیبانی میکنند. با این حال، در تاریخ 1 دسامبر 2022 یا پس از آن، YouTube از شناسههای تراک شرح قدیمی پشتیبانی نخواهد کرد. در آن زمان، فراخوانی هر یک از آن متدهای API با شناسه تراک عنوان قدیمی منجر به خطای captionNotFound
میشود.
برای آماده شدن برای این تغییر، باید برنامهریزی کنید که همه دادههای ذخیره شده آهنگ زیرنویس را از هماکنون تا 1 دسامبر 2022 جایگزین کنید. این بدان معناست که برای هر ویدیویی که دادههای آهنگ شرح را برای آن ذخیره میکنید، باید دادههای ذخیرهشده فعلی را حذف کنید، سپس با روش captions.list
برای بازیابی مجموعه فعلی از آهنگهای زیرنویس برای ویدیو و ذخیره دادهها در پاسخ API همانطور که معمولاً انجام میدهید.
12 جولای 2022
شرایط خدمات YouTube API Services به روز شده است. لطفاً برای اطلاعات بیشتر به شرایط خدمات YouTube API Services - Revision History مراجعه کنید.
27 آوریل 2022
توضیحات روش videos.insert
بهروزرسانی شده است تا توجه داشته باشید که حداکثر اندازه فایل برای ویدیوهای آپلود شده از 128 گیگابایت به 256 گیگابایت افزایش یافته است.
8 آوریل 2022
تعاریف پارامتر myRecentSubscribers
و mySubscribers
روش subscriptions.list
هر دو بهروزرسانی شدهاند تا توجه داشته باشیم که حداکثر تعداد مشترکینی که توسط API بازگردانده میشوند ممکن است محدود باشد. این تغییر نشان دهنده یک تصحیح مستندات است و نه تغییر در رفتار API.
15 دسامبر 2021
همانطور که در 18 نوامبر 2021 اعلام شد، همراه با تغییراتی برای خصوصی کردن تعداد عدم پسندیدن ویدیو در کل پلتفرم YouTube ، ویژگی statistics.dislikeCount
منبع video
اکنون خصوصی است.
میتوانید در وبلاگ رسمی YouTube درباره این تغییر اطلاعات بیشتری کسب کنید.
18 نوامبر 2021
در ارتباط با تغییراتی که برای خصوصی کردن شمارش نپسندیدن ویدیو در کل پلتفرم YouTube انجام میشود ، ویژگی statistics.dislikeCount
منبع video
از 13 دسامبر 2021 خصوصی میشود. به این معنی که این ویژگی فقط در پاسخ API از videos.list
گنجانده میشود. اگر درخواست API توسط مالک ویدیو تأیید شده باشد، videos.list
.
نقطه پایانی videos.rate
تحت تأثیر این تغییر قرار نمیگیرد.
توسعه دهندگانی که تعداد نپسندیدن را به صورت عمومی نمایش نمی دهند و همچنان به تعداد عدم پسندیدن برای مشتری API خود نیاز دارند، می توانند برای قرار گرفتن در لیست مجاز برای معافیت درخواست دهند. برای درخواست معافیت، باید این فرم درخواست را تکمیل کنید.
میتوانید در وبلاگ رسمی YouTube درباره این تغییر اطلاعات بیشتری کسب کنید.
2 ژوئیه 2021
توجه: این یک اعلامیه منسوخ شدن است.
نقطه پایانی commentThreads.update
منسوخ شده است و دیگر پشتیبانی نمی شود. این قابلیت تکراری نقطه پایانی از طریق سایر نقاط پایانی API در دسترس است. در عوض، می توانید با comments.update
تماس بگیرید
commentThreads
نیاز دارد، یک فراخوان ثانویه با متد commentThreads.list
برقرار کنید. 1 ژوئیه 2021
همه برنامهنویسهایی که از سرویسهای API YouTube استفاده میکنند، باید یک حسابرسی انطباق با API انجام دهند تا بیش از سهمیه پیشفرض 10000 واحد به آنها اعطا شود. تا به امروز، هم فرآیند حسابرسی انطباق و هم درخواستها برای تخصیص واحدهای سهمیه اضافی توسط توسعهدهندگانی که خدمات YouTube API را پر کرده و ارسال میکنند - فرم تمدید حسابرسی و سهمیه انجام شده است.
برای شفاف سازی این فرآیندها و پاسخگویی بهتر به نیازهای توسعه دهندگان با استفاده از خدمات API ما، سه فرم جدید و راهنمای تکمیل آن فرم ها را اضافه می کنیم:
- فرم درخواستهای توسعهدهنده حسابرسی شده : برنامهنویسانی که قبلاً یک حسابرسی انطباق API را گذراندهاند، میتوانند این فرم کوتاهتر را برای درخواست تمدید سهمیه اختصاصیافته پر کرده و ارسال کنند.
- فرم درخواست تجدیدنظر : توسعه دهندگانی که پروژه های API آنها در ممیزی انطباق شکست خورده است (یا از افزایش سهمیه رد شده اند) می توانند این فرم را پر کرده و ارسال کنند.
- تغییر فرم کنترل : توسعهدهندگان یا هر طرفی که از طرف یک توسعهدهنده یک کلاینت API را اجرا میکند، که با تغییر کنترل (مثلاً از طریق خرید یا فروش سهام، ادغام یا سایر شکلهای تراکنش شرکتی) مرتبط با یک پروژه API، تجربه میکنند. این فرم را پر کرده و ارسال کنید این به تیم API YouTube امکان میدهد سوابق ما را بهروزرسانی کند، مطابقت موارد استفاده پروژه جدید API را بررسی کند و سهمیه فعلی توسعهدهنده را تأیید کند.
هر فرم جدید ما را از استفاده مورد نظر شما از API YouTube آگاه می کند و به ما امکان می دهد بهتر به شما کمک کنیم.
جزئیات بیشتر در راهنمای حسابرسی انطباق API جدید ما موجود است.
12 مه 2021
توجه: این یک اعلامیه منسوخ شدن است.
این به روز رسانی تغییرات API زیر را پوشش می دهد:
ویژگی
contentDetails.relatedPlaylists.favorites
منبعchannel
منسوخ شده است. عملکرد ویدیوهای مورد علاقه قبلاً برای چندین سال منسوخ شده است همانطور که در ورودی تاریخچه بازبینی در 28 آوریل 2016 ذکر شد.قبل از این بهروزرسانی، اگر یک کلاینت API بخواهد ویدیویی را به لیست پخش مورد علاقههای موجود اضافه کند، API همچنان یک لیست پخش جدید ایجاد میکند. در ادامه، لیست پخش در این حالت ایجاد نخواهد شد و API خطایی را برمیگرداند. تلاشها برای تغییر فهرستهای پخش دلخواه با افزودن، اصلاح یا حذف موارد نیز همه در اعلانهای قبلی منسوخ شدهاند و ممکن است در هر زمانی شروع به بازگشت خطا کنند.
ویژگی های منبع
channel
زیر منسوخ شده است. این ویژگیها قبلاً در رابط کاربری YouTube Studio و YouTube پشتیبانی نمیشوند. در نتیجه، آنها دیگر از طریق API نیز پشتیبانی نمی شوند.-
brandingSettings.channel.defaultTab
-
brandingSettings.channel.featuredChannelsTitle
-
brandingSettings.channel.featuredChannelsUrls[]
-
brandingSettings.channel.profileColor
-
brandingSettings.channel.showBrowseView
-
brandingSettings.channel.showRelatedChannels
همه ویژگی ها از نمایش منبع
channel
حذف شده اند و تعاریف آنها از لیست ویژگی های منبع حذف شده است. علاوه بر این، خطاهای مرتبط با این ویژگی ها از مستندات روش خاص حذف شده است.-
ویژگی های منبع
channelSection
زیر منسوخ شده است. این ویژگیها قبلاً در رابط کاربری YouTube Studio و YouTube پشتیبانی نمیشوند. در نتیجه، آنها دیگر از طریق API نیز پشتیبانی نمی شوند.-
snippet.style
-
snippet.defaultLanguage
-
snippet.localized.title
-
localizations
-
localizations.(key)
-
localizations.(key).title
-
targeting
-
targeting.languages[]
-
targeting.regions[]
-
targeting.countries[]
در ارتباط با این تغییر، پارامتر
hl
روشchannelSection.list
نیز منسوخ شده است زیرا ویژگی هایی که پشتیبانی می کند پشتیبانی نمی شوند.همه ویژگی ها از نمایش منبع
channelSection
حذف شده اند و تعاریف آنها از لیست ویژگی های منبع حذف شده است. علاوه بر این، خطاهای مرتبط با این ویژگی ها از مستندات روش خاص حذف شده است.-
برای ویژگی
snippet.type
منبعchannelSection
، مقادیر زیر منسوخ شده است. این مقادیر قبلاً در صفحات کانال YouTube پشتیبانی نمیشوند و در نتیجه، دیگر از طریق API نیز پشتیبانی نمیشوند.-
likedPlaylists
-
likes
-
postedPlaylists
-
postedVideos
-
recentActivity
-
recentPosts
-
ویژگی
snippet.tags[]
منبعplaylist
منسوخ شده است. این ویژگی قبلاً در YouTube پشتیبانی نمیشود و در نتیجه، دیگر از طریق API پشتیبانی نمیشود.
9 فوریه 2021
منبع playlistItem
از دو ویژگی جدید پشتیبانی می کند:
- ویژگی
snippet.videoOwnerChannelId
شناسه کانالی را که ویدیوی لیست پخش را آپلود کرده است مشخص می کند. - ویژگی
snippet.videoOwnerChannelTitle
نام کانالی را که ویدیوی لیست پخش را آپلود کرده است مشخص می کند.
28 ژانویه 2021
این به روز رسانی شامل تغییرات زیر است:
روش های
playlistItems.delete
،playlistItems.insert
،playlistItems.list
،playlistItems.update
،playlists.delete
،playlists.list
وplaylists.update
همگی از یک خطایplaylistOperationUnsupported
جدید پشتیبانی می کنند. این خطا زمانی رخ می دهد که یک درخواست تلاش می کند عملیاتی را انجام دهد که برای یک لیست پخش خاص مجاز نیست. به عنوان مثال، کاربر نمی تواند یک ویدیو را از لیست پخش ویدیوهای آپلود شده خود حذف کند یا خود لیست پخش را حذف کند.در همه موارد، این خطا کد پاسخ
400
HTTP (درخواست بد) را برمی گرداند.خطاهای
watchHistoryNotAccessible
وwatchLaterNotAccessible
روشplaylistItems.list
از مستندات حذف شده است. در حالی که تاریخچه تماشای کاربران و لیستهای تماشای بعدی، در واقع از طریق API قابل دسترسی نیستند، این خطاهای خاص توسط API بازگردانده نمیشوند.
15 اکتبر 2020
دو بخش جدید به سیاست های توسعه دهنده اضافه شده است:
- بخش جدید III.E.4.i اطلاعات بیشتری درباره داده های جمع آوری و ارسال شده از طریق پخش کننده تعبیه شده YouTube ارائه می دهد. شما مسئول هر گونه اطلاعات کاربری هستید که از طریق هر پخش کننده جاسازی شده YouTube برای ما ارسال می کنید، قبل از اینکه کاربر با پخش کننده تعامل داشته باشد تا قصد پخش را نشان دهد. با تنظیم پخش خودکار روی نادرست، میتوانید دادههای به اشتراک گذاشته شده با YouTube را قبل از تعامل کاربر با پخشکننده محدود کنید.
- بخش جدید III.E.4.j مربوط به بررسی وضعیت Made for Kids (MFK) محتوا قبل از جاسازی آن در سایت ها و برنامه های شما است. شما مسئول این هستید که بدانید چه زمانی ویدیوهایی که در API Client خود جاسازی میکنید برای کودکان ساخته شدهاند و بر این اساس با دادههای جمعآوریشده از پخشکننده جاسازیشده رفتار کنید. به این ترتیب، باید وضعیت محتوا را با استفاده از YouTube Data API Service قبل از جاسازی آن در API Client از طریق هر پخش کننده جاسازی شده YouTube بررسی کنید.
راهنمای جدید Finding the MadeForKids یک راهنمای ویدیویی نحوه جستجوی وضعیت MFK یک ویدیو را با استفاده از سرویس YouTube Data API توضیح میدهد.
در ارتباط با این تغییرات، یادآوری به مستندات پارامتر پخش کننده جاسازی شده اضافه شده است تا توضیح دهد که اگر پخش خودکار را فعال کنید، پخش بدون هیچ گونه تعامل کاربر با پخش کننده انجام می شود. بنابراین جمعآوری و اشتراکگذاری دادههای پخش پس از بارگیری صفحه انجام میشود.
8 اکتبر 2020
این به روز رسانی سه تغییر کوچک مربوط به منبع channel
را پوشش می دهد:
- شی
snippet.thumbnails
، که تصاویر کوچک کانال را شناسایی می کند، ممکن است برای کانال های تازه ایجاد شده خالی باشد و ممکن است یک روز طول بکشد تا پر شود. - ویژگی
statistics.videoCount
فقط تعداد ویدیوهای عمومی کانال را حتی برای مالکان منعکس می کند. این رفتار با تعداد نشان داده شده در وب سایت YouTube مطابقت دارد. - کلمات کلیدی کانال، که در ویژگی
brandingSettings.channel.keywords
مشخص میشوند، اگر از حداکثر طول مجاز 500 کاراکتر تجاوز کنند یا دارای علامت نقل قول غیرقابل فرار ("
) باشند، ممکن است کوتاه شوند. توجه داشته باشید که محدودیت 500 نویسه برای هر محدودیت کلمه کلیدی بلکه محدودیتی در طول کل کلمات کلیدی است. این رفتار با رفتار وب سایت YouTube مطابقت دارد.
9 سپتامبر 2020
توجه: این یک اعلامیه منسوخ شدن است.
این به روز رسانی تغییرات API زیر را پوشش می دهد. همه تغییرات در تاریخ 9 سپتامبر 2020 یا بعد از این اعلامیه اعمال خواهند شد. با در نظر گرفتن این موضوع، توسعه دهندگان دیگر نباید به هیچ یک از ویژگی های API ذکر شده در زیر اعتماد کنند.
- منابع، روشها، پارامترها و ویژگیهای منبع API زیر فوراً منسوخ شدهاند و در تاریخ یا پس از این اعلامیه کار نمیکنند:
- ویژگی های منبع
channel
زیر:- ویژگی
statistics.commentCount
- شی
brandingSettings.image
و همه ویژگی های فرزند آن - فهرست
brandingSettings.hints
و همه ویژگیهای فرزند آن
- ویژگی
- پارامتر فیلتر
categoryId
روشchannels.list
- منبع
guideCategories
و روشguideCategories.list
- ویژگی های منبع
- اگر درخواست API پارامتر
managedByMe
را رویtrue
تنظیم کند، پاسخهای API برای روشchannels.list
دیگر حاوی ویژگیprevPageToken
نیستند. این تغییر بر ویژگیprevPageToken
برای سایر درخواستهایchannels.list
تأثیر نمیگذارد و برای هیچ درخواستی بر ویژگیnextPageToken
تأثیر نمیگذارد. - ویژگی های
contentDetails.relatedPlaylists.watchLater
وcontentDetails.relatedPlaylists.watchHistory
منبعchannel
هر دو در 11 اوت 2016 منسوخ اعلام شدند. پشتیبانی از روشplaylistItems.insert
وplaylistItems.delete
از این لیستهای پخش نیز اکنون کاملاً منسوخ شده است و این دو ویژگی از اسناد حذف شدهاند. - پارامتر
mySubscribers
روشchannels.list
، که در 30 ژوئیه 2013 منسوخ اعلام شده بود، از اسناد حذف شده است. از روشsubscriptions.list
و پارامترmySubscribers
آن برای بازیابی لیستی از مشترکین کانال کاربر تأیید شده استفاده کنید. - شیء
invideoPromotion
منبعchannel
و همه ویژگیهای فرزند آن، که در 27 نوامبر 2017 منسوخ اعلام شده بودند، از اسناد حذف شدهاند.
29 جولای 2020
با حذف هزینه اضافی مربوط به پارامتر part
، فرآیند خود را برای دریافت سهمیه درخواستهای API ساده کردهایم. بلافاصله اعمال می شود، ما فقط هزینه پایه را برای روشی که فراخوانی می شود دریافت می کنیم. می توانید اطلاعات بیشتر در مورد سهمیه ساده شده را در اینجا بیابید.
تأثیر این تغییر این است که بیشتر تماسهای API هزینه سهمیهای کمتری خواهند داشت، در حالی که برخی از تماسهای API همچنان همان هزینه را خواهند داشت. این تغییر هزینه تماس های API را افزایش نمی دهد. به طور کلی، تأثیر محتمل این است که سهمیه اختصاص داده شده شما، که در Google Cloud Console قابل مشاهده است، کمی فراتر خواهد رفت.
ما قویاً توصیه میکنیم که همه برنامهنویسان برای اطمینان از دسترسی مداوم به سرویسهای YouTube API ، بازرسی انطباق پروژههای خود را انجام دهند.
این مدخل تاریخچه بازبینی در ابتدا در 20 ژوئیه 2020 منتشر شد.
28 جولای 2020
همه ویدیوهای آپلود شده از طریق videos.insert
endpoint از پروژههای API تأیید نشده ایجاد شده پس از ۲۸ ژوئیه ۲۰۲۰ به حالت مشاهده خصوصی محدود میشوند. برای برداشتن این محدودیت، هر پروژه باید تحت بازرسی قرار گیرد تا مطابقت با شرایط خدمات را تأیید کند.
سازندگانی که از یک کلاینت API تأیید نشده برای آپلود ویدیو استفاده میکنند، ایمیلی دریافت میکنند که در آن توضیح میدهد که ویدیوی آنها بهعنوان خصوصی قفل شده است و میتوانند با استفاده از یک مشتری رسمی یا حسابرسی شده از محدودیت جلوگیری کنند.
پروژه های API ایجاد شده قبل از 28 ژوئیه 2020 در حال حاضر تحت تأثیر این تغییر قرار نمی گیرند. با این حال، اکیداً توصیه میکنیم که همه برنامهنویسان برای اطمینان از دسترسی مداوم به سرویسهای YouTube API ، بازرسی انطباق پروژههای خود را انجام دهند .
21 جولای 2020
[بهروزرسانی در 28 ژوئیه 2020.] بهروزرسانی اسنادی که در این مدخل تاریخچه بازبینی به آن اشاره شده است، در 28 ژوئیه 2020 مجدداً منتشر شد.
دیروز، ما یک بهروزرسانی مستندات مربوط به فرآیند خود را برای شارژ سهمیه منتشر کردیم. اما به دلیل شرایط پیش بینی نشده، تغییر سهمیه هنوز اجرایی نشده است. در نتیجه، اسناد به منظور دقت برگردانده شده است. برای جلوگیری از سردرگمی، مدخل تاریخچه بازبینی که این تغییر را توضیح میدهد حذف شده است و در آینده نزدیک مجدداً منتشر خواهد شد.
7 جولای 2020
توجه: این یک اعلامیه منسوخ شدن است.
پارامترهای autoLevels
و stabilize
روش videos.insert
اکنون منسوخ شدهاند و هر دو پارامتر از مستندات حذف شدهاند. مقادیر آنها نادیده گرفته می شود و بر نحوه پردازش ویدیوهای آپلود شده جدید تأثیری نمی گذارد.
15 ژوئن 2020
راهنمای جدید پیروی از خطمشیهای برنامهنویس YouTube راهنمایی و مثالهایی را ارائه میکند تا به شما کمک کند مطمئن شوید که مشتریان API شما به بخشهای خاصی از شرایط و خطمشیهای خدمات YouTube API (API TOS) پایبند هستند.
این راهنما بینشی را در مورد چگونگی اجرای برخی جنبههای API TOS توسط YouTube ارائه میکند، اما هیچ سند موجود را جایگزین نمیکند. این راهنما به برخی از رایج ترین سوالاتی که توسعه دهندگان در طول ممیزی های انطباق API می پرسند، می پردازد. امیدواریم با کمک به درک نحوه تفسیر و اجرای خطمشیهای خود، فرآیند توسعه ویژگیهای شما را سادهتر کند.
4 ژوئن 2020
توجه: این بهروزرسانی یک اعلامیه قبلی منسوخ شدن است.
ویژگی بولتن کانال اکنون به طور کامل منسوخ شده است. این تغییر ابتدا در 17 آوریل 2020 اعلام شد و اکنون اعمال شده است. در نتیجه، روش activities.insert
دیگر پشتیبانی نمیشود، و روش activities.list
دیگر بولتنهای کانال را برمیگرداند. برای جزئیات بیشتر، لطفاً به مرکز راهنمایی YouTube مراجعه کنید.
17 آوریل 2020
توجه: این یک اعلامیه منسوخ شدن است.
یوتیوب ویژگی بولتن کانال را منسوخ می کند. در نتیجه، متد activities.insert
منسوخ میشود و متد activities.list
بازگرداندن بولتنهای کانال را متوقف میکند. این تغییرات در 18 مه 2020 یا پس از آن در API اعمال خواهند شد. برای جزئیات بیشتر، لطفاً به مرکز راهنمایی YouTube مراجعه کنید.
31 مارس 2020
این به روز رسانی شامل تغییرات زیر است:
منابع و روش های جدید
منبع
member
جدید نماینده یک کانال برای یک کانال YouTube است. یک عضو پشتیبانی پولی مکرر را از سازنده ارائه میکند و مزایای ویژهای دریافت میکند. برای مثال، زمانی که سازنده حالت فقط اعضا را برای گپ روشن میکند، اعضا میتوانند چت کنند.این منبع جایگزین منبع
sponsor
می شود که به عنوان بخشی از YouTube Live Streaming API مستند شده است. منبعsponsor
اکنون منسوخ شده است و مشتریان API باید تماس ها را به روشsponsors.list
به روز کنند تا به جای آن از روشmembers.list
استفاده کنند.منبع جدید
membershipsLevel
سطح قیمتی را مشخص می کند که توسط سازنده ای که درخواست API را مجاز کرده است مدیریت می شود. متدmembershipsLevels.list
فهرستی از تمام سطوح عضویت سازنده را بازیابی می کند.
10 ژانویه 2020
API اکنون از توانایی شناسایی محتوای هدایتشده برای کودکان پشتیبانی میکند که YouTube آن را «ساخته شده برای کودکان» مینامد. در مرکز راهنمای YouTube درباره محتوای «ساخته شده برای کودکان» بیشتر بدانید .
channel
و منابع video
از دو ویژگی جدید پشتیبانی میکنند تا سازندگان محتوا و بینندگان بتوانند محتوایی را که برای کودکان ساخته شده است شناسایی کنند:
- ویژگی
selfDeclaredMadeForKids
به سازندگان محتوا امکان میدهد مشخص کنند که کانال یا ویدیو برای کودکان ساخته شده است یا خیر.
برای کانال ها، این ویژگی را می توان هنگام فراخوانی روشchannels.update
تنظیم کرد. برای ویدیوها، این ویژگی را می توان هنگام فراخوانی روش هایvideos.insert
یاvideos.update
تنظیم کرد.
توجه داشته باشید که این ویژگی فقط در پاسخهای API که حاوی منابعchannel
یاvideo
هستند در صورتی گنجانده میشود که مالک کانال درخواست API را مجاز کرده باشد. - ویژگی
madeForKids
هر کاربری را قادر میسازد تا وضعیت «ساخته شده برای بچهها» یک کانال یا ویدیو را بازیابی کند. برای مثال، وضعیت ممکن است بر اساس مقدار ویژگیselfDeclaredMadeForKids
تعیین شود. برای اطلاعات بیشتر درباره تنظیم مخاطب برای کانال، ویدیوها یا پخشهای خود، به مرکز راهنمایی YouTube مراجعه کنید.
ما همچنین شرایط خدمات YouTube API Services و خطمشیهای برنامهنویس را بهروزرسانی کردهایم. لطفاً برای اطلاعات بیشتر به شرایط خدمات YouTube API Services - Revision History مراجعه کنید. تغییرات در شرایط خدمات YouTube API Services و خطمشیهای برنامهنویس از 10 ژانویه 2020 به وقت اقیانوس آرام اعمال میشود.
10 سپتامبر 2019
اسناد مرجع API بهروزرسانی شده است تا تغییری در نحوه گزارش تعداد مشترکین در YouTube و در نتیجه در پاسخهای API نشان دهد. در نتیجه این تغییر، تعداد مشترکین برگردانده شده توسط سرویس YouTube Data API به سه رقم قابل توجه برای تعداد مشترکین بیش از 1000 مشترک کاهش می یابد. این تغییر بر ویژگی statistics.subscriberCount منبع channel
تأثیر می گذارد.
توجه: این تغییر حتی در مواردی که کاربر درخواست مجاز برای دادههای مربوط به کانال خود را ارسال میکند، بر این مقدار ویژگی تأثیر میگذارد. مالکان کانال همچنان میتوانند تعداد دقیق مشترکین را در استودیوی YouTube مشاهده کنند.
برای مثال، اگر کانالی 123456 مشترک داشته باشد، ویژگی statistics.subscriberCount
حاوی مقدار 123000
خواهد بود. جدول زیر نمونههایی از نحوه گرد کردن تعداد مشترکین در پاسخهای API و به اختصار در سایر رابطهای کاربری YouTube قابل مشاهده برای عموم را نشان میدهد:
تعداد مشترکین نمونه | YouTube Data API | رابطهای کاربری YouTube قابل مشاهده برای عموم |
---|---|---|
1,234 | 1230 | 1.23 هزار |
12,345 | 12300 | 12.3 هزار |
123,456 | 123000 | 123 هزار |
1,234,567 | 1230000 | 1.23 میلیون |
12,345,678 | 12300000 | 12.3 میلیون |
123,456,789 | 123000000 | 123M |
4 آوریل 2019
این به روز رسانی شامل تغییرات زیر است:
اسناد مرجع API برای توضیح بهتر موارد استفاده رایج برای هر روش و ارائه نمونه کد پویا و با کیفیت بالا از طریق ویجت APIs Explorer به روز شده است. برای مثال به مستندات روش
channels.list
مراجعه کنید. اکنون دو عنصر جدید در صفحات وجود دارد که روشهای API را توصیف میکنند:ویجت APIs Explorer به شما امکان میدهد محدودههای مجوز را انتخاب کنید، پارامترهای نمونه و مقادیر ویژگی را وارد کنید، و سپس درخواستهای API واقعی را ارسال کنید و پاسخهای API واقعی را ببینید. ویجت همچنین یک نمای تمام صفحه ارائه می دهد که نمونه های کامل کد را نشان می دهد که به صورت پویا برای استفاده از محدوده ها و مقادیری که وارد کرده اید به روز می شوند.
بخش موارد استفاده متداول یک یا چند مورد استفاده متداول را برای روش توضیح داده شده در صفحه توضیح می دهد. برای مثال، میتوانید برای بازیابی دادههای مربوط به یک کانال خاص یا برای بازیابی دادههای مربوط به کانال کاربر فعلی، روش
channels.list
را فراخوانی کنید.میتوانید از پیوندهای موجود در آن بخش برای پر کردن APIs Explorer با مقادیر نمونه برای مورد استفاده خود یا برای باز کردن APIs Explorer تمام صفحه با مقادیری که قبلاً پر شدهاند، استفاده کنید. هدف از این تغییرات، دیدن نمونههای کدی است که مستقیماً در مورد استفادهای که میخواهید در برنامه کاربردی خود پیادهسازی کنید، قابل اجرا هستند.
نمونه کد در حال حاضر برای جاوا، جاوا اسکریپت، پی اچ پی، پایتون و کرل پشتیبانی می شود.
ابزار نمونه کد نیز با یک رابط کاربری جدید به روز شده است که همه ویژگی های مشابهی را که در بالا توضیح داده شد ارائه می دهد. با استفاده از آن ابزار، میتوانید موارد استفاده را برای روشهای مختلف کاوش کنید، مقادیر را در APIs Explorer بارگیری کنید، و APIs Explorer تمام صفحه را باز کنید تا نمونههای کد را در جاوا، جاوا اسکریپت، PHP و پایتون دریافت کنید.
در ارتباط با این تغییر، صفحاتی که قبلاً نمونه کدهای موجود برای جاوا، جاوا اسکریپت، پی اچ پی و پایتون را فهرست کرده بودند حذف شدند.
راهنماهای شروع سریع برای جاوا ، جاوا اسکریپت ، پی اچ پی و پایتون به روز شده است. راهنماهای اصلاح شده نحوه اجرای یک نمونه با کلید API و نمونه دیگر با شناسه مشتری OAuth 2.0 را با استفاده از نمونه کدهای APIs Explorer توضیح می دهند.
توجه داشته باشید که تغییرات توضیح داده شده در بالا جایگزین ابزار تعاملی می شود که در سال 2017 به اسناد API اضافه شده بود.
9 جولای 2018
این به روز رسانی شامل تغییرات زیر است:
تعریف ویژگی
snippet.thumbnails
منبعchannel
بهروزرسانی شده است تا توجه داشته باشید که هنگام نمایش تصاویر کوچک در برنامه شما، کد شما باید از URLهای تصویر دقیقاً همانطور که در پاسخهای API برگردانده شدهاند استفاده کند. به عنوان مثال، برنامه شما نباید از دامنهhttp
به جای دامنهhttps
در URL بازگردانده شده در یک پاسخ API استفاده کند.از ژوئیه 2018، نشانیهای اینترنتی تصاویر کوچک کانال فقط در دامنه
https
در دسترس خواهند بود، به این ترتیب نشانیهای وب در پاسخهای API ظاهر میشوند. پس از آن زمان، اگر برنامه خود سعی کند تصاویر YouTube را از دامنهhttp
بارگیری کند، ممکن است تصاویر شکسته را در برنامه خود مشاهده کنید.توجه: این یک اعلامیه منسوخ شدن است.
ویژگی
recordingDetails.location.altitude
منبعvideo
منسوخ شده است. هیچ تضمینی وجود ندارد که ویدیوها مقادیر این ویژگی را برگردانند. به طور مشابه، حتی اگر درخواستهای API برای تعیین مقدار برای آن ویژگی تلاش کنند، ممکن است دادههای دریافتی ذخیره نشوند.
22 ژوئن 2018
راهنمای پیادهسازی که قبلاً بهعنوان راهنمای پیادهسازی و مهاجرت شناخته میشد، برای حذف دستورالعملهای مهاجرت از API v2 به API v3 بهروزرسانی شده است. علاوه بر این، دستورالعملهایی برای ویژگیهایی که از آن زمان در v3 API منسوخ شدهاند، مانند ویدیوهای مورد علاقه، حذف شدهاند.
27 نوامبر 2017
این به روز رسانی شامل تغییرات زیر است:
توجه: این یک اعلامیه منسوخ شدن است.
YouTube در حال حذف پشتیبانی از ویژگیهای ویدیوی ویژه و وبسایت ویژه است که در API از طریق شیء
invideoPromotion
منبعchannel
پشتیبانی میشوند. در نتیجه، آن شی، از جمله تمام ویژگیهای فرزند آن، منسوخ میشوند.همچنان میتوانید دادههای
invideoPromotion
را تا 14 دسامبر 2017 بازیابی و تنظیم کنید. پس از آن تاریخ:- تلاش برای بازیابی بخش
invideoPromotion
هنگام فراخوانیchannels.list
یکinvideoPromotion
خالی را برمیگرداند یا اصلاً هیچ دادهinvideoPromotion
را بر نمیگرداند. - تلاش برای بهروزرسانی دادههای
invideoPromotion
هنگام تماس باchannels.update
حداقل تا 27 مه 2018 پاسخ موفقیتآمیزی خواهد داشت، اما بهعنوان غیرفعال تلقی میشوند، به این معنی که در واقع بهروزرسانی انجام نمیدهند.
پس از 27 مه 2018، ممکن است این درخواستها پیامهای خطایی را برگردانند تا مثلاً نشان دهند که
invalidPromotion
یک بخش نامعتبر است.- تلاش برای بازیابی بخش
16 نوامبر 2017
این به روز رسانی شامل تغییرات زیر است:
ابزار قطعه کد تعاملی اکنون از نمونه کدهای Node.js پشتیبانی می کند. نمونه ها همچنین در اسناد تقریباً همه روش های API، مانند روش
channels.list
، قابل مشاهده هستند.نمونههای قابل تنظیم به گونهای طراحی شدهاند که یک نقطه شروع خاص برای یک برنامه Node.js به شما ارائه دهند. عملکرد مشابه کد موجود در راهنمای شروع سریع Node.js است. با این حال، نمونه ها حاوی برخی از توابع کاربردی هستند که در شروع سریع ظاهر نمی شوند:
- تابع
removeEmptyParameters
فهرستی از جفتهای کلید-مقدار مربوط به پارامترهای درخواست API را میگیرد و پارامترهایی را که مقادیری ندارند حذف میکند. - تابع
createResource
فهرستی از جفتهای کلید-مقدار مربوط به ویژگیهای یک منبع API را میگیرد. سپس ویژگی ها را به یک شی JSON تبدیل می کند که می تواند در عملیاتinsert
وupdate
استفاده شود. مثال زیر مجموعهای از نامها و مقادیر ویژگی و شی JSON را نشان میدهد که کد برای آنها ایجاد میکند:# Key-value pairs: {'id': 'ABC123', 'snippet.title': 'Resource title', 'snippet.description': 'Resource description', 'status.privacyStatus': 'private'} # JSON object: { 'id': 'ABC123', 'snippet': { 'title': 'Resource title', 'description': 'Resource description', }, 'status': { 'privacyStatus': 'private' } }
همه این نمونه ها برای دانلود و اجرای محلی طراحی شده اند. برای اطلاعات بیشتر، پیش نیازهای اجرای نمونه کد کامل را به صورت محلی در دستورالعملهای ابزار قطعه کد مشاهده کنید.
- تابع
25 اکتبر 2017
این به روز رسانی شامل تغییرات زیر است:
نمونه کدهای پایتون در ابزار قطعه کد تعاملی برای استفاده از کتابخانه های
google-auth
وgoogle-auth-oauthlib
به جای کتابخانهoauth2client
که اکنون منسوخ شده است، به روز شده اند.علاوه بر این تغییر، این ابزار اکنون نمونههای کد کاملی را برای برنامههای پایتون نصب شده و برنامههای وب سرور پایتون ارائه میکند که از جریانهای مجوز کمی متفاوت استفاده میکنند. برای دیدن نمونه های کامل (و این تغییر):
- به ابزار قطعه کد تعاملی یا اسناد مربوط به هر روش API، مانند روش
channels.list
بروید. - روی تب
Python
در بالای نمونه کد کلیک کنید. - برای جابجایی از دیدن یک قطعه به یک نمونه کامل، روی کلید بالای برگه ها کلیک کنید.
- اکنون برگه باید یک نمونه کد کامل را نشان دهد که از جریان مجوز
InstalledAppFlow
استفاده می کند. توضیحات بالای نمونه این را توضیح می دهد و همچنین به نمونه ای برای یک برنامه وب سرور پیوند می دهد. - برای جابجایی به نمونه وب سرور، روی پیوند کلیک کنید. آن نمونه از چارچوب برنامه وب Flask و یک جریان مجوز متفاوت استفاده می کند.
همه این نمونه ها برای دانلود و اجرای محلی طراحی شده اند. اگر میخواهید نمونهها را اجرا کنید، دستورالعملهای اجرای نمونههای کامل کد را به صورت محلی در دستورالعملهای ابزار قطعه کد ببینید.
- به ابزار قطعه کد تعاملی یا اسناد مربوط به هر روش API، مانند روش
29 آگوست 2017
این به روز رسانی شامل تغییرات زیر است:
- تعریف پارامتر
forContentOwner
روشsearch.list
بهروزرسانی شده است تا توجه داشته باشید که اگر آن پارامتر رویtrue
تنظیم شود، پارامترtype
باید رویvideo
تنظیم شود. - تعریف پارامتر
regionCode
روشsearch.list
به روز شده است تا مشخص شود که این پارامتر نتایج جستجو را محدود به ویدیوهایی می کند که می توانند در منطقه مشخص شده مشاهده شوند. - یوتیوب لوگوها و نمادهای برند خود را به روز کرده است. آرمهای جدید «توسعه یافته با YouTube» را میتوانید از صفحه دستورالعملهای برندینگ دانلود کنید. سایر نشانوارهها و نمادهای YouTube نیز در آن صفحه نشان داده شدهاند و میتوانند از سایت برند YouTube دانلود شوند.
24 جولای 2017
این به روز رسانی شامل تغییرات زیر است:
- راهنمای شروع سریع YouTube Data API برای iOS در دسترس است. راهنما نحوه استفاده از YouTube Data API را در یک برنامه ساده iOS که با Objective-C یا Swift نوشته شده است، توضیح می دهد.
- ابزار قطعه کد تعاملی برای YouTube Data API اکنون شامل مستنداتی است که برخی از ویژگی های ابزار را توضیح می دهد:
- اجرای درخواست های API
- جابجایی بین قطعه کد و نمونه کد کامل
- استفاده از توابع دیگ بخار
- بارگیری منابع موجود (برای روش های به روز رسانی)
توجه: این ابزار همچنین در اسناد مرجع API برای روش های API تعبیه شده است ( مثال ).
1 ژوئن 2017
این به روز رسانی شامل تغییرات زیر است:
توجه: این یک اعلامیه منسوخ شدن است.
ویژگی های منبع
video
زیر در حال منسوخ شدن هستند. در حالی که ویژگیها تا 1 دسامبر 2017 پشتیبانی میشوند، هیچ تضمینی وجود ندارد که ویدیوها تا آن زمان به بازگرداندن مقادیر برای آن ویژگیها ادامه دهند. به طور مشابه، درخواستهایvideos.insert
وvideos.update
که این مقادیر ویژگی را تنظیم میکنند، قبل از آن تاریخ خطا ایجاد نمیکنند، اما ممکن است دادههای دریافتی ذخیره نشوند.
17 مه 2017
این به روز رسانی شامل تغییرات زیر است:
اسناد مرجع API به روز شده است تا تکه های کد را فراگیرتر و تعاملی تر کند. صفحاتی که روشهای API را توضیح میدهند، مانند
channels.list
یاvideos.rate
، اکنون دارای یک ابزار تعاملی هستند که به شما امکان میدهد قطعات کد را در جاوا، جاوا اسکریپت، PHP، Python، Ruby، Apps Script و Go مشاهده و سفارشی کنید.برای هر روش معین ، ابزار قطعه های کد را برای یک یا چند مورد استفاده نشان می دهد ، و هر مورد استفاده یک روش مشترک برای فراخوانی آن روش را توصیف می کند. به عنوان مثال ، برای بازیابی داده ها در مورد یک کانال خاص یا در مورد کانال کاربر فعلی می توانید با روش
channels.list
تماس بگیرید.همچنین می توانید با نمونه های کد ارتباط برقرار کنید:
پارامتر و مقادیر خاصیت را اصلاح کنید ، و قطعه های کد به صورت پویا به روز می شوند تا مقادیر ارائه شده را منعکس کنند.
بین قطعه های کد و نمونه های کامل جابجا شوید. یک قطعه کد بخشی از کدی را که روش API را صدا می کند نشان می دهد. یک نمونه کامل حاوی آن قطعه و همچنین کد دیگ بخار برای مجوز و ارسال درخواست است. نمونه های کامل را می توان از خط فرمان یا یک سرور وب محلی کپی و اجرا کرد.
با کلیک روی یک دکمه ، درخواست ها را اجرا کنید. (برای اجرای درخواست ها ، شما باید به ابزار اجازه دهید تا از طرف شما با API تماس بگیرد.)
توجه داشته باشید که این ابزار جایگزین APIS Explorer در صفحات موجود در آن شده است. (هر صفحه پیوندی را نشان می دهد تا شما نیز گزینه بارگیری درخواستی را که در آن کار می کنید در APIS Explorer نیز داشته باشید.)
ابزار قطعه Code Code Data نیز با UI جدید به روز شده است که تمام ویژگی های مشابهی را که در بالا توضیح داده شده است ارائه می دهد. مهمترین ویژگی های جدید موجود در این صفحه عبارتند از:
- پشتیبانی از درخواست های API که داده می نویسند.
- پشتیبانی از نمونه های جاوا.
- کد دیگ بخار انعطاف پذیر و جامع تر برای مجاز کردن کاربران و ساخت درخواست های API.
27 آوریل 2017
این به روزرسانی شامل تغییرات زیر است:
- راهنماهای جدید QuickStart نحوه تنظیم یک برنامه ساده را توضیح می دهد که درخواست های API داده YouTube را ایجاد می کند. راهنماها در حال حاضر برای Android ، Apps Script ، Go ، Java ، JavaScript ، Node.JS ، PHP ، Python و Ruby در دسترس هستند.
30 مارس 2017
این به روزرسانی شامل تغییرات زیر است:
- Tostmetails.Topiccategories [] New
channel
ResourcetopicDetails.topicCategories[]
شامل لیستی از URL های ویکی پدیا است که محتوای کانال را توصیف می کند. URL ها مطابق با شناسه های موضوعی است که در موضوع Resource'stopicDetails.topicIds[]
وجود دارد. -
playlistItem
Resource's NewcontentDetails.videoPublishedAt
زمان انتشار این فیلم در یوتیوب را مشخص می کند. این منبع در حال حاضر حاوی خاصیتsnippet.publishedAt
است ، که زمان اضافه شدن این مورد به لیست پخش را مشخص می کند. - مانند منبع
channel
، منبعvideo
اکنون ویژگیtopicDetails.topicCategories[]
را برمی گرداند ، که حاوی لیستی از URL های ویکی پدیا است که محتوای این فیلم را توصیف می کند. برای منابعvideo
، URL ها با شناسه های موضوع برگشتی در موضوعtopicDetails.relevantTopicIds[]
. -
contentDetails.contentRating.mpaatRating
دارایی جدید این منبعvideo
است ، رتبه بندی را که انجمن تصویر متحرک آمریکا به یک تریلر فیلم یا پیش نمایش داده است ، مشخص می کند.
27 فوریه 2017
همانطور که در ابتدا در 11 آگوست 2016 اعلام شد ، YouTube لیست پشتیبانی شده شناسه های موضوع را به یک لیست سرپرستی تغییر داده است. لیست کاملی از شناسه های موضوع پشتیبانی شده در ویژگی های topicDetails
برای منابع channel
و video
و همچنین در پارامتر topicId
search.list
Method در گنجانده شده است.
توجه داشته باشید که چندین تغییر در لیست سرپرستی وجود دارد:
- مباحث زیر به عنوان زیرمجموعه
Society
اضافه شده است:نام شناسه موضوع کسب و کار /m/09s1f
سلامتی /m/0kt51
نظامی /m/01h6rj
سیاست /m/05qt0
دین /m/06bvp
- موضوع
Animated cartoon
، که قبلاً کودکEntertainment
بود ، حذف شده است. - موضوع
Children's music
، که قبلاً کودکMusic
بود ، حذف شده است.
در نتیجه این تغییر ، مباحث مربوط به یک فیلم اکنون همیشه در topicDetails.relevantTopicIds[]
منبع video
بازگردانده می شوند.
29 نوامبر 2016
این به روزرسانی شامل تغییرات زیر است:
سه تغییر کوچک در لیست شناسه های موضوع وجود دارد که از 10 فوریه 2017 پشتیبانی می شود:
- دسته
Professional wrestling
، که قبلاً فرزند گروهSports
بود ، اکنون فرزندEntertainment
است. - دسته
TV shows
، که کودکEntertainment
است ، جدید است. - گروه
Health
، قبلاً فرزندLifestyle
، برداشته شده است.
همچنین توجه داشته باشید که چند دسته والدین (
Entertainment
،Gaming
،Lifestyle
،Music
وSports
) وجود دارد. هر ویدئویی که با یک گروه کودک همراه باشد ، مانندTennis
، با گروه والدین (Sports
) نیز همراه خواهد بود.- دسته
10 نوامبر 2016
این به روزرسانی شامل تغییرات زیر است:
همانطور که برای اولین بار در 11 آگوست 2016 اعلام شد ، استهلاک FreeBase و API Freebase نیاز به چندین تغییر مربوط به شناسه های موضوع دارد. شناسه های موضوع مباحث مرتبط با منابع
channel
وvideo
را شناسایی می کنند ، و همچنین می توانید از پارامتر جستجویtopicId
برای یافتن کانال ها یا فیلم های مربوط به یک موضوع خاص استفاده کنید.در تاریخ 10 فوریه 2017 ، YouTube به جای مجموعه بسیار گرانول تر از شناسه های برگشتی که تاکنون برگشته است ، شروع به بازگرداندن مجموعه کوچکی از شناسه های موضوع می کند. علاوه بر این ، توجه داشته باشید که کانال ها و فیلم ها تضمین نمی شوند که با هر موضوعی همراه باشند ، که با رفتار API فعلی سازگار است.
به طوری که می توانید مشتری های API خود را برای آن تغییرات آماده کنید ، تعاریف پارامترها و خصوصیات API زیر برای لیست شناسه های موضوع که پس از آن زمان پشتیبانی می شوند به روز شده اند. توجه داشته باشید که لیست دسته ها برای همه خصوصیات یکسان است.
-
topicDetails.topicIds[]
دارایی منابعchannel
. -
topicDetails.relevantTopicIds[]
منبعvideo
. - پارامتر
topicId
search.list
Method.
-
توجه: این یک اعلامیه استهلاک است.
خصوصیات زیر در حال کاهش است:
-
topicDetails.topicIds[]
دارایی منابعchannel
. این ملک تا 10 نوامبر 2017 پشتیبانی می شود. -
topicDetails.relevantTopicIds[]
منبعvideo
. این ملک تا 10 نوامبر 2017 پشتیبانی می شود. -
topicDetails.topicIds[]
دارایی منبعvideo
[]. اینtopicDetails.relevantTopicIds[]
شامل مقادیر بعد از 10 فوریه 2017 نخواهد بود.
-
از آنجا که FreeBase قبلاً کاهش یافته است ، راهنمای جستجوی موضوعات Freebase از مستندات حذف شده است. این راهنما نمونه های کد را برای نشان دادن نحوه کار یک برنامه با API Freebase ارائه می دهد.
علاوه بر این ، چندین نمونه کد مربوط به شناسه های موضوع از مستندات روش
search.list
حذف شده است.
2 نوامبر 2016
این به روزرسانی شامل تغییرات زیر است:
خصوصیات و پارامترهای جدید
منبع
video
شامل چندین ویژگی جدید است:ویژگی
player.embedHtml
حاوی یک برچسب<iframe>
است که می توانید برای تعبیه بازیکنی که این فیلم را پخش می کند ، استفاده کنید.player.embedHeight
وplayer.embedWidth
Properties ابعاد بازیکن تعبیه شده را مشخص می کند. این خصوصیات فقط درصورتی بازگردانده می شوند که درخواست API حداقل یکی از پارامترهایmaxHeight
یاmaxWidth
را تعیین کند. این دو پارامتر جدید بعداً در این ورود تاریخچه تجدید نظر توضیح داده شده است.ویژگی جدید
hasCustomThumbnail
نشان می دهد که آیا بارگذاری کننده ویدیو تصویر تصویربرداری سفارشی را برای این ویدئو ارائه داده است یا خیر. توجه داشته باشید که این ویژگی فقط برای بارگذاری کننده ویدیو قابل مشاهده است.fpbRatingReasons[]
دلایلی را که این فیلم رتبه FPB (آفریقای جنوبی) را دریافت کرده است ، مشخص می کند.mcstRating
جدید رتبه ای را که این فیلم در ویتنام دریافت کرده است ، مشخص می کند.
روش
videos.list
از دو پارامتر جدید ،maxHeight
وmaxWidth
پشتیبانی می کند. هنگام بازیابی قسمتplayer
در منابعvideo
می توانید از پارامتر یا هر دو پارامتر استفاده کنید.به طور پیش فرض ، ارتفاع
<iframe>
درplayer.embedHtml
بازگشت 360px است. عرض برای مطابقت با نسبت ابعاد فیلم تنظیم می شود ، در نتیجه اطمینان می دهد که پخش کننده تعبیه شده دارای میله های سیاه نیست که این فیلم را قاب می کند. بنابراین ، به عنوان مثال ، اگر نسبت ابعاد یک فیلم 16: 9 باشد ، عرض بازیکن 640px خواهد بود.با پارامترهای جدید ، می توانید مشخص کنید که به جای ابعاد پیش فرض ، کد تعبیه شده باید از ارتفاع و/یا عرض مناسب برای طرح برنامه خود استفاده کند. سرور API ابعاد پخش کننده را در حد مناسب مقیاس می دهد تا اطمینان حاصل شود که پخش کننده تعبیه شده دارای میله های سیاه نیست که فیلم را قاب می کند. توجه داشته باشید که هر دو پارامتر حداکثر ابعاد پخش کننده تعبیه شده را مشخص می کنند. بنابراین ، اگر هر دو پارامتر مشخص شده باشند ، یک بعد ممکن است هنوز کوچکتر از حداکثر مقدار مجاز برای آن بعد باشد.
به عنوان مثال ، فرض کنید یک فیلم نسبت ابعاد 16: 9 دارد. بنابراین ، اگر پارامتر
maxHeight
یاmaxWidth
تنظیم نشده باشد ، برچسبplayer.embedHtml
حاوی یک بازیکن 640x360 است.- اگر پارامتر
maxHeight
روی720
تنظیم شود و پارامترmaxWidth
تنظیم نشده باشد ، API یک پخش کننده 1280x720 را برمی گرداند. - اگر پارامتر
maxWidth
روی960
تنظیم شود و پارامترmaxHeight
تنظیم نشده باشد ، API یک پخش کننده 960x540 را برمی گرداند. - اگر پارامتر
maxWidth
روی960
تنظیم شود و پارامترmaxHeight
روی450
تنظیم شود ، API یک پخش کننده 800x450 را برمی گرداند.
player.embedHeight
وplayer.embedWidth
Properties ، که در بالا توضیح داده شده است ، ابعاد بازیکن را مشخص می کند.- اگر پارامتر
به روزرسانی در روش ها ، خصوصیات و پارامترها
توضیحات منابع
channelSection
به روز شده است که توجه داشته باشید که یک کانال می تواند حداکثر 10 قفسه را بدون تنظیم داده های هدفمند ایجاد کند و می تواند حداکثر 100 قفسه را با داده های هدفمند ایجاد کند.علاوه بر این ، خاصیت
targeting
منابعchannelSection
به روز شده است تا این واقعیت را منعکس کند که گزینه های هدفمند فقط با استفاده از API قابل تنظیم هستند. اگر بخش کانال با استفاده از رابط کاربری در وب سایت YouTube اصلاح شود ، گزینه های هدفمند حذف می شوند.تعریف خاصیت
snippet.name
منبعi18nLanguage
. name اصلاح شده است تا منعکس شود که این مقدار نام یک زبان را نشان می دهد همانطور که به زبان مشخص شده توسط پارامترhl
i18nLanguage.list
نوشته شده است.playlistItem
Resource'scontentDetails.note
ویژگی به روز شده است تا توجه داشته باشید که حداکثر طول ارزش خاصیت 280 کاراکتر است.contentDetails.startAt
وcontentDetails.endAt
ازplaylistItem
Resource PlaylistiTEM Resource Resource. این زمینه ها در صورت تنظیم در لیست هایplaylistItems.insert
یاplaylistItems.update
نادیده گرفته می شوند.روشهای
playlistItems.update
playlistItems.delete
onBehalfOfContentOwner
درخواست هایی که از این روش استفاده می کنند نیز باید با یک نشانه مجاز باشند که دسترسی بهhttps://www.googleapis.com/auth/youtubepartner
را فراهم کند.پارامترهای
publishedBefore
وpublishedAfter
از روشsearch.list
. بنابراین ، به عنوان مثال ، اگر پارامترpublishedBefore
تنظیم شود ، API منابع ایجاد شده قبل یا در زمان مشخص شده را برمی گرداند.video
contentDetails.contentRating.grfilmRating
سه مقدار اضافی پشتیبانی می کند:grfilmK12
،grfilmK15
وgrfilmK18
.توضیحات روش
videos.insert
به روز شده است تا توجه داشته باشید که حداکثر اندازه پرونده برای فیلم های بارگذاری شده از 64 گیگابایت به 128 گیگابایت افزایش یافته است.
خطاهای جدید و به روز شده
API از خطاهای جدید زیر پشتیبانی می کند:
نوع خطا جزئیات خطا شرح forbidden (403)
homeParameterDeprecated
روش activities.list
این خطا را برمی گرداند تا نشان دهد که داده های فعالیت صفحه اصلی کاربر از طریق این API در دسترس نیست. اگر پارامترhome
را در یک درخواستtrue
تنظیم کنید ، ممکن است این خطا رخ دهد.invalidValue (400)
invalidContentDetails
روش playlistItems.insert
این خطا را برمی گرداند تا نشان دهد که شیءcontentDetails
در درخواست نامعتبر است. یکی از دلایلی که این خطا رخ می دهد این است که قسمتcontentDetails.note
از 280 کاراکتر طولانی تر است.forbidden (403)
watchHistoryNotAccessible
روش playlistItems.list
این خطا را برمی گرداند تا نشان دهد که این درخواست سعی در بازیابی موارد لیست پخش "Watch History" دارد ، اما این موارد را نمی توان با استفاده از API بازیابی کرد.forbidden (403)
watchLaterNotAccessible
روش playlistItems.list
این خطا را برمی گرداند تا نشان دهد که این درخواست سعی در بازیابی موارد لیست پخش "بعد از تماشای" دارد ، اما با استفاده از API قابل بازیابی نیست.badRequest (400)
uploadLimitExceeded
روش videos.insert
این خطا را برمی گرداند تا نشان دهد که کانال از تعداد فیلم هایی که ممکن است بارگذاری کند فراتر رفته است.forbidden (403)
forbiddenEmbedSetting
روش videos.update
این خطا را برمی گرداند تا نشان دهد که درخواست API سعی در تنظیم یک تنظیم تعبیه نامعتبر برای این فیلم دارد. توجه داشته باشید که برخی از کانال ها ممکن است اجازه ارائه بازیکنان تعبیه شده برای جریان های زنده نداشته باشند. برای اطلاعات بیشتر به مرکز راهنمای YouTube مراجعه کنید.روش
playlistItems.insert
اگر یک فیلم تکراری را در لیست پخش وارد کنید ، دیگر خطایی را برنمی گرداند. این خطایی که قبلاً برای برخی از لیست های پخش مانند فیلم های مورد علاقه رخ داده است ، این اجازه را نمی دهد که کپی ها را مجاز نمی دانند اما دیگر پشتیبانی نمی شوند. به طور کلی ، لیست های پخش به فیلم های تکراری اجازه می دهند.
به روزرسانی های دیگر
ورود تاریخچه تجدید نظر برای 15 سپتامبر 2016 ، به روز شده است تا روشن شود که ، هر زمان که محتوای
channel
.contentDetails.relatedPlaylists.watchHistory
وcontentDetails.relatedPlaylists.watchLater
در پاسخ به ترتیب درج شده است ، آنها همیشه حاوی مقادیرHL
وWL
هستند. علاوه بر این ، این خصوصیات فقط در صورتی شامل می شوند که یک کاربر مجاز در حال بازیابی داده های مربوط به کانال خود کاربر باشد.
15 سپتامبر 2016
این به روزرسانی شامل تغییرات زیر است:
در تاریخ 11 آگوست 2016 ، به روزرسانی تاریخچه تجدید نظر در مورد چندین تغییر مربوط به شناسه های موضوع ، از جمله این واقعیت که مجموعه شناسه های موضوع پشتیبانی شده از 10 فوریه 2017 تغییر خواهد کرد. لیست مباحثی که پشتیبانی می شوند تا 10 نوامبر منتشر می شود ، 2016.
تغییرات زیر اکنون عملی شده است. اطلاع از این تغییرات در به روزرسانی تاریخچه تجدید نظر در 11 آگوست 2016 آورده شده است:
اگر روش
activities.list
با پارامترhome
تنظیم شده رویtrue
فراخوانی شود ، پاسخ API اکنون شامل مواردی مشابه آنچه کاربر YouTube وارد شده در صفحه اصلی می بیند.این یک تغییر جزئی است که برای ارائه تجربه کاربری بهتر از رفتار شرح داده شده در به روزرسانی تاریخچه تجدید نظر در 11 آگوست 2016 در نظر گرفته شده است. این بروزرسانی اظهار داشت که درخواست ها با استفاده از پارامتر
home
یک لیست خالی را برمی گرداند.channel
به ترتیب در حال حاضر به ترتیب برای همه کانال هاcontentDetails.relatedPlaylists.watchHistory
مقادیرHL
وWL
contentDetails.relatedPlaylists.watchLater
.برای روشن شدن ، این خصوصیات فقط برای یک کاربر مجاز بازیابی داده های مربوط به کانال خود کاربر قابل مشاهده است. این خصوصیات همیشه حاوی مقادیر
HL
وWL
است ، حتی برای یک کاربر مجاز که داده های مربوط به کانال خود کاربر را بازیابی می کند. بنابراین ، تاریخچه ساعت و تماشای شناسه های لیست پخش بعدی را نمی توان از طریق API بازیابی کرد.علاوه بر این ، درخواست ها برای بازیابی جزئیات لیست پخش (
playlists.list
) یا لیست های لیست پخش (playlistItems.list
) برای تاریخچه تماشای یک کانال یا تماشای لیست پخش بعدی اکنون لیست های خالی را برمی گرداند. این رفتار برای مقادیر جدید ،HL
وWL
و همچنین برای هرگونه سابقه ساعت یا تماشای شناسه های لیست پخش بعدی که مشتری API شما قبلاً ذخیره کرده است ، صادق است.
منبع
video
fileDetails.recordingLocation
شیء و خصوصیات کودک آن دیگر بازگردانده نمی شوند. پیش از این ، این داده ها (مانند ObjectfileDetails
) فقط توسط صاحب یک فیلم قابل بازیابی است.
11 آگوست 2016
این به روزرسانی شامل تغییرات زیر است:
خدمات خدمات تازه منتشر شده API YouTube API ("اصطلاحات به روز شده") ، که به تفصیل در وبلاگ مهندسی و توسعه دهندگان YouTube مورد بحث قرار گرفته است ، مجموعه ای غنی از به روزرسانی ها را به شرایط فعلی خدمات ارائه می دهد. علاوه بر اصطلاحات به روز شده ، که از تاریخ 10 فوریه 2017 به مرحله اجرا در خواهد آمد ، این بروزرسانی شامل چندین سند پشتیبانی برای کمک به توضیح سیاست هایی است که توسعه دهندگان باید دنبال کنند.
مجموعه کامل اسناد جدید در تاریخ تجدید نظر برای اصطلاحات به روز شده شرح داده شده است. علاوه بر این ، تغییرات آینده در اصطلاحات به روز شده یا در مورد اسناد حامی نیز در آن تاریخ تجدید نظر توضیح داده می شود. شما می توانید از پیوندی در آن سند در یک لیست لیست فید RSS مشترک شوید.
استهلاک Freebase و API Freebase باعث ایجاد چندین تغییر مربوط به شناسه های موضوع می شود. شناسه های موضوع در منابع و روشهای API زیر استفاده می شود:
- قسمت
channel
Resource'stopicDetails
مباحث مرتبط با کانال را مشخص می کند. - قسمت
topicDetails
منبعvideo
مباحث مرتبط با این فیلم را مشخص می کند. - پارامتر
topicId
search.list
MethodID به شما امکان می دهد فیلم ها یا کانال های مربوط به یک موضوع خاص را جستجو کنید.
تغییرات در این ویژگی ها عبارتند از:
از تاریخ 10 فوریه 2017 ، YouTube به جای مجموعه بسیار دانه ای تر از شناسه های برگشتی که تاکنون برگشته است ، شروع به بازگرداندن مجموعه کوچکی از شناسه های موضوع می کند. این مجموعه از موضوعات پشتیبانی شده ، دسته بندی های سطح بالا مانند ورزش یا بسکتبال را شناسایی می کند ، اما به عنوان مثال ، آنها تیم ها یا بازیکنان خاصی را شناسایی نمی کنند. ما مجموعه ای از موضوعات پشتیبانی شده را اعلام خواهیم کرد تا شما وقت خود را برای آماده سازی برنامه خود برای این تغییر داشته باشید.
هر شناسه موضوع FreeBase که قبلاً بازیابی کرده اید می تواند برای جستجوی محتوا تا 10 فوریه 2017 استفاده شود. با این حال ، پس از آن زمان ، شما قادر خواهید بود فقط از مجموعه های کوچکتر از موضوعات مشخص شده در مورد قبلی استفاده کنید تا نتایج جستجو را بازیابی کنید موضوع.
پس از 10 فوریه 2017 ، اگر سعی می کنید با استفاده از شناسه موضوع که در مجموعه کوچکتر از شناسه های موضوعی پشتیبانی شده نیست ، نتایج را جستجو کنید ، API یک مجموعه نتیجه خالی را برمی گرداند.
- قسمت
چندین زمینه و پارامترهای API در 12 سپتامبر 2016 به طور مؤثر کاهش می یابد:
پارامتر
home
Methodactivities.list
یک کاربر مجاز را قادر می سازد تا فید فعالیتی را که در صفحه اصلی YouTube برای آن کاربر نمایش می دهد ، بازیابی کند. درخواست هایی که از این پارامتر بعد از 12 سپتامبر 2016 استفاده می کنند ، یک لیست خالی را برمی گردانند.channel
فقط برای یک کاربر مجاز بازیابیcontentDetails.relatedPlaylists.watchHistory
در مورد کانال شخصی کاربرcontentDetails.relatedPlaylists.watchLater
مشاهده است. پس از 12 سپتامبر 2016 ،contentDetails.relatedPlaylists.watchHistory
یک مقدارHL
را برمی گرداند وcontentDetails.relatedPlaylists.watchLater
دارایی برای همه کانال ها ارزشWL
را برمی گرداند.درخواست های بازیابی جزئیات لیست پخش (
playlists.list
) برای تاریخچه تماشای یک کانال یا تماشای لیست پخش بعدی بعد از 12 سپتامبر 2016 یک لیست خالی را باز می گرداند. درخواست های بازیابی موارد لیست پخش (لیستplaylistItems.list
. بعد از آن زمان لیست کنید. این در مورد مقادیر جدید ،HL
وWL
، و همچنین برای هرگونه تاریخچه ساعت یا تماشای شناسه های لیست پخش بعدی که ممکن است مشتری API شما قبلاً ذخیره کرده باشد ، صادق است.fileDetails.recordingLocation
از منابعvideo
یا هر یک از خصوصیات کودک آن دیگر پس از 12 سپتامبر 2016 بازگردانده نمی شود. این داده ها فقط توسط صاحب یک ویدیو قابل بازیابی هستند زیرا والدینfileDetails
فقط توسط یک صاحب ویدیو قابل بازیابی هستند.
13 ژوئن 2016
این به روزرسانی شامل تغییرات زیر است:
contentDetails.googlePlusUserId
از منابعchannel
کمبود شده است. پیش از این ، این ویژگی تنها در صورتی که کانال با نمایه Google+ همراه بود ، موجود بود. پس از استهلاک ، این ملک دیگر در هیچ منبعchannel
گنجانده نمی شود.snippet.authorGoogleplusProfileUrl
از منبعcomment
کمبود شده است. پیش از این ، این ویژگی تنها در صورتی که کانال با نمایه Google+ همراه بود ، موجود بود. پس از استهلاک ، این ملک دیگر در هیچ منبعcomment
گنجانده نمی شود.
از آنجا که هیچ یک از این خصوصیات به دنبال استهلاک بازگردانده نمی شوند ، هر دو ویژگی از مستندات منابع مربوطه حذف نشده اند.
31 مه 2016
این به روزرسانی شامل تغییرات زیر است:
پارامتر جدید
myRecentSubscribers
روشsubscriptions.list
. لیستی از مشترکان کانال کاربر تأیید شده را به ترتیب زمانی معکوس از زمان مشترک در کانال بازیابی می کند.توجه داشته باشید که پارامتر جدید فقط از بازیابی 1000 مشترک جدید در کانال کاربر تأیید شده پشتیبانی می کند. برای بازیابی لیست کاملی از مشترکان ، از پارامتر
mySubscribers
استفاده کنید. این پارامتر ، که مشترکان را به ترتیب خاصی باز نمی گرداند ، تعداد مشترکانی را که می توان بازیابی کرد محدود نمی کند.تعریف
snippet.thumbnails.(key)
خاصیت برای فعالیت ، لیست پخش ، لیست پخش ، نتیجه جستجو ، تصویر کوچک و ویدیویی به روز شده است تا توجه داشته باشید که اندازه تصویر کوچک تصویر کوچک برای برخی از فیلم ها در دسترس است.- تصویر
standard
640px عرض و 480px قد دارد. - تصویر
maxres
1280px عرض و 720px قد دارد.
- تصویر
تعریف پارامتر
part
channelSection.list
Method به روز شده است تا توجه داشته باشید که قسمتtargeting
را می توان با هزینه2
واحد سهمیه بازیابی کرد.روش
videos.list
اکنون خطایی ممنوعه (403
) را برمی گرداند که یک درخواست مجاز به طور نادرست سعی در بازیابیfileDetails
،processingDetails
یاsuggestions
بخش هایی از یک منبعvideo
دارد. این قسمت ها فقط در اختیار صاحب فیلم است.
17 مه 2016
ابزار جدید قطعه کد API Code ، قطعه های کد کوتاه را برای موارد استفاده API در مورد داده های YouTube متداول فراهم می کند. قطعه های کد در حال حاضر برای کلیه روشهای API فقط خواندنی در برنامه های Script ، Go ، JavaScript ، PHP ، Python و Ruby در دسترس هستند.
برای هر روش ، ابزار نمونه های کد را برای یک یا چند مورد استفاده نشان می دهد. به عنوان مثال ، این روش پنج کد را برای روش search.list
فراهم می کند.
- لیست فیلم ها بر اساس کلمه کلیدی
- فیلم ها را بر اساس مکان لیست کنید
- لیست رویدادهای زنده
- فیلم های کاربر معتبر را جستجو کنید
- لیست فیلم های مرتبط
برای هر مورد استفاده ، ابزار پارامترهای مورد استفاده در درخواست API را نشان می دهد. می توانید مقادیر پارامتر را تغییر دهید ، در این حالت ابزار قطعه کد را به روز می کند تا مقادیر پارامتر ارائه شده را منعکس کند.
سرانجام ، ابزار پاسخ API را به هر درخواست نشان می دهد. اگر پارامترهای درخواست را اصلاح کرده اید ، پاسخ API بر اساس مقادیر پارامتر ارائه شده شما است. توجه داشته باشید که برای نمایش پاسخ های API باید به ابزاری برای ارسال درخواست ها از طرف خود اجازه دهید.
28 آوریل 2016
این به روزرسانی شامل تغییرات زیر است:
ویژگی جدید
contentDetails.projection
از منبعvideo
قالب پیش بینی فیلم را مشخص می کند. مقادیر معتبر خاصیت360
وrectangular
است.video
وfileDetails.recordingLocation
recordingDetails.location
دو به روز شده اند تا تفاوت بین این دو ویژگی را توضیح دهند:- ویژگی
recordingDetails.location
مکانی را که صاحب فیلم می خواهد با این ویدئو در ارتباط باشد ، مشخص می کند. این مکان قابل ویرایش است ، در فیلم های عمومی قابل جستجو است و ممکن است برای فیلم های عمومی برای کاربران نمایش داده شود. - مقدار خاصیت
fileDetails.recordingLocation
تغییر ناپذیر است و مکان مرتبط با پرونده ویدیویی بارگذاری شده اصلی را نشان می دهد. این مقدار فقط برای صاحب فیلم قابل مشاهده است.
- ویژگی
تعریف از
contentDetails.relatedPlaylists.favorites
به عنوان تعریف از منابعchannel
به روز شده است تا توجه داشته باشید که مقدار خاصیت ممکن است حاوی یک شناسه لیست پخش باشد که به یک لیست پخش خالی اشاره دارد و نمی توان آن را بدست آورد. این به این دلیل است که عملکرد فیلم های مورد علاقه قبلاً کاهش یافته است. توجه داشته باشید که این ملک مشمول سیاست استهلاک API نیست .تعریف خطای
ineligibleAccount
، که می تواند توسطcomments.insert
،comments.update
،commentThreads.insert
یاcommentThreads.update
برگردانده شود ، به روز شده است تا منعکس شود که خطا در هنگام استفاده از حساب YouTube برای مجاز بودن درخواست API رخ می دهد. با حساب Google کاربر ادغام نشده است.
20 آوریل 2016
این به روزرسانی شامل تغییرات زیر است:
تعریف پارامتر
part
channels.update
به روز شده است تا توجه داشته باشید کهlocalizations
نیز یک مقدار معتبر برای آن پارامتر است.بخش استفاده از سهمیه راهنمای شروع کار برای پیوند به کنسول توسعه دهنده Google به روز شده است ، جایی که می توانید سهمیه واقعی و استفاده از سهمیه خود را مشاهده کنید.
16 مارس 2016
این به روزرسانی شامل تغییرات زیر است:
به روز رسانی منابع و روشهای موجود
مستندات منابع
channelBanner
به روز شده است تا توجه داشته باشد که اندازه توصیه شده برای تصویر بنر کانال بارگذاری شده تا 1440px 2560px است. حداقل اندازه (2048px با 1152px) تغییر نکرده است.ویژگی جدید
channel
Resourcesnippet.customUrl
URL سفارشی مرتبط با کانال را مشخص می کند. (همه کانال ها دارای URL های سفارشی نیستند.) مرکز کمک YouTube الزامات لازم برای دریافت URL سفارشی و همچنین نحوه تنظیم URL را توضیح می دهد.Object
brandingSettings.watch
Resourcechannel
و تمام خصوصیات کودک آن کاهش یافته است.پاسخ API به یک درخواست
search.list
اکنون شامل یک ویژگیregionCode
است. این ملک کد منطقه ای را که برای جستجوی جستجو استفاده شده است ، مشخص می کند. کد منطقه به API دستور می دهد تا نتایج جستجو را برای کشور مشخص بازگرداند.مقدار خاصیت یک کد کشور دو حرفی است که منطقه را مشخص می کند. روش
i18nRegions.list
لیستی از مناطق پشتیبانی شده را برمی گرداند. مقدار پیش فرضUS
. اگر یک منطقه غیر پشتیبانی مشخص شده باشد ، YouTube ممکن است هنوز منطقه دیگری را به جای مقدار پیش فرض انتخاب کند تا از پرس و جو استفاده کند.تعاریف مربوط به
snippet.label
وsnippet.secondaryReasons[].label
منبعvideoAbuseReportReason
Resource.علاوه بر این ، روش
videoAbuseReportReasons.list
اکنون از پارامترhl
پشتیبانی می کند ، که زبانی را که باید برای متن برچسب در پاسخ API استفاده شود ، مشخص می کند. مقدار پارامتر پیش فرضen_US
است.contentDetails.contentRating.ecbmctRating
دارایی جدید این منبعvideo
است. رتبه یک فیلم را از هیئت ارزیابی و طبقه بندی ترکیه از وزارت فرهنگ و گردشگری مشخص می کند.علاوه بر این ، خصوصیات API برای سایر سیستم های رتبه بندی از مقادیر خاص خاص زیر پشتیبانی می کند:
-
contentDetails.contentRating.fpbRating
(آفریقای جنوبی)
امتیاز: 10 ؛ ارزش خاصیت:fpb10
-
contentDetails.contentRating.moctwRating
(تایوان)
امتیاز: R-12 ؛ ارزش خاصیت:moctwR12
-
contentDetails.contentRating.moctwRating
(تایوان)
امتیاز: R-15 ؛ ارزش خاصیت:moctwR15
-
liveStreamingDetails.activeLiveChatId
از منابعvideo
حاوی شناسه چت زنده فعال مرتبط با این ویدئو است. ارزش ملک فقط در صورتی وجود دارد که این ویدئو یک پخش زنده فعلی است که چت زنده را فعال کرده است. پس از پایان پخش و گپ زنده به پایان رسید ، این ملک دیگر برای این فیلم بازگردانده نمی شود.status.rejectionReason
منبعvideo
legal
API از خطاهای جدید زیر پشتیبانی می کند:
نوع خطا جزئیات خطا شرح badRequest (400)
notEditable
channelSections.insert
،channelSections.update
وchannelSections.delete
این خطا را برمی گردانند تا نشان دهد که بخش کانال مشخص شده نمی تواند ایجاد ، به روز شده یا حذف شود.badRequest (400)
styleRequired
روش های channelSections.insert
وchannelSections.update
این خطا را برمی گرداند تا نشان دهد که منبعchannelSection
ارسال شده در درخواست API باید یک مقدار را برای خاصیتsnippet.style
مشخص کند.badRequest (400)
typeRequired
channelSections.insert
وchannelSections.update
این خطا را برمی گرداند تا نشان دهد که منبعchannelSection
ارسال شده در درخواست API باید یک مقدار را برای خاصیتsnippet.type
مشخص کند.badRequest (400)
processingFailure
روش commentThreads.list
این خطا را برمی گرداند تا نشان دهد سرور API نتوانسته است درخواست را با موفقیت پردازش کند. در حالی که این می تواند یک خطای گذرا باشد ، معمولاً نشان می دهد که ورودی درخواست نامعتبر است. برای اطمینان از اعتبار آن ، ساختار منبعcommentThread
را در بدنه درخواست بررسی کنید.forbidden (403)
commentsDisabled
روش commentThreads.list
این خطا را برمی گرداند تا نشان دهد که ویدیوی مشخص شده توسط پارامترvideoId
نظرات را غیرفعال کرده است.badRequest (400)
commentTextTooLong
روش commentThreads.insert
این خطا را برمی گرداند تا نشان دهد که منبعcomment
که در حال وارد شدن است ، شامل شخصیت های زیادی درsnippet.topLevelComment.snippet.textOriginal
است.invalidValue (400)
videoAlreadyInAnotherSeriesPlaylist
روش playlistItems.insert
این خطا را برمی گرداند تا نشان دهد این ویدئویی که می خواهید به لیست پخش اضافه کنید ، در لیست پخش سری دیگری قرار دارد. برای کسب اطلاعات بیشتر در مورد لیست های پخش سری ، به مرکز راهنمای YouTube مراجعه کنید.badRequest (400)
subscriptionForbidden
روش subscriptions.insert
این خطا را برمی گرداند تا نشان دهد که به حداکثر اشتراک های خود رسیده اید یا اشتراک های اخیر بیش از حد ایجاد کرده اید. در حالت دوم ، می توانید پس از چند ساعت درخواست را دوباره امتحان کنید.badRequest (400)
invalidCategoryId
روش videos.update
این خطا را برمی گرداند تا نشان دهد که خاصیتsnippet.categoryId
در منبعvideo
بارگذاری شده ، شناسه دسته نامعتبر را مشخص می کند. برای بازیابی دسته های پشتیبانی شده از روشvideoCategories.list
استفاده کنید.badRequest (400)
invalidDescription
روش videos.update
این خطا را برمی گرداند تا نشان دهد که خاصیتsnippet.description
در منبعvideo
بارگذاری شده یک مقدار نامعتبر را مشخص می کند.badRequest (400)
invalidPublishAt
روش videos.update
این خطا را برمی گرداند تا نشان دهد که ویژگیstatus.publishAt
در منبعvideo
بارگذاری شده ، زمان انتشار برنامه ریزی شده نامعتبر را مشخص می کند.badRequest (400)
invalidRecordingDetails
روش videos.update
این خطا را برمی گرداند تا نشان دهد که شیءrecordingDetails
در منبعvideo
بارگذاری شده جزئیات ضبط نامعتبر مشخص شده است.badRequest (400)
invalidTags
روش videos.update
این خطا را برمی گرداند تا نشان دهد که خاصیتsnippet.tags
در منبعvideo
بارگذاری شده یک مقدار نامعتبر را مشخص می کند.badRequest (400)
invalidTitle
روش videos.update
این خطا را برمی گرداند تا نشان دهد که خاصیتsnippet.title
در منبعvideo
بارگذاری شده ، عنوان ویدیویی نامعتبر یا خالی را مشخص می کند.badRequest (400)
invalidVideoMetadata
روش videos.update
این خطا را برمی گرداند تا نشان دهد که ابرداده درخواست نامعتبر است. این خطا در صورت بروزرسانی قسمتsnippet
از یک منبعvideo
رخ می دهد اما مقداری را برای هر دو ویژگیsnippet.title
وsnippet.categoryId
تعیین نمی کند.
18 دسامبر 2015
قوانین اتحادیه اروپا (اتحادیه اروپا) مستلزم آن است که افشای خاصی باید به آنها داده شود و رضایت های به دست آمده از کاربران نهایی در اتحادیه اروپا. بنابراین ، برای کاربران نهایی در اتحادیه اروپا ، شما باید خط مشی رضایت کاربر اتحادیه اروپا را رعایت کنید. ما در شرایط خدمات API YouTube خود ، اخطار این نیاز را اضافه کرده ایم.
19 نوامبر 2015
API اکنون از توانایی تنظیم و بازیابی متن بومی شده برای snippet.title
و snippet.description
از playlist
و منابع video
، خاصیت snippet.title
منبع channelSection
و خاصیت snippet.description
از منابع channel
پشتیبانی می کند.
تنظیم عناوین و توضیحات بومی شده
می توانید هنگام تماس با روش
insert
یاupdate
برای آن منبع ، مقادیر بومی سازی شده را برای یک منبع تنظیم کنید. برای تنظیم مقادیر بومی شده برای یک منبع ، هر دو مورد را انجام دهید:اطمینان حاصل کنید که یک مقدار برای خاصیت
snippet.defaultLanguage
منبع تنظیم شده است. این خاصیت زبانsnippet.title
وsnippet.description
را مشخص می کند. ارزش آن می تواند هر زبان برنامه پشتیبانی شده یا سایر کدهای زبانی ISO 639-1: 2002 باشد. به عنوان مثال ، اگر ویدئویی را که دارای عنوان و توضیحات انگلیسی است بارگذاری کنید ، ویژگیsnippet.defaultLanguage
را رویen
قرار می دهید.توجه داشته باشید برای به روزرسانی منابع
channel
: برای تنظیم ویژگیsnippet.defaultLanguage
برای یک منبعchannel
، در واقع باید ویژگی هایbrandingSettings.channel.defaultLanguage
را به روز کنید.شیء
localizations
را به منبعی که به روز می کنید اضافه کنید. هر کلید شیء رشته ای است که یک زبان برنامه یا کد زبان ISO 639-1: 2002 را مشخص می کند ، و هر یک از کلیدها را به یک شیء که شامل عنوان (و توضیحات) برای منبع است ، نقشه می کند.قطعه نمونه زیر زبان پیش فرض منبع را به انگلیسی تنظیم می کند. همچنین عناوین و توضیحات بومی آلمانی و اسپانیایی را به یک فیلم اضافه می کند:
{ "kind": "youtube#video", ... "snippet": { "title": "Playing soccer", "description": "We play soccer in the park on Sundays.", "defaultLanguage": "en", ... }, "localizations": "de": { "title": "Fußball spielen", "description": "Wir spielen Fußball im Park am Sonntag" }, "es": { "title": "Jugar al fútbol", "description": "Nosotros jugamos fútbol en el parque los domingos", } } }
نکته مهم: به یاد داشته باشید که وقتی داده های بومی سازی شده را برای یک منبع به روز می کنید ، درخواست API شما باید شامل تمام نسخه های بومی شده موجود داده ها باشد. به عنوان مثال ، اگر درخواست بعدی برای اضافه کردن داده های پرتغالی به این ویدئو در مثال بالا ارسال کرده اید ، درخواست نیاز به داده های محلی برای آلمانی ، اسپانیایی و پرتغالی دارد.
بازیابی مقادیر بومی شده
The API supports two ways to retrieve localized values for a resource:
Add the
hl
parameter to yourchannels.list
,channelSections.list
,playlists.list
, orvideos.list
request to retrieve localized data for a specific application language that the YouTube website supports . If localized resource details are available in that language, the resource'ssnippet.localized
object will contain the localized values. However, if localized details are not available, thesnippet.localized
object will contain resource details in the resource's default language .For example, suppose a
videos.list
request retrieved data for the video described above with localized German and Spanish data. If thehl
parameter were set tode
, the resource would contain the following data:{ "kind": "youtube#video", ... "snippet": { "title": "Playing soccer", "description": "We play soccer in the park on Sundays.", "defaultLanguage": "en", "localized": { "title": "Fußball spielen", "description": "Wir spielen Fußball im Park am Sonntag" } ... } }
However, if the
hl
parameter were set tofr
, thesnippet.localized
object would contain the English title and description because English is the default language for the resource, and localized French details are not available.Important: Thehl
parameter only supports values that identify application languages that the YouTube website supports. To determine whether localized text is available for other languages, you need to retrieve thelocalizations
part for the resource and filter to determine whether the localized text exists.
For example, you would need to retrieve the full list of localizations to determine whether localized text is available in Appalachian English.When retrieving a resource, include
localizations
in thepart
parameter value to retrieve all of the localized details for that resource. If you are retrieving localized data for a language that is not a current YouTube application language , you need to use this approach to retrieve all localizations and then filter to determine whether the desired localized data exists.
Errors related to localized text values
The API also supports the following new errors for localized text values:
نوع خطا جزئیات خطا شرح badRequest (400)
defaultLanguageNotSetError
This error indicates that a request that tries to insert or update the localizations
object for a resource is failing because thesnippet.defaultLanguage
property is not set for that resource. Thechannels.update
,channelSections.insert
,channelSections.update
,playlists.insert
,playlists.update
,videos.insert
, andvideos.update
methods support this error.badRequest (400)
localizationValidationError
This error indicates that one of the values in a resource's localizations
object failed to validate. For example, this error might occur if the object contains an invalid language code. Thechannels.update
,channelSections.insert
,channelSections.update
,playlists.insert
, andplaylists.update
methods support this error.
4 نوامبر 2015
This update contains the following changes:
Updates to existing resources and methods
The
search.list
method'sorder
parameter has been updated to note that if you sort live broadcasts byviewCount
, the API results are sorted by the broadcasts' number of concurrent viewers while the broadcasts are still ongoing.The
search.list
method'srelatedToVideoId
parameter has been updated to note that if the parameter is set, the only other supported parameters arepart
,maxResults
,pageToken
,regionCode
,relevanceLanguage
,safeSearch
,type
(which must be set tovideo
), andfields
. This update does not reflect a change in API behavior.The definition of the
video
resource'ssnippet.publishedAt
property has been updated to note that the property value, which specifies the date and time that the video was published, might be different than the time that the video was uploaded. For example, if a video is uploaded as a private video and then made public at a later time, the property value specifies the time that the video was made public. The updated definition also explains how the value is populated for private and unlisted videos.This change does not reflect a change in API behavior.
The definition of the
video
resource'sstatus.publishAt
property has been updated to note:- If you set this property's value when calling the
videos.update
method, you must also set thestatus.privacyStatus
property value toprivate
even if the video is already private. - If the request schedules a video to be published at some time in the past, it is published right away. As such, the effect of setting the
status.publishAt
property to a past date and time is the same as of changing the video'sprivacyStatus
fromprivate
topublic
.
- If you set this property's value when calling the
The
video
resource'scontentDetails.contentRating.cncRating
property specifies the video's rating from France's Commission de classification cinematographique. This property replaces thecontentDetails.contentRating.fmocRating
property, which is now deprecated.The definition of the
channel
resource's brandingSettings.channel.keywords has been updated to correctly reflect that the property value contains a space-separated list of strings and not a comma-separated list, as previously documented. This update does not reflect a change in API behavior.The documentation for the
thumbnails.set
method has been updated to accurately reflect that the body of the request contains the thumbnail image that you are uploading and associating with a video. The request body does not contain athumbnail
resource. Previously, the documentation said that you should not provide a request body when calling this method. This update does not reflect a change in API behavior.The description of the
activity
resource has been updated to reflect the fact that theactivities.list
method does not currently include resources related to new video comments. The resource'ssnippet.type
andcontentDetails.comment
have been updated as well.
New and updated errors
The API now supports the following errors:
جزئیات خطا activities.insert
HTTP Response Code badRequest (400)
دلیل invalidMetadata
شرح The kind
property does not match the type of ID provided.commentThreads.update
comments.insert
comments.update
HTTP Response Code badRequest (400)
دلیل commentTextTooLong
شرح The comment
resource that is being inserted or updated contains too many characters in thesnippet.topLevelComment.snippet.textOriginal
property.playlistItems.insert
playlistItems.update
HTTP Response Code forbidden (403)
دلیل playlistItemsNotAccessible
شرح The request is not properly authorized to insert, update, or delete the specified playlist item. playlists.delete
playlists.insert
playlists.update
HTTP Response Code badRequest (400)
دلیل playlistForbidden
شرح This operation is forbidden or the request is not properly authorized. search.list
HTTP Response Code badRequest (400)
دلیل invalidLocation
شرح The location
and/orlocationRadius
parameter value was formatted incorrectly.search.list
HTTP Response Code badRequest (400)
دلیل invalidRelevanceLanguage
شرح The relevanceLanguage
parameter value was formatted incorrectly.subscriptions.insert
HTTP Response Code badRequest (400)
دلیل subscriptionForbidden
شرح This error occurs when any of the following are true: - The subscription that you are trying to create already exists
- You have already reached your maximum number of subscriptions
- You are trying to subscribe to your own channel, which is not supported.
- You have created too many subscriptions recently and need to wait a few hours before retrying the request.
videos.update
HTTP Response Code badRequest (400)
دلیل invalidDefaultBroadcastPrivacySetting
شرح The request attempts to set an invalid privacy setting for the default broadcast.
28 آگوست 2015
This update contains the following changes:
Updates to existing resources and methods
The
video
resource'sstatistics.favoriteCount
property has been deprecated.In accordance with our deprecation policy, this property will continue to be included in
video
resources for at least one year after this announcement. However, the property value is now always set to0
.
7 آگوست 2015
This update contains the following changes:
Updates to existing resources and methods
The definition of the
video
resource'ssnippet.tags[]
property has been updated to provide more information about how the API server calculates the length of the property's value. Note that this update does not reflect a change in the API's behavior.Specifically, the definition now explains that if a tag contains a space, the API server handles the tag value as though it were wrapped in quotation marks, and the quotation marks count toward the character limit. So, for the purposes of character limits, the tag Foo-Baz contains seven characters, but the tag Foo Baz contains nine characters.
The
commentThreads.insert
method no longer supports theshareOnGooglePlus
parameter, which previously indicated whether a comment and replies to that comment should also be posted to the author's Google+ profile. If a request submits the parameter, the API server ignores the parameter but otherwise handles the request.
18 ژوئن 2015
This update contains the following changes:
Updates to existing resources and methods
The
commentThreads.list
method's neworder
parameter specifies the order in which the API response should list comment threads. Threads can be ordered by time or relevance. The default behavior is to order them by time.The
video
resource's newsnippet.defaultAudioLanguage
property specifies the language spoken in the video's default audio track.The definition of the
video
resource'scontentDetails.licensedContent
property has been updated to clarify that the content must have been originally uploaded to a channel linked to a YouTube content partner and then claimed by that partner. This does not represent a change in actual API behavior.The
captions.delete
,captions.download
,captions.insert
,captions.list
, andcaptions.update
methods now support theonBehalfOfContentOwner
parameter, which is already supported for several other methods. Requests that use that method also need to be authorized with a token that provides access to thehttps://www.googleapis.com/auth/youtubepartner
scope.
New and updated errors
The API now supports the following errors:
جزئیات خطا videos.rate
HTTP Response Code badRequest (400)
دلیل emailNotVerified
شرح The user must verify her email address prior to rating the video. videos.rate
HTTP Response Code badRequest (400)
دلیل videoPurchaseRequired
شرح Rental videos can only be rated by users who rented them. The
subscriptions.delete
andsubscriptions.insert
methods no longer support theaccountClosed
andaccountSuspended
errors.
27 آوریل 2015
This update contains the following changes:
New resources and methods
The new
videoAbuseReportReason
resource contains information about a reason that a video would be flagged for containing abusive content. ThevideoAbuseReportReasons.list
method lets you retrieve a list of all of the reasons why videos might be flagged.The new
videos.reportAbuse
method provides a way to actually flag a video that contains abusive content. The body of the request contains a JSON object that specifies the video being flagged as well as the reason that the video is deemed to contain abusive content. Valid reasons can be obtained from thevideoAbuseReportReason.list
method described above.The migration guide has also been updated with an example for reporting an abusive video. With this change, the v3 API now supports all of the v2 API features that it is scheduled to support. These features are also all explained in the migration guide.
Updates to existing resources and methods
The
search.list
method's newforDeveloper
filter parameter restricts a search to only retrieve videos uploaded via the developer's application or website. TheforDeveloper
parameter can be used in conjunction with optional search parameters like theq
parameter.For this feature, each uploaded video is automatically tagged with the project number that is associated with the developer's application in the Google Developers Console .
When a search request subsequently sets the
forDeveloper
parameter totrue
, the API server uses the request's authorization credentials to identify the developer. Therefore, a developer can restrict results to videos uploaded through the developer's own app or website but not to videos uploaded through other apps or sites.The new feature offers functionality that is similar, albeit not identical, to the developer tags functionality that the v2 API supported.
The
channel
resource's newsnippet.country
property lets channel owners associate their channels with a particular country.Note: To set the
snippet.country
property for achannel
resource, you actually need to update thebrandingSettings.channel.country
property.The API now supports targeting for
channelSection
resources. Channel section targeting provides a way to restrict visibility of a content section to users that match particular criteria.The API exposes three targeting options. A user must meet all of the targeting settings for a channel section to be visible.
targeting.languages[]
: A list of YouTube application languages . Users who have chosen one of those languages can see the corresponding channel section.targeting.regions[]
: A list of YouTube preferred content regions . The channel section is visible to users that have selected one of those regions as well as users for whom one of those regions is automatically selected.targeting.countries[]
: A list of countries where the channel section is visible. Each value in the list is an ISO 3166-1 alpha-2 country code .
The definition of the
video
resource'scontentDetails.duration
property has been corrected to reflect that the value can reflect hours, days, and so forth.The documentation for the
channelSections.delete
,playlistItems.delete
,playlists.delete
,subscriptions.delete
, andvideos.delete
method has been corrected to reflect that, when successful, those methods all return an HTTP204
response code (No Content
).
New and updated errors
The API now supports the following errors:
نوع خطا جزئیات خطا شرح badRequest (400)
targetInvalidCountry
The channelSections.insert
andchannelSections.update
methods return this error if the insertedchannelSection
resource contained an invalid value for thetargeting.countries[]
property.badRequest (400)
targetInvalidLanguage
The channelSections.insert
andchannelSections.update
methods return this error if the insertedchannelSection
resource contained an invalid value for thetargeting.languages[]
property.badRequest (400)
targetInvalidRegion
The channelSections.insert
andchannelSections.update
methods return this error if the insertedchannelSection
resource contained an invalid value for thetargeting.regions[]
property.badRequest (400)
operationNotSupported
The comments.insert
method returns this error if the API user is not able to insert a comment in reply to the top-level comment identified by thesnippet.parentId
property. In acommentThread
resource, thesnippet.canReply
property indicates whether the current viewer can reply to the thread.badRequest (400)
invalidChannelId
The search.list
method returns this error if thechannelId
parameter in the request specified an invalid channel ID.badRequest (400)
subscriptionForbidden
The subscriptions.insert
method returns this error if the API user tries to subscribe to the user's own channel.The
captions.update
method no longer supports theinvalidMetadata
andvideoNotFound
errors.
16 آوریل 2015
This update contains the following changes:
The migration guide has been updated to explain how to migrate applications still using comments functionality from the v2 API.
The guide also calls out several commenting features that the v2 API did not support but that are supported in the v3 API . این شامل:
- Retrieving comments about a channel
- Retrieving all comment threads related to a channel, which means that the API response can contain comments about the channel or any of its videos.
- Updating the text of a comment
- Marking a comment as spam
- Setting a comment's moderation status
The Subscribing to push notifications guide has been updated to reflect the fact that notifications are only pushed to the Google PubSubHubBub hub and not also to the Superfeedr hub as previously indicated.
9 آوریل 2015
This update contains the following changes:
The API's new
commentThread
andcomment
resources let you retrieve, insert, update, delete, and moderate comments.A
commentThread
resource contains information about a YouTube comment thread, which comprises a top-level comment and replies, if any exist, to that comment. AcommentThread
resource can represent comments about either a video or a channel.The top-level comment and the replies are actually
comment
resources that are nested inside thecommentThread
resource. It is important to note that thecommentThread
resource does not necessarily contain all replies to a comment, and you need to use thecomments.list
method if you want to retrieve all replies for a particular comment. In addition, some comments do not have replies.The API supports the following methods for
commentThread
resources:-
commentThreads.list
– Retrieve a list of comment threads. Use this method to retrieve comments associated with a particular video or channel. -
commentThreads.insert
– Create a new top-level comment. (Use thecomments.insert
method to reply to an existing comment.) -
commentThreads.update
– Modify a top-level comment.
-
A
comment
resource contains information about a single YouTube comment. Acomment
resource can represent a comment about either a video or a channel. In addition, the comment could be a top-level comment or a reply to a top-level comment.The API supports the following methods for
comment
resources:-
comments.list
– Retrieve a list of comment. Use this method to retrieve all of the replies to a particular comment. -
comments.insert
– Create a reply to an existing comment. -
comments.update
– Modify a comment. -
comments.markAsSpam
– Flag one or more comments as spam. -
comments.setModerationStatus
– Set the moderation status of one or more comments. For example, clear a comment for public display or reject a comment as unfit for display. The API request must be authorized by the owner of the channel or video associated with the comments.. -
comments.delete
– Delete a comment.
-
Note that the API's new
https://www.googleapis.com/auth/youtube.force-ssl
scope, described in the revision history for April 2, 2015 , is required for calls to thecomments.insert
,comments.update
,comments.markAsSpam
,comments.setModerationStatus
,comments.delete
,commentThreads.insert
, andcommentThreads.update
methods.The new Subscribing to push notifications guide explains the API's new support for push notifications via PubSubHubBub , a server-to-server publish/subscribe protocol for Web-accessible resources. Your PubSubHubBub callback server can receive Atom feed notifications when a channel does any of the following activities:
- uploads a video
- updates a video's title
- updates a video's description
The migration guide has also been updated to note the new support for push notifications. However, since the v2 API supported numerous other types of push notifications that are not supported in the v3 API, the mention of PubSubHubBub support is still listed in the Deprecated section of that guide.
The API's new
https://www.googleapis.com/auth/youtube.force-ssl
scope is now a valid scope for any API method that previously supported thehttps://www.googleapis.com/auth/youtube
scope.The API now supports the following errors:
نوع خطا جزئیات خطا شرح badRequest (400)
invalidRating
The videos.rate
method returns this error if the request contained an unexpected value for therating
parameter.The
subscriptions.insert
method no longer supports thesubscriptionLimitExceeded
error, which previously indicated that the subscriber identified with the request had exceeded the subscription rate limit.
2 آوریل 2015
This update contains the following changes:
The new
captions
resource represents a YouTube caption track. A caption track is associated with exactly one YouTube video.The API supports methods to list , insert , update , download , and delete caption tracks.
The migration guide has also been updated to explain how to migrate applications still using captions functionality in the v2 API.
The API's new
https://www.googleapis.com/auth/youtube.force-ssl
scope requires communication with the API server to happen over an SSL connection.This new scope grants the same access as the
https://www.googleapis.com/auth/youtube
scope. And, in fact, those two scopes are functionally identical because the YouTube API server is only available via an HTTPS endpoint. As a result, even though thehttps://www.googleapis.com/auth/youtube
scope does not require an SSL connection, there is actually no other way to make an API request.The new scope is required for calls to the all of the
caption
resource's methods.
11 مارس 2015
This update contains the following changes:
The YouTube Data API (v3) migration guide contains a new tab, named New in the v3 API , that lists features that the v3 API does support and that the v2 API did not support. The same features were previously and are still listed in other tabs in the guide. For example, the new feature explaining how to update a channel's in-video promotional campaign data is also listed under the Channels (profiles) tab.
The YouTube Data API (v3) migration guide has been updated to note that the v3 API will support the following v2 API feature:
The YouTube Data API (v3) migration guide has been updated to note that the following v2 API features will not be supported in the v3 API:
Retrieve video recommendations – The v3 API does not retrieve a list that only contains videos recommended for the current API user. However, you can use the v3 API to find recommended videos by calling the
activities.list
method and setting thehome
parameter value totrue
.In the API response, a resource corresponds to a recommended video if the
snippet.type
property's value isrecommendation
. In that case, thecontentDetails.recommendation.reason
andcontentDetails.recommendation.seedResourceId
properties will contain information about why the video was recommended. Note that there is no guarantee that the response will contain any particular number of recommended videos.Retrieve new subscription videos – The v3 API does not retrieve a list that only contains videos that have recently been uploaded to channels that the API user subscribes to. However, you can use the v3 API to find new subscription videos by calling the
activities.list
method and setting thehome
parameter value totrue
.In the API response, a resource corresponds to a new subscription video if the
snippet.type
property's value isupload
. Note that there is no guarantee that the response will contain any particular number of new subscription videos.Push notifications for feed updates – The v2 API supported push notifications, using either the Simple Update Protocol (SUP) or PubSubHubbub , to monitor user activity feeds for YouTube users. Notifications were provided for new channel subscriptions and when videos were rated, shared, marked as favorites, commented on, or uploaded.
The v3 API will support push notifications using the PubSubHubbub protocol , but the notifications will only cover video uploads and updates to video titles or video descriptions.
Channel location – The v2 API used the
<yt:location>
tag to identify the user's location as entered in the channel's YouTube public profile. While some developers used this field to associate a channel with a particular country, the field's data could not consistently be used for that purpose.Set or retrieve developer tags – The v2 API supported the ability to associate keywords, or developer tags, with a video at the time that the video was uploaded. Developer tags would not be displayed to YouTube users, but video owners could retrieve videos that matched a specific developer tag.
The v3 API will provide a similar, but not identical, feature. Specifically, a developer will be able to search for videos uploaded by the developer's own application. For this feature, each uploaded video is automatically tagged with the project number that is associated with the developer's application in the Google Developers Console . The developer then uses the same project number to search for videos.
List videos by publication date, viewcount, or rating – In the v2 API, the
orderby
parameter let you sort videos in a playlist by position, duration, publication date, title, and several other values. In the v3 API, playlist items are typically sorted by position in ascending order and other sorting options are not available.چند استثنا وجود دارد. A new upload, favorite video, liked video, or recently watched video is automatically added as the first item (
snippet.position
=0
) for the following types of playlists. So, each of these lists is effectively sorted in order of newest to oldest item based on the times that items were added to the list.- user uploads
- ویدیوهای مورد علاقه
- liked videos
- watch history
Note, however, that a new item added to the "Watch later" playlist is added as the last item in that list, so that list is effectively sorted from oldest to newest item.
Batch processing – The v3 API supports one of the batch processing use cases that the v2 API had supported. The v3 API's
channels.list
,channelSections.list
,guideCategories.list
,playlistItems.list
,playlists.list
,subscriptions.list
,videoCategories.list
, andvideos.list
methods all support anid
parameter, which can be used to specify a comma-delimited list of IDs (video IDs, channel IDs, etc.). Using those methods, you can retrieve a list of multiple resources with a single request.
With these changes, the guide now identifies all functionality that was supported in the old (v2) API that will be deprecated in the current API version (v3).
4 مارس 2015
This update contains the following changes:
The
channelSections.delete
andchannelSections.update
methods now support theonBehalfOfContentOwner
parameter, which is already supported for several other methods.The following properties and their child properties have been deprecated:
-
brandingSettings.image.backgroundImageUrl
-
brandingSettings.image.largeBrandedBannerImageImapScript
-
brandingSettings.image.largeBrandedBannerImageUrl
-
brandingSettings.image.smallBrandedBannerImageImapScript
-
brandingSettings.image.smallBrandedBannerImageUrl
Note: None of these properties had been subject to the API Deprecation Policy.
-
The
video
resource's newcontentDetails.contentRating.contentDetails.contentRating.djctqRatingReasons
property identifies the reasons that explain why the video received its DJCQT (Brazil) rating.The API now supports the following errors:
نوع خطا جزئیات خطا شرح notFound (404)
channelNotFound
The channels.update
method returns this error if the request'sid
parameter specifies a channel that cannot be found.badRequest (400)
manualSortRequiredinvalidValue
The playlistItems.insert
andplaylistItems.update
methods return this error if the request attempts to set the playlist item's position, but the playlist does not use manual sorting. For example, playlist items might be sorted by date or popularity. You can address this error by removing thesnippet.position
element from the resource sent in the request body. If you want the playlist item to have a specific position in the list, you need to first update the playlist's ordering setting to Manual . THis setting can be adjusted in the YouTube Video Manager .forbidden (403)
channelClosed
The playlists.list
method returns this error if the request'schannelId
parameter specifies a channel that has been closed.forbidden (403)
channelSuspended
The playlists.list
method returns this error if the request'schannelId
parameter specifies a channel that has been suspended.forbidden (403)
playlistForbidden
The playlists.list
method returns this error if the request'sid
parameter does not support the request or the request is not properly authorized.notFound (404)
channelNotFound
The playlists.list
method returns this error if the request'schannelId
parameter specifies a channel that cannot be found.notFound (404)
playlistNotFound
The playlists.list
method returns this error if the request'sid
parameter specifies a playlist that cannot be found.notFound (404)
videoNotFound
The videos.list
method returns this error if the request'sid
parameter specifies a video that cannot be found.badRequest (400)
invalidRating
The videos.rate
method returns this error if the request contains an unexpected value for therating
parameter.
2 مارس 2015
This update contains the following changes:
The
search.list
method now supports therelevanceLanguage
parameter, which lets you request results that are most relevant to a particular language.The YouTube Data API (v3) migration guide has also been updated to explain how to use this new parameter. The parameter addresses a feature gap that previously existed between the current API version (v3) and the previous version (v2), which has already been deprecated.
The YouTube Data API (v3) migration guide has also been updated to indicate the deprecation of the special feeds and metadata fields that the v2 API provided for describing movies, trailers, television shows, television seasons, and television episodes.
14 ژانویه 2015
This update contains the following changes:
The YouTube Data API (v3) migration guide has been updated to explain how to use the v3 API to upload videos using JavaScript. (See the Upload a video section for details.) This functionality is comparable to the browser-based uploading functionality that the v2 API supports. Note that this change to the migration guide does not reflect an actual API change but rather the availability of new sample code for uploading videos with client-side JavaScript.
Given the support for uploading videos with the JavaScript client library and CORS, the migration guide no longer lists browser-based uploading as a feature that may be deprecated in the v3 API.
The documentation for the
videos.insert
method has been updated to include the new JavaScript code sample described above. The list of JavaScript code samples for the YouTube Data API (v3) has also been updated.
November 11, 2014
This update contains the following changes:
The quota cost for a call to the
search.list
method has changed to 100 units.Important: In many cases, you can use other API methods to retrieve information at a lower quota cost. For example, consider these two ways of finding videos uploaded to the GoogleDevelopers channel.
Quota cost: 100 units
Call the
search.list
method and search forGoogleDevelopers
.Quota cost: 6 units
Call the
channels.list
method to find the right channel ID. Set theforUsername
parameter toGoogleDevelopers
and thepart
parameter tocontentDetails
. In the API response, thecontentDetails.relatedPlaylists.uploads
property specifies the playlist ID for the channel's uploaded videos.Then call the
playlistItems.list
method and set theplaylistId
parameter to the captured ID and thepart
parameter tosnippet
.
8 اکتبر 2014
This update contains the following changes:
The
channel
resource contains two new properties:The
status.longUploadsStatus
property indicates whether the channel is eligible to upload videos that are more than 15 minutes long. This property is only returned if the channel owner authorized the API request. Valid property values are:-
allowed
– The channel can upload videos more than 15 minutes long. -
eligible
– The channel is eligible to upload videos more than 15 minutes long but must first enable the feature. -
disallowed
– The channel is not able or eligible to upload videos more than 15 minutes long.
See the property definition for more information about these values. The YouTube Help Center also provides more detailed information about this feature.
-
The
invideoPromotion.useSmartTiming
property indicates whether the channel's promotional campaign uses "smart timing." This feature attempts to show promotions at a point in the video when they are more likely to be clicked and less likely to disrupt the viewing experience. This feature also picks up a single promotion to show on each video.
The definitions of the
video
resource'ssnippet.title
andsnippet.categoryId
properties have both been updated to clarify the way that API handles calls to thevideos.update
method. If you call that method to update thesnippet
part of avideo
resource, you must set a value for both of those properties.If you try to update the
snippet
part of avideo
resource and do not set a value for both of those properties, the API returns aninvalidRequest
error. That error's description has also been updated.The
video
resource'scontentDetails.contentRating.oflcRating
property, which identifies a video's rating from New Zealand's Office of Film and Literature Classification, now supports two new ratings:oflcRp13
andoflcRp16
. These correspond to theRP13
andRP16
ratings, respectively.The
channelBanners.insert
method now supports the following error:نوع خطا جزئیات خطا شرح badRequest
bannerAlbumFull
The channel owner's YouTube Channel Art album has too many images. The channel owner should go to http://photos.google.com , navigate to the albums page, and remove some from images from that album.
12 سپتامبر 2014
This update contains the following changes:
The quota cost for a call to the
search.list
method has changed from 1 unit to 2 units in addition to the cost of the specified resource parts .
13 آگوست 2014
This update contains the following changes:
The
subscriptions.insert
method now supports the following error:نوع خطا جزئیات خطا شرح badRequest
subscriptionLimitExceeded
The subscriber identified with the request has exceeded the subscription rate limit. More subscriptions can be attempted in a few hours.
12 آگوست 2014
This update contains the following changes:
A new guide, titled Migrating Your Application to YouTube Data API (v3) , explains how to use the YouTube Data API (v3) to perform functionality available in the YouTube Data API (v2). The older API was officially deprecated as of March 4, 2014. The guide intends to help you migrate applications still using the v2 API to the most recent API version.
8 جولای 2014
This update contains the following changes:
The
playlists.insert
method now supports the following error:نوع خطا جزئیات خطا شرح badRequest
maxPlaylistExceeded
This error occurs if a playlist cannot be created because the channel already has the maximum number of playlists allowed.
18 ژوئن 2014
This update contains the following changes:
The description of each API method has been updated to include the quota cost incurred by a call to that method. Similarly, the definitions of
part
parameters have been updated to specify the quota cost of each part that can be retrieved in an API call. For example, a call to thesubscriptions.insert
method has a quota cost of approximately 50 units. Thesubscription
resource also contains three parts (snippet
,contentDetails
, andsubscriberSnippet
), and each of those has a cost of two units.Please remember that quota costs can change without warning.
The
video
resource now supports 43 new content rating systems, which identify the ratings that videos received from various national rating agencies. The newly supported rating systems are from Argentina , Austria , Belgium , Bulgaria , Chile ( television ), Chile ( film ), Czech Republic , Colombia , Denmark , Egypt , Estonia , Finland , France , Greece , Hong Kong , Iceland , Indonesia , Ireland , Israel , Italy , Kenya , Latvia , Luxembourg , Malaysia , Maldives , Malta , Netherlands , Nigeria , Norway , Peru , Philippines , Portugal , Romania , Singapore , Slovakia , South Africa , Sweden , Switzerland , Taiwan , Thailand , and Venezuela .
28 مه 2014
This update contains the following changes:
The
search.list
method now supports thelocation
andlocationRadius
parameters, which let you search for videos associated with a geographic location. A request must specify a value for both parameters to retrieve results based on location, and the API will return an error if a request includes only one of the two parameters.The
location
parameter specifies the latitude/longitude coordinates at the center of the circular geographic area.The
locationRadius
parameter specifies the maximum distance that the location associated with a video can be from the center of the area for the video to still be included in search results.
13 مه 2014
This update contains the following changes:
The
channel
resource'sinvideoPromotion.items[]
property has been updated to note that you can typically only set one promoted item for your channel. If you try to insert too many promoted items, the API will return atooManyPromotedItems
error, which has an HTTP400
status code.The
channelSection
resource now can contain information about a few new types of featured content. ThechannelSection
resource'ssnippet.type
property now supports the following values:-
postedPlaylists
- playlists that the channel's owner posted to the channel's activity feed -
postedVideos
- videos that the channel's owner posted to the channel's activity feed -
subscriptions
- channels that the channel owner has subscribed to
-
The
video
resource's newcontentDetails.contentRating.ifcoRating
property identifies the rating that a video received from the Irish Film Classification Office.The definition of the
watermark
resource'sposition.cornerPosition
property has been updated to note that the watermark always appear in the upper right corner of the player.The definition of the
q
parameter for thesearch.list
method has been updated to note that the query term can use the Boolean NOT (-
) operator to exclude videos associated with a particular search term. The value can also use the Boolean OR (|
) operator to find videos associated with one of several search terms.The definition of the
pageInfo.totalResults
property that is returned in an API response to asearch.list
call has been updated to note that the value is an approximation and may not represent an exact value. In addition, the maximum value is 1,000,000. You should not use this value to create pagination links. Instead, use thenextPageToken
andprevPageToken
property values to determine whether to show pagination links.The
watermarks.set
andwatermarks.unset
methods have been updated to reflect that the API returns an HTTP204
response code for successful requests to those methods.
2 مه 2014
This update contains the following changes:
The new
i18nLanguage
resource identifies an application language that the YouTube website supports. The application language can also be referred to as a UI language. For the YouTube website, an application language could be automatically selected based on Google Account settings, browser language, or IP location, and a user could also manually select the desired UI language from the YouTube site footer.The API supports a method to list supported application languages. Supported languages can be used as the value of the
hl
parameter when calling API methods likevideoCategories.list
andguideCategories.list
.The new
i18nRegion
resource identifies a geographic area that a YouTube user can select as the preferred content region. The content region can also be referred to as a content locale. For the YouTube website, a content region could be automatically selected based on heuristics like the YouTube domain or the user's IP location, and a user could also manually select the desired content region from the YouTube site footer.The API supports a method to list supported content regions. Supported region codes can be used as the value of the
regionCode
parameter when calling API methods likesearch.list
,videos.list
,activities.list
, andvideoCategories.list
.
7 آوریل 2014
This update contains the following changes:
The new
channelSection
resource contains information about a set of videos that a channel has chosen to feature. For example, a section could feature a channel's latest uploads, most popular uploads, or videos from one or more playlists.The API supports methods to list , insert , update , or delete channel sections. You can retrieve a list of channel sections for the authenticated user's channel, by specifying a particular channel ID, or by specifying a list of unique channel section IDs.
The error documentation has also been updated to describe the error messages that the API supports specifically for these new methods.
The definition of the
video
resource'sfileDetails
object has been updated to explain that that object will only be returned if the video'sprocessingDetails.fileDetailsAvailability
property has a value ofavailable
.Similarly, the definition of the
video
resource'ssuggestions
object has been updated to explain that that object will only be returned if the video'sprocessingDetails.tagSuggestionsAvailability
property or itsprocessingDetails.editorSuggestionsAvailability
property has a value ofavailable
.The documentation for the
videos.insert
andvideos.update
methods has been updated to reflect that thestatus.publishAt
property can be set when calling those methods.The definition of the
channel
resource'sinvideoPromotion
object has been updated to explain that the object can only be retrieved by the channel's owner.The parameter list for the
videos.rate
method has been updated to reflect that that method does not actually support theonBehalfOfContentOwner
parameter. This was a documentation error asvideos.rate
requests that set this parameter return a500
error.
31 مارس 2014
This update contains the following changes:
The
video
resource's newstatus.publishAt
property lets you specify the date and time when a private video is scheduled to be published. This property can only be set if the video's privacy status isprivate
and the video has never been published. This new property is not subject to the deprecation policy .
13 مارس 2014
This update contains the following changes:
The API now supports the
contentOwnerDetails
part forchannel
resources. The new part contains channel data that is relevant for YouTube partners linked with the channel, including the ID of the content owner linked to the channel and the date and time when the content owner and channel were linked. Note that this new part is not subject to the deprecation policy .The documentation now lists the maximum supported character length for the following properties:
منبع ویژگی حداکثر طول channel
invideoPromotion.items[].customMessage
40 characters video
snippet.title
100 characters video
snippet.description
5000 bytes video
snippet.tags
500 characters. Note that the property value is a list and that commas between items in the list count toward the limit. The
channel
resource'sbrandingSettings.watch.featuredPlaylistId
property has been deprecated. The API will return an error if you attempt to set its value.The following
video
resource properties have been added to the list of values that can be set when inserting or updating a video:The error documentation now specifies the HTTP response code for each error type.
The API now supports the following errors:
نوع خطا جزئیات خطا شرح badRequest (400)
invalidCriteria
The channels.list
method returns this error if the request specifies filter parameters that cannot be used in conjunction with each other.badRequest (400)
channelTitleUpdateForbidden
The channels.update
method returns this error if you attempt to update a channel'sbrandingSettings
part and change the value of thebrandingSettings.channel.title
property. (Note that the API does not return the error if you omit the property.)badRequest (400)
invalidRecentlyUploadedBy
The channels.update
method returns this error if theinvideoPromotion.items[].id.recentlyUploadedBy
property specifies an invalid channel ID.badRequest (400)
invalidTimingOffset
The channels.update
method returns this error if theinvideoPromotion
part specifies an invalid timing offset.badRequest (400)
tooManyPromotedItems
The channels.update
method returns this error if theinvideoPromotion
part specifies more than the allowed number of promoted items.forbidden (403)
promotedVideoNotAllowed
The channels.update
method returns this error if theinvideoPromotion.items[].id.videoId
property specifies a video ID that either cannot be found or cannot be used as a promoted item.forbidden (403)
websiteLinkNotAllowed
The channels.update
method returns this error if theinvideoPromotion.items[].id.websiteUrl
property specifies a URL that is not allowed.required (400)
requiredTimingType
The channels.update
method returns this error if a request does not specify default timing settings for when YouTube should display a promoted item.required (400)
requiredTiming
The channels.update
method must specify aninvideoPromotion.items[].timing
object for each promoted item.required (400)
requiredWebsiteUrl
The channels.update
method must specify aninvideoPromotion.items[].id.websiteUrl
property for each promoted item.badRequest (400)
invalidPublishAt
The videos.insert
method returns this error if the request metadata specifies an invalid scheduled publishing time.
4 مارس 2014
This update contains the following changes:
The YouTube Data API, v3 is now subject to the Deprecation Policy described in the YouTube APIs Terms of Service . Note that the page that lists the APIs that are subject to the deprecation policy specifically excludes some v3 API functionality from being subject to the policy.
5 دسامبر 2013
This update contains the following changes:
The
search.list
method's documentation has been updated to properly reflect that you do not need to specify a value for exactly one filter parameter when submitting a search request. Rather, you can set a value for zero filter parameters or for one filter parameter.The definitions for the
search.list
method's parameters have been updated to note that you must set thetype
parameter's value tovideo
if you also specify a value for any of the following parameters:-
eventType
-
videoCaption
-
videoCategoryId
-
videoDefinition
-
videoDimension
-
videoDuration
-
videoEmbeddable
-
videoLicense
-
videoSyndicated
-
videoType
-
The minimum size of uploaded channel banner images has been reduced to 2048px by 1152px. (Previously, the minimum size was 2120px by 1192px.) In addition, note that the
channel
resource documentation specifies the maximum sizes of all of the banner images served from the API. For example, the maximum size of thebrandingSettings.image.bannerTvImageUrl
image for television applications is 2120px by 1192px, but the actual image may be 2048px by 1152px. The YouTube Help Center provides additional guidance for optimizing channel art for display on different types of devices.Several
channel
resource property definitions have been updated to reflect the following information:- The
brandingSettings.channel.description
property's value has a maximum length of 1000 characters. - The
brandingSettings.channel.featuredChannelsTitle
property has a maximum length of 30 characters. - The
brandingSettings.channel.featuredChannelsUrls[]
property can now list up to 100 channels. - The
brandingSettings.channel.unsubscribedTrailer
property value, if set, must specify the YouTube video ID of a public or unlisted video that is owned by the channel owner.
- The
The
channels.update
method now supports updates to theinvideoPromotion.items[].promotedByContentOwner
property. That property indicates whether the content owner's name will be shown when displaying the promotion. It can only be set if the API request that sets the property value is being made on the content owner's behalf using theonBehalfOfContentOwner
parameter.The
playlistItems.list
andplaylistItems.insert
methods now support theonBehalfOfContentOwner
parameter, which is already supported for several other methods.The
contentDetails.contentRating.acbRating
property can now specify a rating from either the Australian Classification Board (ACB) for movies or from the Australian Communications and Media Authority (ACMA) for children's television programming.The new
contentDetails.contentRating.catvRating
andcontentDetails.contentRating.catvfrRating
properties identify the ratings that a video received under the Canadian TV Classification System and the French-language Régie du cinéma rating system, which is used in Québec, respectively.The
videoCategory
resource's newsnippet.assignable
property indicates whether updated videos or newly uploaded videos can be associated with that video category.Code samples have been added for the following methods:
-
activities.insert
(Go) -
channelBanners.insert
(Python) -
channels.update
(Python) -
playlistItems.list
(Go) -
search.list
(Go) -
thumbnails.set
(Java) -
videos.insert
(Go)
-
24 اکتبر 2013
This update contains the following changes:
The API includes two additional features designed to help find and feature live broadcast content:
The new
snippet.liveBroadcastContent
property in search results indicates whether a video or channel resource has live broadcast content. Valid property values areupcoming
,active
, andnone
.The
video
resource's newsnippet.liveBroadcastContent
property indicates whether the video is an upcoming or active live broadcast. The list below explains the property's possible values:-
upcoming
– The video is a live broadcast that has not yet started. -
active
– The video is an ongoing live broadcast. -
none
– The video is not an upcoming or active live broadcast. This will be the property value for completed broadcasts that are still viewable on YouTube.
-
The
video
resource's newliveStreamingDetails
property is an object that contains metadata about a live video broadcast. To retrieve this metadata, includeliveStreamingDetails
in thepart
parameter value's list of resource parts. The metadata includes the following new properties:-
liveStreamingDetails.actualStartTime
– The time that the broadcast actually started. (This value will be present once the broadcast's state isactive
.) -
liveStreamingDetails.actualEndTime
– The time that the broadcast actually ended. (This value will be present once the broadcast is over.) -
liveStreamingDetails.scheduledStartTime
– The time that the broadcast is scheduled to begin. -
liveStreamingDetails.scheduledEndTime
– The time that the broadcast is scheduled to end. If the property value is empty or the property is not present, then the broadcast is scheduled to go on indefinitely. -
liveStreamingDetails.concurrentViewers
– The number of people watching the live broadcast.
To retrieve this metadata, include
liveStreamingDetails
in thepart
parameter value when calling thevideos.list
,videos.insert
, orvideos.update
method.-
Note that two other features for identifying live broadcast content were released on October 1, 2013 – the
search.list
method'seventType
parameter and the search result'ssnippet.liveBroadcastContent
property.The
videos.insert
method now supports thenotifySubscribers
parameter, which indicates whether YouTube should send a notification about the new video to users who subscribe to the video's channel. The parameter's default value isTrue
, which indicates that subscribers will be notified of newly uploaded videos. However, a channel owner who is uploading many videos might prefer to set the value toFalse
to avoid sending a notification about each new video to the channel's subscribers.The list of properties that can be modified when calling the
channels.update
method has been updated to include theinvideoPromotion.items[].customMessage
andinvideoPromotion.items[].websiteUrl
properties. In addition, the list has been modified to identify thebrandingSettings
properties that are modifiable. ThesebrandingSettings
properties were already modifiable, so the documentation change does not reflect a change to the API's existing functionality.The
playlists.insert
,playlists.update
, andplaylists.delete
methods now support theonBehalfOfContentOwner
parameter, which is already supported for several other methods.The
playlists.insert
method now supports theonBehalfOfContentOwnerChannel
parameter, which is already supported for several other methods.The
video
resource'scontentDetails.contentRating.tvpgRating
property now supports a value ofpg14
, which corresponds to aTV-14
rating.The definition of the
snippet.liveBroadcastContent
property, which is part of search results, has been corrected to reflect thatlive
is a valid property value, butactive
is not a valid property value.The
video
resource'scontentDetails.contentRating.mibacRating
property now supports two additional ratings:-
mibacVap
(VAP) – Children should be accompanied by an adult. -
mibacVm6
(VM6) – Restricted to 6 and over. -
mibacVm12
(VM12) – Restricted to 12 and over.
-
The
channel
resource's newinvideoPromotion.items[].promotedByContentOwner
property indicates whether the content owner's name will be shown when displaying the promotion. This field can only be set if the API request that sets the value is being made on the content owner's behalf. See theonBehalfOfContentOwner
parameter for more information.
1 اکتبر 2013
This update contains the following changes:
The
channel
resource's newauditDetails
object contains channel data that a multichannel network (MCN) would evaluate while determining whether to accept or reject a particular channel. Note that any API request that retrieves this resource part must provide an authorization token that contains thehttps://www.googleapis.com/auth/youtubepartner-channel-audit
scope. In addition, any token that uses that scope must be revoked when the MCN decides to accept or reject the channel or within two weeks of the date that the token was issued.The
channel
resource'sinvideoPromotion.items[].id.type
property now supports a value ofrecentUpload
, which indicates that the promoted item is the most recently uploaded video from a specified channel.By default, the channel is the same as the one for which the in-video promotion data is set. However, you can promote the most recently uploaded video from another channel by setting the value of the new
invideoPromotion.items[].id.recentlyUploadedBy
property to the channel ID for that channel.The
channel
resource contains three new properties –brandingSettings.image.bannerTvLowImageUrl
,brandingSettings.image.bannerTvMediumImageUrl
,brandingSettings.image.bannerTvHighImageUrl
– that specify the URLs for the banner images that display on channel pages in television applications.The new
snippet.liveBroadcastContent
property in search results indicates whether a video or channel resource has live broadcast content. Valid property values areupcoming
,active
, andnone
.- For a
video
resource, a value ofupcoming
indicates that the video is a live broadcast that has not yet started, while a value ofactive
indicates that the video is an ongoing live broadcast. - For a
channel
resource, a value ofupcoming
indicates that the channel has a scheduled broadcast that has not yet started, while a value ofacive
indicates that the channel has an ongoing live broadcast.
- For a
In the
watermark
resource, thetargetChannelId
property has changed from an object to a string. Instead of containing a child property that specifies the YouTube channel ID of the channel that the watermark image links to, thetargetChannelId
property now specifies that value itself. Accordingly, the resource'stargetChannelId.value
property has been removed.The
thumbnails.set
method now supports theonBehalfOfContentOwner
parameter, which is already supported for several other methods.The
search.list
method now supports theeventType
parameter, which restricts a search to only return either active, upcoming, or completed broadcast events.The new
contentDetails.contentRating.mibacRating
property identifies the rating that a video received from Italy's Ministero dei Beni e delle Attivita Culturali e del Turismo.The API now supports the following errors:
نوع خطا جزئیات خطا شرح badRequest
invalidImage
The thumbnails.set
method returns this error if the provided image content is invalid.forbidden
videoRatingDisabled
The videos.rate
method returns this error if the owner of the video that is being rated has disabled ratings for that video.
August 27, 2013
This update contains the following changes:
The new
watermark
resource identifies an image that displays during playbacks of a specified channel's videos. You can also specify a target channel to which the image will link as well as timing details that determine when the watermark appears during video playbacks and the length of time it is visible.The
watermarks.set
method uploads and sets a channel's watermark image. Thewatermarks.unset
method deletes a channel's watermark image.The error documentation describes the error messages that the API supports specifically for the
watermarks.set
andwatermarks.unset
methods.The
channel
resource's newstatistics.hiddenSubscriberCount
property contains a boolean value that indicates whether the channel's number of subscribers is hidden. As such, the property's value isfalse
if the channel's subscriber count is publicly visible.The
playlists.list
method now supports theonBehalfOfContentOwner
andonBehalfOfContentOwnerChannel
parameters. Both parameters are already supported for several other methods.The
videos.list
method now supports theregionCode
parameter, which identifies the content region for which a chart should be retrieved. This parameter can only be used in conjunction with thechart
parameter. The parameter value is an ISO 3166-1 alpha-2 country code.The
error documentation
describes the following new common request error, which could occur for multiple API methods:نوع خطا جزئیات خطا شرح forbidden
insufficientPermissions
The scopes associated with the OAuth 2.0 token provided for the request are insufficient for accessing the requested data.
15 آگوست 2013
This update contains the following changes:
The
channel
resource'sinvideoPromotion
object has the following new and updated properties:The API now supports the ability to specify a website as a promoted item. To do so, set the
invideoPromotion.items[].id.type
property value towebsite
and use the newinvideoPromotion.items[].id.websiteUrl
property to specify the URL. Also use the newinvideoPromotion.items[].customMessage
property to define a custom message to display for the promotion.Links can be to associated websites, merchant sites, or social networking sites. See the YouTube Help Center instructions for associated websites and merchant sites for more information about enabling links for your content.
By adding promotional links, you agree that those links will not be used to redirect traffic to unauthorized sites and that those links will comply with YouTube's AdWords policies , YouTube ad policies , YouTube Community Guidelines and YouTube Terms of Service .
The properties related to the timing settings for displaying promoted items during video playback have been restructured:
The
invideoPromotion.timing
object has been moved toinvideoPromotion.items[].timing
. This object now enables you to customize the timing data for each promoted item in theinvideoPromotion.items[]
list.The new
invideoPromotion.defaultTiming
object specifies default timing settings for your promotion. Those settings define when a promoted item will display during playback of one of your channel's videos. You can override the default timing for any given promoted item using theinvideoPromotion.items[].timing
object.The new
invideoPromotion.items[].timing.durationMs
property specifies the amount of time, in milliseconds, that the promotion should display. TheinvideoPromotion.defaultTiming
object also contains adurationMs
field that specifies the default amount of time that the promoted item will display.
The
invideoPromotion.items[].type
andinvideoPromotion.items[].videoId
properties both have been moved into theinvideoPromotion.items[].id
object.
The
subscriptions.list
method now supports theonBehalfOfContentOwner
andonBehalfOfContentOwnerChannel
parameters. Both parameters are already supported for several other methods.In the API response to a
thumbnails.set
request, thekind
property value has changed fromyoutube#thumbnailListResponse
toyoutube#thumbnailSetResponse
.Code samples have been added for the following methods:
-
channels.update
(Java, Python) -
playlists.insert
(.NET, PHP) -
subscriptions.insert
(PHP, Python) -
thumbnails.set
(PHP, Python) -
videos.insert
(PHP) -
videos.list
(PHP) -
videos.rate
(Python) -
videos.update
(Java, PHP, Python)
Note that the Python example for the
playlistItems.insert
method was also removed since the functionality it demonstrated is now handled by thevideos.rate
method.-
The
error documentation
describes the following new request context error, which could occur for any API method that supports themine
request parameter:نوع خطا جزئیات خطا شرح badRequest
invalidMine
The mine
parameter cannot be used in requests where the authenticated user is a YouTube partner. You should either remove themine
parameter, authenticate as a YouTube user by removing theonBehalfOfContentOwner
parameter, or act as one of the partner's channels by providing theonBehalfOfContentOwnerChannel
parameter if available for the called method.
8 آگوست 2013
This update contains the following changes:
The Getting Started with the YouTube Data API guide's Quota Usage section has been updated to reflect a change in the quota cost of a video upload from approximately 16000 units to approximately 1600 units.
30 جولای 2013
This update contains the following changes:
In a
channelBanner
resource, the value of thekind
property's value has changed fromyoutube#channelBannerInsertResponse
toyoutube#channelBannerResource
. This resource is returned in response to achannelBanners.insert
request.The
channel
resource's newbrandingSettings.channel.profileColor
property specifies a prominent color that complements the channel's content. The property value is a pound sign (#
) followed by a six-character hexadecimal string, such as#2793e6
.The API now supports the ability to specify whether a subscription is for all of a channel's activities or just for new uploads. The
subscription
resource's newcontentDetails.activityType
property identifies the types of activities that the subscriber will be notified about. Valid property values areall
anduploads
.The
videos.list
method supports new parameters for retrieving a chart of the most popular videos on YouTube:- The
chart
parameter identifies the chart that you want to retrieve. Currently, the only supported value ismostPopular
. Note that thechart
parameter is a filter parameter, which means it cannot be used in the same request as other filter parameters (id
andmyRating
). - The
videoCategoryId
parameter identifies the video category for which the chart should be retrieved. This parameter can only be used in conjunction with thechart
parameter. By default, charts are not restricted to a particular category.
- The
The
video
resource's newtopicDetails.relevantTopicIds[]
property provides a list of Freebase topic IDs that are relevant to the video or its content. The subjects of these topics may be mentioned in or appear in the video.The
video
resource'srecordingDetails.location.elevation
property has been renamed torecordingDetails.location.altitude
, and itsfileDetails.recordingLocation.location.elevation
property has been renamed tofileDetails.recordingLocation.location.altitude
.The
video
resource'scontentDetails.contentRating
object specifies the ratings that a video received under various rating schemes, including MPAA ratings, TVPG ratings, and so forth. For each rating system, the API now supports a rating value that indicates that the video has not been rated. Note that for MPAA ratings , an "unrated" rating is frequently used to identify uncut versions of films for which the cut version of the film did receive an official rating.The
video
resource's newcontentDetails.contentRating.ytRating
property identifies age-restricted content. The property value will beytAgeRestricted
if YouTube has identified the video as containing content that is inappropriate for users less than 18 years old. If the property is absent or if the property value is empty, then the content has not been identified as age-restricted.The
channels.list
method'smySubscribers
parameter has been deprecated. Use thesubscriptions.list
method and itsmySubscribers
parameter to retrieve a list of subscribers to the authenticated user's channel.The
channelBanners.insert
,channels.update
,videos.getRating
, andvideos.rate
methods all now support theonBehalfOfContentOwner
parameter. That parameter indicates that the authenticated user is acting on behalf of the content owner specified in the parameter value.The
channels.update
method's documentation has been updated to reflect the fact that that method can be used to update thechannel
resource'sbrandingSettings
object and its child properties. The documentation also now lists the updated list of properties that you can set for thechannel
resource'sinvideoPromotion
object.The
error documentation
describes the following new errors:نوع خطا جزئیات خطا شرح forbidden
accountDelegationForbidden
This error is not specific to a particular API method. It indicates that the authenticated user is not authorized to act on behalf of the specified Google account. forbidden
authenticatedUserAccountClosed
This error is not specific to a particular API method. It indicates that the authenticated user's YouTube account is closed. If the user is acting on behalf of another Google Account, then this error would indicate that that other account is closed. forbidden
authenticatedUserAccountSuspended
This error is not specific to a particular API method. It indicates that the authenticated user's YouTube account is suspended. If the user is acting on behalf of another Google Account, then this error would indicate that that other account is suspended. forbidden
authenticatedUserNotChannel
This error is not specific to a particular API method. It indicates that the API server cannot identify the channel associated with the API request. If the request is authorized and uses the onBehalfOfContentOwner
parameter, you should also set theonBehalfOfContentOwnerChannel
parameter.forbidden
cmsUserAccountNotFound
This error is not specific to a particular API method. The CMS user is not allowed to act on behalf of the specified content owner. notFound
contentOwnerAccountNotFound
This error is not specific to a particular API method. The specified content owner account was not found. badRequest
invalidPart
This error is not specific to a particular API method. The request's part
parameter specifies parts that cannot be written at the same time.badRequest
videoChartNotFound
The videos.list
method returns this error when the request specifies an unsupported or unavailable video chart.notFound
videoNotFound
The videos.update
method returns this error to indicate that the video you are trying to update cannot be found. Check the value of theid
property in the request body to ensure it is correct.
10 ژوئن 2013
This update contains the following changes:
The
channels.list
method's newforUsername
parameter enables you to retrieve information about a channel by specifying its YouTube username.The
activities.list
method now supports theregionCode
parameter, which instructs the API to return results relevant to the specified country. YouTube uses this value when the authorized user's previous activity on YouTube does not provide enough information to generate the activity feed.Playlist resources now contain the
snippet.tags
property. The property will be only be returned to authorized users who are retrieving data about their own playlists. Authorized users can also set playlist tags when calling either theplaylists.insert
orplaylists.update
methods.The
onBehalfOfContentOwner
parameter, which was previously supported for thechannels.list
andsearch.list
methods, is now also supported for thevideos.insert
,videos.update
, andvideos.delete
methods. Note that when this parameter is used in a call to thevideos.insert
method, the request must also specify a value for the newonBehalfOfContentOwnerChannel
parameter, which identifies the channel to which the video will be added. The channel must be linked to the content owner that theonBehalfOfContentOwner
parameter specifies.The parameter indicates that the request's authorization credentials identify a YouTube CMS user who is acting on behalf of the content owner specified in the parameter value. The CMS account that the user authenticates with must be linked to the specified YouTube content owner.
This parameter is intended for content partners that own and manage many different YouTube channels. The parameter enables those partners to authenticate once and get access to all of their video and channel data, without having to provide authentication credentials for each individual channel.
Specifically in regard to this release, the parameter now enables a content partner to insert, update, or delete videos in any of the YouTube channels that the partner owns.
The
error documentation
describes the following new errors:نوع خطا جزئیات خطا شرح forbidden
insufficientCapabilities
This error is not specific to a particular API method. It indicates that the CMS user calling the API does not have sufficient permissions to perform the requested operation. This error is associated with the use of the onBehalfOfContentOwner
parameter, which is supported for several API methods.unauthorized
authorizationRequired
The activities.list
method returns this error when the request uses thehome
parameter but is not properly authorized.In the
channels
resource, theinvideoPromotion.channelId
property has been removed because the channel ID is already specified using the resource'sid
property.The new Working with Channel IDs guide explains how the API uses channel IDs. The guide may be especially useful for developers migrating from the previous version of the API and who have applications that either request content for the
default
user or that rely on the notion that every YouTube channel has a unique username, which is no longer the case.
22 مه 2013
This update contains the following changes:
The new
channelBanners.insert
method enables you to upload a banner image that can subsequently be set as the banner image for a channel using thechannel
resource's newbrandingSettings.image.bannerExternalUrl
property.The documentation for the
channels.update
method has been updated to list the properties that can be modified when calling the method.The
video
resource documentation no longer listsunspecified
as a valid property value for thesuggestions.processingErrors[]
,suggestions.processingHints[]
,suggestions.processingWarnings[]
, andsuggestions.editorSuggestions[]
properties.The
videos.list
method'smaxResults
parameter now has a default value of5
.The
error documentation
now lists errors for thechannelBanners.insert
andsubscriptions.list
methods. It also lists several new errors for thechannels.update
method.
May 14, 2013
This update contains the following changes:
Standalone pages now list code samples for Java , .NET , PHP , and Ruby .
The page that lists Python code samples now includes examples for adding a subscription, creating a playlist, and updating a video.
10 مه 2013
This update contains the following changes:
YouTube no longer identifies experimental API features and services. Instead, we now provide a list of YouTube APIs that are subject to the deprecation policy .
8 مه 2013
This update contains the following changes:
Channel resources now support the
inVideoPromotion
object, which encapsulates information about a promotional campaign associated with the channel. A channel can use an in-video promotional campaign to display thumbnail images for a promoted video within the video player during playbacks of the channel's videos.You can retrieve this data by including
invideoPromotion
in thepart
parameter value in achannels.list
request.The new
channels.update
method can be used to update a channel's in-video promotional campaign data. Note that the method only supports updates to theinvideoPromotion
part of thechannel
resource and does not yet support updates to other parts of that resource.
2 مه 2013
This update contains the following changes:
Channel resources now support the
status.isLinked
property, which indicates whether the channel data identifies a user that is already linked to either a YouTube username or a Google+ account. A user that has one of these links already has a public YouTube identity, which is a prerequisite for several actions, such as uploading videos.Subscription resources now support the
subscriberSnippet
part. That object encapsulates contains snippet data for the subscriber's channel.The API now supports the
videos.getRating
method, which retrieves the ratings that the authenticated user gave to a list of one or more videos.The
videos.list
method's newmyRating
parameter enables you to retrieve a list of videos that the authenticated user rated with alike
ordislike
rating.The
myRating
parameter and theid
parameter are both now considered filter parameters, which means that an API request must specify exactly one of the parameters. (Previously, theid
parameter was a required parameter for this method.)The method returns a
forbidden
error for requests that attempt to retrieve video rating information but are not properly authorized to do so.With the introduction of the
myRating
parameter, thevideos.list
method has also been updated to support pagination. Note, however, that paging parameters are only supported for requests using themyRating
parameter. (Paging parameters and information are not supported for requests that use theid
parameter.)The
maxResults
parameter specifies the maximum number of videos that the API can return in the result set, and thepageToken
parameter identifies a specific page in the result set that you want to retrieve.The
youtube#videoListResponse
resource, which is returned in response to avideos.list
request, now contains thepageInfo
object, which contains details like the total number of results and the number of results included in the current result set. Theyoutube#videoListResponse
resource can also includenextPageToken
andprevPageToken
properties, each of which provides a token that could be used to retrieve a specific page in the result set.
The
videos.insert
method supports the following new parameters:-
autoLevels
– Set this parameter value totrue
to instruct YouTube to automatically enhance the video's lighting and color. -
stabilize
– Set this parameter value totrue
to instruct YouTube to adjust the video by removing shakiness resulting from camera motions.
-
The
channelTitle
property has been added to thesnippet
for the following resources:-
playlistItem
– The property specifies the name of the channel that added the playlist item. -
playlist
– The property specifies the name of the channel that created the playlist. -
subscription
– The property specifies the name of the channel that is subscribed to.
-
Code samples have been added for the following methods:
-
activities.insert
(Ruby) -
playlistItems.list
(.NET) -
search.list
(.NET) -
subscriptions.insert
(Java, Ruby) -
videos.insert
(.NET, Ruby)
-
The
subscriptions.list
method's newmySubscribers
parameter enables you to retrieve a list of the currently authenticated user's subscribers. This parameter can only be used in a properly authorized request.Note: This functionality is intended to replace the
mySubscribers
parameter currently supported for thechannels.list
method. That parameter will be deprecated.In a
video
resource, the property valueunspecified
is no longer a possible value for any of the following properties:API requests that contain an unexpected parameter now return a
badRequest
error, and the reported reason for the error isunexpectedParameter
.The error that the
playlistItems.insert
method returns when the playlist already contains the maximum number of allowed items has been updated. The error is now reported as aforbidden
error, and the error reason isplaylistContainsMaximumNumberOfVideos
.
19 آوریل 2013
This update contains the following changes:
The new
videos.rate
method lets a user set alike
ordislike
rating on a video or remove a rating from a video.The error documentation has also been updated to list the errors that the API might return in response to a
videos.rate
method call.Thumbnail images are now identified in the API documentation as a separate resource , and the new
thumbnails.set
method enables you to upload a custom video thumbnail to YouTube and set it for a video.The error documentation has also been updated to list the errors that the API might return in response to a
thumbnails.set
method call.Note that this change does not really affect existing resources that return thumbnail images. Thumbnail images are returned in those resources in the same way that they were previously, though the documentation does now list the names of the different thumbnail sizes that the API might return.
The
channel
resource's newbrandingSettings
part identifies settings, text, and images for the channel's channel page and video watch pages.The
playlistItem
resource contains the following new properties:The new
status
object encapsulates status information about the playlist item, and thestatus.privacyStatus
property identifies the playlist item's privacy status.
The
video
resource contains the following new properties:The
status.publicStatsViewable
property indicates whether extended video statistics on the watch page are publicly viewable. By default, those statistics are viewable, and statistics like a video's viewcount and ratings will still be publicly visible even if this property's value is set tofalse
. You can set this property's value when calling thevideos.insert
orvideos.update
method.The
contentDetails.contentRating
object encapsulates ratings that the video received under various rating schemes. The list below identifies the supported rating systems and provides a link to the property associated with each rating system. The property definitions identify the supported rating values for each system.کشور Rating system ویژگی ایالات متحده Motion Picture Association of America (MPAA) contentDetails.contentRating.mpaaRating
ایالات متحده رهنمودهای تلویزیونی والدین contentDetails.contentRating.tvpgRating
استرالیا Australian Classification Board (ACB) contentDetails.contentRating.acbRating
برزیل Departamento de Justiça, Classificação, Qualificação e Títulos contentDetails.contentRating.djctqRating
کانادا Canadian Home Video Rating System (CHVRS) contentDetails.contentRating.chvrsRating
فرانسه Centre national du cinéma et de l'image animée (French Ministry of Culture) contentDetails.contentRating.fmocRating
آلمان Freiwillige Selbstkontrolle der Filmwirtschaft (FSK) contentDetails.contentRating.fskRating
بریتانیای کبیر British Board of Film Classification (BBFC) contentDetails.contentRating.bbfcRating
هند Central Board of Film Certification (CBFC) contentDetails.contentRating.cbfcRating
ژاپن 映倫管理委員会 (EIRIN) contentDetails.contentRating.eirinRating
کشور کره 영상물등급위원회 (KMRB) contentDetails.contentRating.kmrbRating
مکزیک General Directorate of Radio, Television and Cinematography (RTC) contentDetails.contentRating.rtcRating
نیوزلند دفتر رده بندی فیلم و ادبیات contentDetails.contentRating.oflcRating
روسیه National Film Registry of the Russian Federation contentDetails.contentRating.russiaRating
اسپانیا موسسه سمعی و بصری سینما و هنرهای هنری (ICAA) contentDetails.contentRating.icaaRating
The
playlistItems.update
method's documentation has been updated to reflect the fact that thesnippet.resourceId
property must be specified in the resource sent as the request body.The
search.list
method now supports the following functionality:The new
forMine
parameter restricts a search to only retrieve the authenticated user's videos.The
order
parameter now supports the ability to sort results alphabetically by title (order=title
) or by video count in descending order (order=videoCount
).The new
safeSearch
parameter indicates whether search results should include restricted content.
The
videos.insert
method supports several new errors, which are listed in the table below:نوع خطا جزئیات خطا شرح badRequest
invalidCategoryId
The snippet.categoryId
property specifies an invalid category ID. Use thevideoCategories.list
method to retrieve supported categories.badRequest
invalidRecordingDetails
The metadata specifies invalid recording details.
badRequest
invalidVideoGameRating
The request metadata specifies an invalid video game rating. badRequest
invalidVideoMetadata
The request metadata is invalid. The
onBehalfOfContentOwner
parameter has been removed from the list of supported parameters for thevideos.update
andvideos.delete
methods.
12 مارس 2013
This update contains the following changes:
The
channelTitle
property has been added to thesnippet
for the following resources:The
search.list
method supports the following new parameters:The
channelType
parameter lets you restrict a search for channels to retrieve all channels or to retrieve only shows.The
videoType
parameter lets you restrict a search for videos to retrieve all videos or to retrieve only movies or only episodes of shows.
The definition of the
video
resource'srecordingDetails
part has been updated to note that the object will only be returned for a video if the video's geolocation data or recording time has been set.The
playlistItems.update
method now returns aninvalidSnippet
error, which is returned if the API request does not specify a valid snippet.Several API methods support new parameters that are intended exclusively for YouTube content partners. YouTube content partners include movie and television studios, record labels, and other content creators that make their content available on YouTube.
پارامتر
onBehalfOfContentOwner
نشان می دهد که اعتبارنامه مجوز درخواست، کاربر YouTube CMS را شناسایی می کند که از طرف مالک محتوا مشخص شده در مقدار پارامتر عمل می کند. The CMS account that the user authenticates with must be linked to the specified YouTube content owner.This parameter is intended for content partners that own and manage many different YouTube channels. The parameter enables those partners to authenticate once and get access to all of their video and channel data, without having to provide authentication credentials for each individual channel.
The
channels.list
,search.list
,videos.delete
,videos.list
, andvideos.update
methods all support this parameter.The
managedByMe
parameter, which is supported by thechannels.list
method, instructs the API to return all channels owned by the content owner that theonBehalfOfContentOwner
parameter specifies.The
forContentOwner
parameter, which is supported by thesearch.list
method, instructs the API to restrict search results to only include resources that are owned by the content owner that theonBehalfOfContentOwner
parameter specifies.
25 فوریه 2013
This update contains the following changes:
The API supports several new parts and properties for
video
resources:The new
fileDetails
,processingDetails
, andsuggestions
parts provide information to video owners about their uploaded videos. This data is very useful in applications that enable video uploads and includes the following:- processing status and progress
- errors or other issues encountered while processing a video
- availability of thumbnail images
- suggestions for improving video or metadata quality
- details about the original file uploaded to YouTube
All of these parts can only be retrieved by the video owner. The list below briefly describes the new parts, and the
video
resource documentation defines all of the properties that each part contains.The
fileDetails
object contains information about the video file that was uploaded to YouTube, including the file's resolution, duration, audio and video codecs, stream bitrates, and more.The
processingProgress
object contains information about YouTube's progress in processing the uploaded video file. The object's properties identify the current processing status and estimate the time remaining until YouTube finishes processing the video. This part also indicates whether different types of data or content, such as file details or thumbnail images, are available for the video.This object is designed to be polled so that the video uploader can track the progress that YouTube has made in processing the uploaded video file.
The
suggestions
object contains suggestions that identify opportunities to improve the video quality or the metadata for the uploaded video.
The
contentDetails
part contains four new properties. These properties can be retrieved with unauthenticated requests.-
dimension
– Indicates whether the video is available in 2D or 3D. -
definition
– Indicates whether the video is available in standard or high definition. -
caption
– Indicates whether captions are available for the video. -
licensedContent
– Indicates whether the video contains content that has been claimed by a YouTube content partner.
-
The
status
part contains two new properties. Video owners can set values for both properties when inserting or updating a video. These properties can also be retrieved with unauthenticated requests.-
embeddable
– Indicates whether the video can be embedded on another website. -
license
– Specifies the video's license. Valid values arecreativeCommon
andyoutube
.
-
The definition of the
part
parameter has been updated for thevideos.list
,videos.insert
, andvideos.update
methods to list the newly added parts described above as well as therecordingDetails
part, which had been inadvertently omitted.The
channel
resource's newcontentDetails.googlePlusUserId
property specifies the Google+ profile ID associated with the channel. This value can be used to generate a link to the Google+ profile.Each thumbnail image object now specifies the image's width and height. Thumbnail images are currently returned in
activity
,channel
,playlist
,playlistItem
,search result
,subscription
, andvideo
resources.The
playlistItems.list
now supports thevideoId
parameter, which can be used in conjunction with theplaylistId
parameter to only retrieve the playlist item that represents the specified video.The API returns a
notFound
error if the video that the parameter identifies cannot be found in the playlist.The error documentation describes a new
forbidden
error, which indicates that a request is not properly authorized for the requested action.The
channel
resource'ssnippet.channelId
property has been removed. The resource'sid
property provides the same value.
30 ژانویه 2013
This update contains the following changes:
The new error page lists errors that the API can return. The page includes general errors, which might occur for multiple different API methods, as well as method-specific errors.
16 ژانویه 2013
This update contains the following changes:
Code samples are now available for the methods and languages shown in the list below:
-
activities.insert
– Java -
playlistItems.insert
– Python -
playlistItems.list
– Java, JavaScript, PHP, Python, Ruby -
playlists.insert
– Java, JavaScript, Python -
search.list
– Java, JavaScript, Python, Ruby -
videos.insert
– Java
-
An
activity
resource can now report achannelItem
action, which occurs when YouTube adds a video to an automatically generated YouTube channel . (YouTube algorithmically identifies topics that have a significant presence on the YouTube website and automatically generates channels for those topics.)The following
search.list
parameters have been updated:- The
q
parameter is no longer designated as a filter, which means .... - The
relatedToVideo
parameter has been renamedrelatedToVideoId
. - The
published
parameter has been replaced with two new parameters,publishedAfter
andpublishedBefore
, which are described below.
- The
The
search.list
method supports the following new parameters:نام پارامتر ارزش شرح channelId
string
Return resources created by the specified channel. publishedAfter
datetime
Return resources created after the specified time. publishedBefore
datetime
Return resources created before the specified time. regionCode
string
Return resources for the specified country. videoCategoryId
string
Filter video search results to only include videos associated with the specified video category . videoEmbeddable
string
Filter video search results to only include videos that can be played in an embedded player on a web page. Set the parameter value to true
to only retrieve embeddable videos.videoSyndicated
string
Filter video search results to only include videos that can be played outside of YouTube.com. Set the parameter value to true
to only retrieve syndicated videos.Several API resources support new properties. The table below identifies the resources and their new properties:
منبع نام ملک ارزش شرح activity
contentDetails.playlistItem.playlistItemId
string
The playlist item ID that YouTube assigned to uniquely identify the item in the playlist. activity
contentDetails.channelItem
object
An object that contains information about a resource that was added to a channel. This property is only present if the snippet.type
ischannelItem
.activity
contentDetails.channelItem.resourceId
object
An object that identifies the resource that was added to the channel. Like other resourceId
properties, it contains akind
property that specifies the resource type, such as video or playlist. It also contains exactly one of several properties –videoId
,playlistId
, etc. – that specifies the ID that uniquely identifies that resource.channel
status
object
This object encapsulates information about the channel's privacy status. channel
status.privacyStatus
string
The channel's privacy status. Valid values are private
andpublic
.playlist
contentDetails
object
This object contains metadata about the playlist's content. playlist
contentDetails.itemCount
unsigned integer
The number of videos in the playlist. playlist
player
object
This object contains information that you would use to play the playlist in an embedded player. playlist
player.embedHtml
string
An <iframe>
tag that embeds a video player that plays the playlist.video
recordingDetails
object
This object encapsulates information that identifies or describes the place and time that the video was recorded. video
recordingDetails.location
object
This object contains geolocation information associated with the video. video
recordingDetails.location.latitude
double
Latitude in degrees. video
recordingDetails.location.longitude
double
Longitude in degrees. video
recordingDetails.location.elevation
double
Altitude above the Earth, in meters. video
recordingDetails.locationDescription
string
A text description of the location where the video was recorded. video
recordingDetails.recordingDate
datetime
The date and time when the video was recorded. The value is specified in ISO 8601 ( YYYY-MM-DDThh:mm:ss.sZ
) format.The documentation for several API methods now identifies properties that must be specified in the request body or that are updated based on values in the request body. The table below lists those methods as well as the required or modifiable properties.
Note: Documentation for other methods may already list required and modifiable properties.
روش خواص activities.insert
Required properties: -
snippet.description
-
snippet.description
-
contentDetails.bulletin.resourceId
playlists.update
Required properties: -
id
playlistItems.update
Required properties: -
id
videos.update
Required properties: -
id
-
The API no longer reports a
playlistAlreadyExists
error if you try to create or update a playlist that would have the same title as a playlist that already exists in the same channel.Several API methods support new error types. The table below identifies the method and the newly supported errors:
روش نوع خطا جزئیات خطا شرح guideCategories.list
notFound
notFound
The guide category identified by the id
parameter cannot be found. Use the guideCategories.list method to retrieve a list of valid values.playlistItems.delete
forbidden
playlistItemsNotAccessible
The request is not properly authorized to delete the specified playlist item. videoCategories.list
notFound
videoCategoryNotFound
The video category identified by the id
parameter cannot be found. Use the videoCategories.list method to retrieve a list of valid values.
This page lists YouTube Data API (v3) changes and documentation updates. Subscribe to this changelog .
13 مارس 2024
Note: This is a deprecation announcement.
This update contains the following changes:
The sync
parameter for the captions.insert
and captions.update
methods has been deprecated. YouTube will stop supporting the parameter as of April 12, 2024.
As a result of this change, developers must include timing information when inserting or updating caption tracks or the upload will fail.
12 مارس 2024
This update contains the following changes:
Documentation for the captions
resource has been updated to note that the maximum allowed length for the snippet.name
field is 150 characters. The API returns a nameTooLong
error if the track name is longer than that.
7 مارس 2024
Note: This is a deprecation announcement.
The channel
resource property brandingSettings.channel.moderateComments
has been deprecated. YouTube will stop supporting the parameter as of March 7, 2024.
31 ژانویه 2024
This update contains the following changes:
The channels.list
method's new forHandle
parameter enables you to retrieve information about a channel by specifying its YouTube handle.
9 نوامبر 2023
All references to the videoId
resource under Comments
have been removed as the videoId
resource is not being returned using an API call.
September 12, 2023
Note: This is a deprecation announcement.
The comments.markAsSpam
method has been deprecated for several years. This method is already unsupported on YouTube and is no longer supported through the API.
A deprecation notice has been added to all of the documents referencing the comments.markAsSpam
method.
22 اوت 2023
The search.list
method now supports the videoPaidProductPlacement
parameter. This parameter enables you to filter search results to include only videos that the creator has denoted as having a paid promotion.
18 آگوست 2023
The definition of the video
resource's liveStreamingDetails.concurrentViewers
has been updated to note that the concurrent viewer counts that the YouTube Data API returns might differ from the processed, despammed concurrent viewer counts available through YouTube Analytics. The YouTube Help Center provides more information about live streaming metrics.
7 آگوست 2023
As announced on June 12, 2023 , the search.list
method's relatedToVideoId
parameter has been deprecated. That parameter is no longer supported, and references to the parameter have been removed from the API documentation.
June 28, 2023
The thumbnails.set method now supports the uploadRateLimitExceeded
error, which indicates that the channel has uploaded too many thumbnails during the past 24 hours and should try again later.
12 ژوئن 2023
Note: This is a deprecation announcement.
The search.list method's relatedToVideoId
parameter has been deprecated. YouTube will stop supporting the parameter as of August 7, 2023.
At this time, a deprecation notice has been added to the search.list
method's documentation. This parameter will be fully removed from the search.list
documentation on or after August 7, 2023.
In addition, an example demonstrating how to retrieve related videos has been removed from the API implementation guide .
August 22, 2022
Corrected type annotations for video.statistics fields to string from unsigned long.
5 آگوست 2022
YouTube has changed the way that caption IDs are generated and, as part of that change, is assigning new caption IDs to all caption tracks. This change might be a backward-incompatible change for applications that store caption_id
values, though it will not affect applications that do not store caption_id
values.
Between now and December 1, 2022, the captions.list
, captions.update
, captions.download
, and and captions.delete
methods will support both the old and new caption track IDs. However, on or after December 1, 2022, YouTube will stop supporting the old caption track IDs. At that time, calling any of those API methods with an old caption track ID will result in a captionNotFound
error.
To prepare for this change, you should plan to fully replace all stored caption track data between now and December 1, 2022. This means that for any video for which you store caption track data, you should delete the currently stored data, then call the captions.list
method to retrieve the current set of caption tracks for the video and store the data in the API response as you would normally.
12 جولای 2022
The YouTube API Services Terms of Service has been updated. Please see the YouTube API Services Terms of Service - Revision History for more information.
27 آوریل 2022
The videos.insert
method description has been updated to note that the maximum file size for uploaded videos has increased from 128GB to 256GB.
8 آوریل 2022
The subscriptions.list
method's myRecentSubscribers
and mySubscribers
parameter definitions have both been updated to note that the maximum number of subscribers returned by the API might be limited. This change represents a documentation correction and not a change in API behavior.
15 دسامبر 2021
As announced on November 18, 2021 , in conjunction with changes to make video dislike counts private across the entire YouTube platform , the video
resource's statistics.dislikeCount
property is now private.
You can learn more about this change on YouTube's official blog .
18 نوامبر 2021
In conjunction with changes to make video dislike counts private across the entire YouTube platform , the video
resource's statistics.dislikeCount
property will be made private as of December 13, 2021. This means that the property will only be included in an API response from the videos.list
endpoint if the API request was authenticated by the video owner.
The videos.rate
endpoint is not affected by this change.
Developers who do not display dislike counts publicly and still need the dislike count for their API client can apply to be put on an allow list for an exemption. To apply for an exemption, you must complete this application form .
You can learn more about this change on YouTube's official blog .
2 ژوئیه 2021
Note: This is a deprecation announcement.
The commentThreads.update
endpoint has been deprecated and is no longer supported. This endpoint duplicated functionality available through other API endpoints. Instead, you can call the comments.update
commentThreads
resource, make a secondary call to the commentThreads.list
method. 1 ژوئیه 2021
All developers using YouTube's API Services must complete an API Compliance Audit in order to be granted more than the default quota allocation of 10,000 units. To date, both the compliance audit process and requests for additional quota unit allocations have been conducted by developers filling out and submitting the YouTube API Services - Audit and Quota Extension Form .
To clarify these processes and better meet the needs of developers using our API Services, we are adding three new forms and a guide to completing those forms:
- Audited Developer Requests Form : Developers who have already passed an API Compliance Audit can fill out and submit this shorter form to request an allocated quota extension.
- Appeals Form : Developers whose API projects have failed a compliance audit (or been denied a quota unit increase) can fill out and submit this form.
- Change of Control Form : Developers, or any party operating an API client on a developer's behalf, who experience a change of control (for example, through a stock purchase or sale, merger or other form of corporate transaction) associated with an API project must fill out and submit this form. This enables YouTube's API team to update our records, audit the new API project's use case compliance, and validate the developer's current quota allocation.
Each new form will inform us of your intended usage of YouTube's API and enable us to better assist you.
More details are available in our new API Compliance Audits guide .
12 مه 2021
Note: This is a deprecation announcement.
This update covers the following API changes:
The
channel
resource'scontentDetails.relatedPlaylists.favorites
property has been deprecated. Favorite videos functionality has already been deprecated for several years as noted in the April 28, 2016 , revision history entry.Prior to this update, the API would still create a new playlist if an API client attempted to add a video to a nonexistent favorites playlist. Going forward, the playlist will not be created in this case and the API will return an error. Attempts to modify favorites playlists by adding, modifying, or deleting items are also all deprecated per prior announcements and might start returning errors at any time.
The following
channel
resource properties have been deprecated. These properties are already unsupported in the YouTube Studio UI and on YouTube. As a result, they are also no longer supported via the API.-
brandingSettings.channel.defaultTab
-
brandingSettings.channel.featuredChannelsTitle
-
brandingSettings.channel.featuredChannelsUrls[]
-
brandingSettings.channel.profileColor
-
brandingSettings.channel.showBrowseView
-
brandingSettings.channel.showRelatedChannels
All of the properties have been removed from the
channel
resource representation , and their definitions have been removed from the resource's property list . In addition, errors associated with these properties have been removed from the method-specific documentation.-
The following
channelSection
resource properties have been deprecated. These properties are already unsupported in the YouTube Studio UI and on YouTube. As a result, they are also no longer supported via the API.-
snippet.style
-
snippet.defaultLanguage
-
snippet.localized.title
-
localizations
-
localizations.(key)
-
localizations.(key).title
-
targeting
-
targeting.languages[]
-
targeting.regions[]
-
targeting.countries[]
In conjunction with this change, the
channelSection.list
method'shl
parameter has also been deprecated since the features it supports are not supported.All of the properties have been removed from the
channelSection
resource representation , and their definitions have been removed from the resource's property list . In addition, errors associated with these properties have been removed from the method-specific documentation.-
For the
channelSection
resource'ssnippet.type
property, the following values have been deprecated. These values are already unsupported on YouTube channel pages and, as a result, they are also no longer supported via the API.-
likedPlaylists
-
likes
-
postedPlaylists
-
postedVideos
-
recentActivity
-
recentPosts
-
The
playlist
resource'ssnippet.tags[]
property has been deprecated. This property is already unsupported on YouTube and, as a result, it is no longer supported via the API.
9 فوریه 2021
The playlistItem
resource supports two new properties:
- The
snippet.videoOwnerChannelId
property identifies the ID of the channel that uploaded the playlist video. - The
snippet.videoOwnerChannelTitle
property identifies the name of the channel that uploaded the playlist video.
28 ژانویه 2021
This update contains the following changes:
The
playlistItems.delete
,playlistItems.insert
,playlistItems.list
,playlistItems.update
,playlists.delete
,playlists.list
, andplaylists.update
methods all support a newplaylistOperationUnsupported
error. The error occurs when a request attempts to perform an operation that is not allowed for a particular playlist. For example, a user cannot delete a video from their uploaded videos playlist or delete the playlist itself.In all cases, this error returns a
400
HTTP response code (Bad Request).The
playlistItems.list
method'swatchHistoryNotAccessible
andwatchLaterNotAccessible
errors have been removed from the documentation. While users' watch history and watch later lists are, indeed, not accessible via the API, these particular errors are not returned by the API.
15 اکتبر 2020
Two new sections have been added to the Developer Policies :
- The new Section III.E.4.i provides additional information about the data collected and sent via the YouTube embedded player. You are responsible for any user data you send to us via any YouTube embedded player before the user has interacted with the player to indicate playback intent. You can limit the data shared with YouTube before a user interacts with the player by setting Autoplay to false.
- The new Section III.E.4.j relates to checking the Made for Kids (MFK) status of content before embedding it on your sites and apps. You are responsible for knowing when videos that you embed on your API Client are made for kids and treating data collected from the embedded player accordingly. As such, you must check the status of content using YouTube Data API Service before embedding it on your API Client via any YouTube embedded players.
The new Finding the MadeForKids status of a video guide explains how to look up the MFK status of a video using the YouTube Data API Service .
In conjunction with these changes, a reminder has been added to the Embedded Player Parameter documentation to explain that if you enable Autoplay, playback will occur without any user interaction with the player; playback data collection and sharing will therefore occur upon page load.
8 اکتبر 2020
This update covers three small changes related to the channel
resource:
- The
snippet.thumbnails
object, which identifies a channel's thumbnail images, might be empty for newly created channels and might take up to one day to populate. - The
statistics.videoCount
property reflects the count of the channel's public videos only, even to owners. This behavior is consistent with counts shown on the YouTube website. - Channel keywords, which are identified in the
brandingSettings.channel.keywords
property, might be truncated if they exceed the maximum allowed length of 500 characters or if they contained unescaped quotation marks ("
). Note that the 500 character limit is not a per-keyword limit but rather a limit on the total length of all keywords. This behavior is consistent with that on the YouTube website.
9 سپتامبر 2020
Note: This is a deprecation announcement.
This update covers the following API changes. All changes will go into effect on or after 9 September 2020, the date of this announcement. With that in mind, developers should no longer rely on any of the API features listed below.
- The following API resources, methods, parameters, and resource properties are deprecated immediately and will stop working on or after the date of this announcement:
- The following
channel
resource properties:- The
statistics.commentCount
property - The
brandingSettings.image
object and all of its child properties - The
brandingSettings.hints
list and all of its child properties
- The
- The
channels.list
method'scategoryId
filter parameter - The
guideCategories
resource and theguideCategories.list
method
- The following
- API responses for the
channels.list
method no longer contain theprevPageToken
property if the API request sets themanagedByMe
parameter totrue
. This change does not affect theprevPageToken
property for otherchannels.list
requests, and it does not affect thenextPageToken
property for any requests. - The
channel
resource'scontentDetails.relatedPlaylists.watchLater
andcontentDetails.relatedPlaylists.watchHistory
properties were both announced as deprecated on 11 August 2016 . TheplaylistItems.insert
method's andplaylistItems.delete
method's support for these playlists are also now fully deprecated, and the two properties have been removed from the documentation. - The
channels.list
method'smySubscribers
parameter, which was announced as deprecated on 30 July 2013 , has been removed from the documentation. Use thesubscriptions.list
method and itsmySubscribers
parameter to retrieve a list of subscribers to the authenticated user's channel. - The
channel
resource'sinvideoPromotion
object and all of its child properties, which were announced as deprecated on 27 November 2017 , have been removed from the documentation.
29 جولای 2020
We have simplified our process for charging quota for API requests by removing the additional cost associated with the part
parameter. Effective immediately, we will only charge the base cost for the method that is called. You can find more information about the simplified quota here .
The effect of this change is that most API calls will have a marginally lower quota cost, while some API calls will still have the same cost. This change does not increase the cost of any API calls. Overall, the likely impact is that your allocated quota, which can be seen in the Google Cloud Console , will go a little further.
We strongly recommend that all developers complete a compliance audit for their projects to ensure continued access to the YouTube API Services.
This revision history entry was originally published on July 20, 2020.
28 جولای 2020
All videos uploaded via the videos.insert
endpoint from unverified API projects created after 28 July 2020 will be restricted to private viewing mode. To lift this restriction, each project must undergo an audit to verify compliance with the Terms of Service .
Creators who use an unverified API client to upload video will receive an email explaining that their video is locked as private, and that they can avoid the restriction by using an official or audited client.
API projects created prior to 28 July 2020 are not currently affected by this change. However, we strongly recommend that all developers complete a compliance audit for their projects to ensure continued access to the YouTube API Services.
21 جولای 2020
[Updated July 28, 2020.] The documentation update referenced in this revision history entry was republished on July 28, 2020.
Yesterday, we published a documentation update related to our process for charging quota. However, due to unforeseen circumstances, the quota change is not yet in effect. As a result, the documentation has been reverted in the interest of accuracy. To avoid confusion, the revision history entry explaining the change has been removed and will be republished in the near future.
7 جولای 2020
Note: This is a deprecation announcement.
The videos.insert
method's autoLevels
and stabilize
parameters are now deprecated, and both parameters have been removed from the documentation. Their values are ignored and do not affect the way newly uploaded videos are processed.
15 ژوئن 2020
The new Complying with the YouTube Developer Policies guide provides guidance and examples to help you ensure that your API clients adhere to specific portions of the YouTube API Services Terms and Policies (API TOS).
This guidance offers insight into how YouTube enforces certain aspects of the API TOS but does not replace any existing documents. The guide addresses some of the most common questions that developers ask during API compliance audits. We hope that it simplifies your feature development process by helping you understand how we interpret and enforce our policies.
4 ژوئن 2020
Note: This is an update to a prior deprecation announcement.
The channel bulletin feature has now been fully deprecated. This change was initially announced on 17 April 2020 and has now taken effect. As a result, the activities.insert
method is no longer supported, and the activities.list
method no longer returns channel bulletins. For more details, please see the YouTube Help Center .
17 آوریل 2020
Note: This is a deprecation announcement.
YouTube is deprecating the channel bulletin feature. As a result, the activities.insert
method will be deprecated, and the activities.list
method will stop returning channel bulletins. These changes will be effective in the API on or after May 18, 2020. For more details, please see the YouTube Help Center .
31 مارس 2020
This update contains the following changes:
New resources and methods
The new
member
resource represents a channel member for a YouTube channel. A member provides recurring monetary support to a creator and receives special benefits. For example, members are able to chat when the creator turns on members-only mode for a chat.This resource replaces the
sponsor
resource, which is documented as part of the YouTube Live Streaming API. Thesponsor
resource is now deprecated and API clients should update calls to thesponsors.list
method to use themembers.list
method instead.The new
membershipsLevel
resource identifies a pricing level managed by the creator that authorized the API request. ThemembershipsLevels.list
method retrieves a list of all of the creator's membership levels.
10 ژانویه 2020
The API now supports the ability to identify child-directed content, which YouTube calls "made for kids." Learn more about "made for kids" content in the YouTube Help Center.
The channel
and video
resources support two new properties to enable content creators and viewers to identify content that is made for kids:
- The
selfDeclaredMadeForKids
property enables content creators to specify whether a channel or video is made for kids.
For channels, this property can be set when calling thechannels.update
method. For videos, this property can be set when calling either thevideos.insert
orvideos.update
methods.
Note that this property is only included in API responses that containchannel
orvideo
resources if the channel owner authorized the API request. - The
madeForKids
property enables any user to retrieve the "made for kids" status of a channel or video . For example, the status might be determined based on the value of theselfDeclaredMadeForKids
property. See the YouTube Help Center for more information about setting the audience for your channel, videos, or broadcasts.
We have also updated the YouTube API Services Terms of Service and Developer Policies. Please see the YouTube API Services Terms of Service - Revision History for more information. The changes to the YouTube API Services Terms of Service and Developer Policies will take effect on January 10, 2020 Pacific Time.
10 سپتامبر 2019
The API reference documentation has been updated to reflect a change to the way that subscriber counts are reported on YouTube and, consequently, in API responses. As a result of the change, subscriber counts returned by the YouTube Data API Service are rounded down to three significant figures for subscriber counts greater than 1000 subscribers. This change affects the channel
resource's statistics.subscriberCount property.
Note: This change affects this property value even in cases where a user sends an authorized request for data about their own channel. Channel owners can still see exact subscriber counts in YouTube Studio.
For example, if a channel has 123,456 subscribers, the statistics.subscriberCount
property will contain the value 123000
. The table below shows examples of how subscriber counts are rounded in API responses and abbreviated in other publicly visible YouTube user interfaces:
Example subscriber count | YouTube Data API | Publicly visible YouTube UIs |
---|---|---|
1,234 | 1230 | 1.23 هزار |
12,345 | 12300 | 12.3 هزار |
123,456 | 123000 | 123 هزار |
1,234,567 | 1230000 | 1.23 میلیون |
12,345,678 | 12300000 | 12.3 میلیون |
123,456,789 | 123000000 | 123M |
April 4, 2019
This update contains the following changes:
The API reference documentation has been updated to better explain common use cases for each method and to provide dynamic, high-quality code samples through the APIs Explorer widget. See the
channels.list
method's documentation for an example. There are now two new elements on pages that describe API methods:The APIs Explorer widget lets you select authorization scopes, enter sample parameter and property values, and then send actual API requests and see actual API responses. The widget also offers a fullscreen view that shows complete code samples, which dynamically update to use the scopes and values that you have entered.
The Common use cases section describes one or more common use cases for the method explained on the page. For example, you could call the
channels.list
method to retrieve data about a specific channel or to retrieve data about the current user's channel.You can use links in that section to populate the APIs Explorer with sample values for your use case or to open the fullscreen APIs Explorer with those values already populated. These changes aim to make it easier for you to see code samples that are directly applicable to the use case that you're trying to implement in your own application.
Code samples are currently supported for Java, JavaScript, PHP, Python, and curl.
The code samples tool has also been updated with a new UI that offers all of the same features described above. Using that tool, you can explore use cases for different methods, load values into the APIs Explorer, and open the fullscreen APIs Explorer to get code samples in Java, JavaScript, PHP, and Python.
In conjunction with this change, the pages that previously listed available code samples for Java, JavaScript, PHP, and Python have been removed.
The quickstart guides for Java , JavaScript , PHP , and Python have been updated. The revised guides explain how to run one sample with an API key and another sample with an OAuth 2.0 client ID using code samples from the APIs Explorer.
Note that the changes described above replace an interactive tool that had been added to the API documentation in 2017.
9 جولای 2018
This update contains the following changes:
The definition of the
channel
resource'ssnippet.thumbnails
property has been updated to note that when displaying thumbnails in your application, your code should use the image URLs exactly as they are returned in API responses. For example, your application should not use thehttp
domain instead of thehttps
domain in a URL returned in an API response.Beginning in July 2018, channel thumbnail URLs will only be available in the
https
domain, which is how the URLs appear in API responses. After that time, you might see broken images in your application if it tries to load YouTube images from thehttp
domain.Note: This is a deprecation announcement.
The
video
resource'srecordingDetails.location.altitude
property has been deprecated. There is no guarantee that videos will return values for this property. Similarly, even if API requests attempt to set a value for that property, it is possible that the incoming data will not be stored.
22 ژوئن 2018
The Implementation guide , formerly known as the Implementation and Migration guide, has been updated to remove instructions for migrating from the v2 API to the v3 API. In addition, instructions have also been removed for features that have since been deprecated in the v3 API, such as favorite videos.
27 نوامبر 2017
This update contains the following changes:
Note: This is a deprecation announcement.
YouTube is removing support for the Featured Video and Featured Website features, which are supported in the API via the
channel
resource'sinvideoPromotion
object. As a result, that object, including all of its child properties are being deprecated.You can still retrieve and set
invideoPromotion
data until December 14, 2017. After that date:- Attempts to retrieve the
invideoPromotion
part when callingchannels.list
will return an emptyinvideoPromotion
or will not return anyinvideoPromotion
data at all. - Attempts to update
invideoPromotion
data when callingchannels.update
will return a successful response until at least May 27, 2018, but they will be treated as no-ops, meaning that they will not actually perform an update.
After May 27, 2018, it is possible that these requests could return error messages to indicate, for example, that
invalidPromotion
is an invalid part.- Attempts to retrieve the
16 نوامبر 2017
This update contains the following changes:
The interactive code snippet tool now supports Node.js code samples. The samples are also visible in the documentation for almost all API methods, such as the
channels.list
method.The customizable samples are designed to give you a use-case-specific starting point for a Node.js application. The functionality is similar to the code in the Node.js quickstart guide . However, the samples do contain some utility functions that don't appear in the quickstart:
- The
removeEmptyParameters
function takes a list of key-value pairs corresponding to API request parameters and removes the parameters that don't have values. - The
createResource
function takes a list of key-value pairs corresponding to properties in an API resource. It then converts the properties into a JSON object that can be used ininsert
andupdate
operations. The example below shows a set of property names and values and the JSON object that the code would create for them:# Key-value pairs: {'id': 'ABC123', 'snippet.title': 'Resource title', 'snippet.description': 'Resource description', 'status.privacyStatus': 'private'} # JSON object: { 'id': 'ABC123', 'snippet': { 'title': 'Resource title', 'description': 'Resource description', }, 'status': { 'privacyStatus': 'private' } }
All of these samples are designed to be downloaded and run locally. For more information, see the prerequisites for running full code samples locally in the code snippet tool instructions.
- The
25 اکتبر 2017
This update contains the following changes:
The Python code samples in the interactive code snippet tool have been updated to use the
google-auth
andgoogle-auth-oauthlib
libraries instead of theoauth2client
library, which is now deprecated.In addition to that change, the tool now provides full code samples for installed Python applications and Python web server applications, which use slightly different authorization flows. To see the full samples (and this change):
- Go to the interactive code snippet tool or to the documentation for any API method, such as the
channels.list
method. - Click the
Python
tab above the code samples. - Click the toggle above the tabs to switch from seeing a snippet to a full sample.
- The tab should now show a complete code sample that uses the
InstalledAppFlow
authorization flow. The description above the sample explains this and also links to a sample for a web server application. - Click the link to switch to the web server example. That sample uses the Flask web application framework and a different authorization flow.
All of these samples are designed to be downloaded and run locally. If you'd like to run the samples, see the instructions for running full code samples locally in the code snippet tool instructions.
- Go to the interactive code snippet tool or to the documentation for any API method, such as the
29 آگوست 2017
This update contains the following changes:
- The definition of the
search.list
method'sforContentOwner
parameter has been updated to note that if that parameter is set totrue
, thetype
parameter must be set tovideo
. - The definition of the
search.list
method'sregionCode
parameter has been updated to clarify that the parameter restricts search results to videos that can be viewed in the specified region. - YouTube has updated its branding logos and icons. New "developed with YouTube" logos can be downloaded from the branding guidelines page. Other new YouTube logos and icons are also shown on that page and can be downloaded from the YouTube brand site .
24 جولای 2017
This update contains the following changes:
- A new YouTube Data API quickstart guide is available for iOS . The guide explains how to use the YouTube Data API in a simple iOS application written in either Objective-C or Swift.
- The interactive code snippet tool for the YouTube Data API now includes documentation explaining some of the tool's features:
- Executing API requests
- Toggling between code snippets and full code samples
- Using boilerplate functions
- Loading existing resources (for update methods)
Note: The tool is also embedded in API reference documentation for API methods ( example ).
1 ژوئن 2017
This update contains the following changes:
Note: This is a deprecation announcement.
The following
video
resource properties are being deprecated. While the properties will be supported until December 1, 2017, there is no guarantee that videos will continue to return values for those properties until that time. Similarly,videos.insert
andvideos.update
requests that set those property values will not generate errors before that date, but it is possible that the incoming data will not be stored.
17 مه 2017
This update contains the following changes:
The API reference documentation has been updated to make code snippets more ubiquitous and interactive. Pages that explain API methods, like
channels.list
orvideos.rate
, now feature an interactive tool that lets you view and customize code snippets in Java, JavaScript, PHP, Python, Ruby, Apps Script, and Go.For any given method, the tool shows code snippets for one or more use cases, and each use case describes a common way of calling that method. For example, you can call the
channels.list
method to retrieve data about a specific channel or about the current user's channel.You can also interact with code samples:
Modify parameter and property values, and the code snippets dynamically update to reflect the values you provide.
Toggle between code snippets and full samples. A code snippet shows the portion of the code that calls the API method. A full sample contains that snippet as well as boilerplate code for authorizing and sending requests. Full samples can be copied and run from the command line or a local web server.
Execute requests by clicking a button. (To execute requests, you need to authorize the tool to call the API on your behalf.)
Note that this tool has replaced the APIs Explorer on the pages where it is available. (Each page displays a link so that you also have the option of loading the request you are working on in the APIs Explorer.)
The Data API Code Snippets tool has also been updated with a new UI that offers all of the same features described above. The major new features available on this page are:
- Support for API requests that write data.
- Support for Java samples.
- More flexible and comprehensive boilerplate code for authorizing users and building API requests.
27 آوریل 2017
This update contains the following changes:
- New quickstart guides explain how to set up a simple application that makes YouTube Data API requests. Guides are currently available for Android , Apps Script , Go , Java , JavaScript , Node.js , PHP , Python , and Ruby .
30 مارس 2017
This update contains the following changes:
- The
channel
resource's newtopicDetails.topicCategories[]
property contains a list of Wikipedia URLs that describe the channel's content. The URLs correspond to the topic IDs returned in the resource'stopicDetails.topicIds[]
property. - The
playlistItem
resource's newcontentDetails.videoPublishedAt
property identifies the time that the video was published to YouTube. The resource already contains thesnippet.publishedAt
property, which identifies the time that the item was added to the playlist. - Like the
channel
resource, thevideo
resource now returns thetopicDetails.topicCategories[]
property, which contains a list of Wikipedia URLs that describe the video's content. Forvideo
resources, the URLs correspond to the topic IDs returned in the resource'stopicDetails.relevantTopicIds[]
property. - The
video
resource's newcontentDetails.contentRating.mpaatRating
property identifies the rating that the Motion Picture Association of America gave to a movie trailer or preview.
27 فوریه 2017
As originally announced on August 11, 2016 , YouTube has switched the supported list of topic IDs to a curated list. The complete list of supported topic IDs is included in the topicDetails
properties for channel
and video
resources as well as in the search.list
method's topicId
parameter.
Note that there are several changes to the curated list:
- The following topics have been added as subtopics of
Society
:نام topic ID کسب و کار /m/09s1f
سلامتی /m/0kt51
نظامی /m/01h6rj
سیاست /m/05qt0
دین /m/06bvp
- The
Animated cartoon
topic, previously a child ofEntertainment
, has been removed. - The
Children's music
topic, previously a child ofMusic
, has been removed.
As a result of this change, topics related to a video are now always returned in the video
resource's topicDetails.relevantTopicIds[]
property value.
29 نوامبر 2016
This update contains the following changes:
There are three small changes to the list of topic IDs that will be supported as of February 10, 2017:
- The
Professional wrestling
category, which was previously a child of theSports
category, is now a child ofEntertainment
. - The
TV shows
category, which is a child ofEntertainment
, is new. - The
Health
category, previously a child ofLifestyle
, has been removed.
Also note that there are a few parent categories (
Entertainment
,Gaming
,Lifestyle
,Music
, andSports
). Any video that is associated with a child category, likeTennis
, will also be associated with the parent category (Sports
).- The
10 نوامبر 2016
This update contains the following changes:
As first announced on August 11, 2016 , the deprecation of Freebase and the Freebase API requires several changes related to topic IDs. Topic IDs identify topics associated with
channel
andvideo
resources, and you can also use thetopicId
search parameter to find channels or videos related to a particular topic.On February 10, 2017, YouTube will start returning a small set of topic IDs instead of the much more granular set of IDs returned thus far. In addition, note that channels and videos are not guaranteed to be associated with any topics, which is consistent with current API behavior.
So that you can prepare your API Clients for those changes, the definitions of the following API parameters and properties have been updated to list the topic IDs that will be supported after that time. Note that the list of categories is the same for all of the properties.
- The
channel
resource'stopicDetails.topicIds[]
property. - The
video
resource'stopicDetails.relevantTopicIds[]
property. - The
search.list
method'stopicId
parameter.
- The
Note: This is a deprecation announcement.
The following properties are being deprecated:
- The
channel
resource'stopicDetails.topicIds[]
property. This property will be supported until November 10, 2017. - The
video
resource'stopicDetails.relevantTopicIds[]
property. This property will be supported until November 10, 2017. - The
video
resource'stopicDetails.topicIds[]
property. This property will not contain values after February 10, 2017. (After that date, thetopicDetails.relevantTopicIds[]
property value will identify all of the topics associated with a video.)
- The
Since Freebase has already been deprecated, the Searching with Freebase Topics guide has been removed from the documentation. That guide provided code samples to show how an application would work with the Freebase API.
In addition, several code samples related to topic IDs have been removed from the
search.list
method's documentation.
2 نوامبر 2016
This update contains the following changes:
New properties and parameters
The
video
resource contains several new properties:The
player.embedHtml
property contains an<iframe>
tag that you can use to embed a player that plays the video. The newplayer.embedHeight
andplayer.embedWidth
properties identify the dimensions of the embedded player. These properties are only returned if the API request specifies a value for at least one of themaxHeight
ormaxWidth
parameters. Those two new parameters are explained later in this revision history entry.The new
hasCustomThumbnail
property indicates whether the video uploader has provided a custom thumbnail image for the video. Note that this property is only visible to the video uploader.The new
fpbRatingReasons[]
identifies reasons that the video received its FPB (South Africa) rating.The new
mcstRating
identifies the rating that the video received in Vietnam.
The
videos.list
method supports two new parameters,maxHeight
andmaxWidth
. You can use either parameter or both parameters when retrieving theplayer
part invideo
resources.By default, the height of the
<iframe>
returned in theplayer.embedHtml
property is 360px. The width adjusts to match the video's aspect ratio, thereby ensuring that the embedded player does not have black bars framing the video. So, for example, if a video's aspect ratio is 16:9, the player's width would be 640px.With the new parameters, you can specify that instead of the default dimensions, the embed code should use a height and/or width appropriate for your application layout. The API server scales the player dimensions as appropriate to ensure that the embedded player does not have black bars framing the video. Note that both parameters specify the maximum dimensions of the embedded player. Thus, if both parameters are specified, one dimension might still be smaller than the maximum amount allowed for that dimension.
For example, suppose a video has a 16:9 aspect ratio. Thus, the
player.embedHtml
tag would contain a 640x360 player if themaxHeight
ormaxWidth
parameter is not set.- If the
maxHeight
parameter is set to720
, and themaxWidth
parameter is not set, the API would return a 1280x720 player. - If the
maxWidth
parameter is set to960
, and themaxHeight
parameter is not set, the API would return a 960x540 player. - If the
maxWidth
parameter is set to960
, and themaxHeight
parameter is set to450
, the API would return an 800x450 player.
The new
player.embedHeight
andplayer.embedWidth
properties, which are described above, identify the player's dimensions.- If the
Updates to existing methods, properties and parameters
The
channelSection
resource description has been updated to note that a channel can create a maximum of 10 shelves without setting targeting data and can create a maximum of 100 shelves with targeting data.In addition, the
channelSection
resource'stargeting
property has been updated to reflect the fact that targeting options can only be set using the API. Targeting options are deleted if the channel section is modified using the user interface on the YouTube website.The definition of the
i18nLanguage
resource'ssnippet.name
property has been corrected to reflect that the value represents a language's name as it is written in the language specified by thei18nLanguage.list
method'shl
parameter.The
playlistItem
resource'scontentDetails.note
property has been updated to note that the property value's maximum length is 280 characters.The
playlistItem
resource'scontentDetails.startAt
andcontentDetails.endAt
properties have been deprecated. These fields are ignored if they are set inplaylistItems.insert
orplaylistItems.update
requests.The
playlistItems.delete
andplaylistItems.update
methods now support theonBehalfOfContentOwner
parameter, which is already supported for several other methods. Requests that use that method also need to be authorized with a token that provides access to thehttps://www.googleapis.com/auth/youtubepartner
scope.The
search.list
method'spublishedBefore
andpublishedAfter
parameters have both been updated to indicate that the parameter values are inclusive. So, for example, if thepublishedBefore
parameter is set, the API returns resources created before or at the specified time.The
video
resource'scontentDetails.contentRating.grfilmRating
property supports three additional values:grfilmK12
,grfilmK15
, andgrfilmK18
.The
videos.insert
method description has been updated to note that the maximum file size for uploaded videos has increased from 64GB to 128GB.
New and updated errors
The API supports the following new errors:
نوع خطا جزئیات خطا شرح forbidden (403)
homeParameterDeprecated
The activities.list
method returns this error to indicate that the user's home page activity data is not available through this API. This error might occur if you set thehome
parameter totrue
in an unauthorized request.invalidValue (400)
invalidContentDetails
The playlistItems.insert
method returns this error to indicate that thecontentDetails
object in the request is invalid. One reason that this error occurs is that thecontentDetails.note
field is longer than 280 characters.forbidden (403)
watchHistoryNotAccessible
The playlistItems.list
method returns this error to indicate that the request tried to retrieve "watch history" playlist items, but those cannot be retrieved using the API.forbidden (403)
watchLaterNotAccessible
The playlistItems.list
method returns this error to indicate that the request tried to retrieve "watch later" playlist items, but those cannot be retrieved using the API.badRequest (400)
uploadLimitExceeded
The videos.insert
method returns this error to indicate that the channel has exceeded the number of videos that it may upload.forbidden (403)
forbiddenEmbedSetting
The videos.update
method returns this error to indicate that the API request attempts to set an invalid embed setting for the video. Note that some channels may not have permission to offer embedded players for live streams. See the YouTube Help Center for more information.The
playlistItems.insert
method no longer returns an error if you insert a duplicate video into a playlist. That error previously occurred for some playlists, like favorite videos, that did not allow duplicates but are no longer supported. In general, playlists do allow duplicate videos.
Other updates
The revision history entry for September 15, 2016, has been updated to clarify that, whenever the
channel
resource'scontentDetails.relatedPlaylists.watchHistory
andcontentDetails.relatedPlaylists.watchLater
properties are included in a response, they always contain the valuesHL
andWL
, respectively. Moreover, those properties are only included if an authorized user is retrieving data about the user's own channel.
15 سپتامبر 2016
This update contains the following changes:
The August 11, 2016, revision history update discussed several changes related to topic IDs, including the fact that the set of supported topic IDs will change as of February 10, 2017. The list of topics that will be supported will be published by November 10 ، 2016.
The following changes are now in effect. Notice of these changes was given in the revision history update on August 11, 2016:
If the
activities.list
method is called with thehome
parameter set totrue
, the API response now contains items similar to what a logged-out YouTube user would see on the home page.This is a slight change that is intended to provide a better user experience than the behavior described in the revision history update on August 11, 2016. That update had stated that requests using the
home
parameter would return an empty list.The
channel
resource'scontentDetails.relatedPlaylists.watchHistory
andcontentDetails.relatedPlaylists.watchLater
properties now contain values ofHL
andWL
, respectively, for all channels.To be clear, these properties are only visible to an authorized user retrieving data about the user's own channel. The properties always contain the values
HL
andWL
, even for an authorized user retrieving data about the user's own channel. Thus, the watch history and watch later playlist IDs cannot be retrieved via the API.In addition, requests to retrieve playlist details (
playlists.list
) or playlist items (playlistItems.list
) for a channel's watch history or watch later playlist now return empty lists. This behavior is true for the new values,HL
andWL
, as well as for any watch history or watch later playlist IDs that your API Client may have already stored.
The
video
resource'sfileDetails.recordingLocation
object and its child properties are no longer returned. Previously, this data (like the parentfileDetails
object) could only be retrieved by a video's owner.
11 آگوست 2016
This update contains the following changes:
The newly published YouTube API Services Terms of Service ("the Updated Terms"), discussed in detail on the YouTube Engineering and Developers Blog , provides a rich set of updates to the current Terms of Service. In addition to the Updated Terms , which will go into effect as of February 10, 2017, this update includes several supporting documents to help explain the policies that developers must follow.
The full set of new documents is described in the revision history for the Updated Terms . In addition, future changes to the Updated Terms or to those supporting documents will also be explained in that revision history. You can subscribe to an RSS feed listing changes in that revision history from a link in that document.
The deprecation of Freebase and the Freebase API is causing several changes related to topic IDs. Topic IDs are used in the following API resources and methods:
- The
channel
resource'stopicDetails
part identifies topics associated with the channel. - The
video
resource'stopicDetails
part identifies topics associated with the video. - The
search.list
method'stopicId
parameter lets you search for videos or channels related to a particular topic.
The changes to these features are:
As of February 10, 2017, YouTube will start returning a small set of topic IDs instead of the much more granular set of IDs returned thus far. That set of supported topics will identify high-level categorizations like Sports or Basketball , but, for example, they will not identify specific teams or players. We will be announcing the set of supported topics so that you have time to prepare your application for this change.
Any Freebase topic IDs that you have already retrieved can be used to search for content until February 10, 2017. However, after that time, you will be able to use only the smaller set of topics identified in the previous item to retrieve search results by موضوع.
After February 10, 2017, if you try to search for results using a topic ID that is not in the smaller set of supported topic IDs, the API will return an empty result set.
- The
Several API fields and parameters are being deprecated effective September 12, 2016:
The
activities.list
method'shome
parameter enabled an authorized user to retrieve the activity feed that would display on the YouTube home page for that user. Requests that use this parameter after September 12, 2016, will return an empty list.The
channel
resource'scontentDetails.relatedPlaylists.watchHistory
andcontentDetails.relatedPlaylists.watchLater
properties are only visible to an authorized user retrieving data about the user's own channel. After September 12, 2016, thecontentDetails.relatedPlaylists.watchHistory
will return a value ofHL
and thecontentDetails.relatedPlaylists.watchLater
property will return a value ofWL
for all channels.Requests to retrieve playlist details (
playlists.list
) for a channel's watch history or watch later playlist will return an empty list after September 12, 2016. Requests to retrieve playlist items (playlistItems.list
) in either of those playlists will also return an empty list after that time. This is true for the new values,HL
andWL
, as well as for any watch history or watch later playlist IDs that your API Client may have already stored.The
video
resource'sfileDetails.recordingLocation
object or any of its child properties will no longer be returned after September 12, 2016. This data can only be retrieved by a video's owner since the parentfileDetails
object can only be retrieved by a video owner.
13 ژوئن 2016
This update contains the following changes:
The
channel
resource'scontentDetails.googlePlusUserId
property has been deprecated. Previously, the property was only present if the channel was associated with a Google+ profile. Following the deprecation, the property will no longer be included in anychannel
resources.The
comment
resource'ssnippet.authorGoogleplusProfileUrl
property has been deprecated. Previously, the property was only present if the channel was associated with a Google+ profile. Following the deprecation, the property will no longer be included in anycomment
resources.
Since neither of these properties will be returned following the deprecation, both properties have been removed from the corresponding resource documentation.
31 مه 2016
This update contains the following changes:
The
subscriptions.list
method's newmyRecentSubscribers
parameter retrieves a list of the subscribers of the authenticated user's channel in reverse chronological order of the time that they subscribed to the channel.Note that the new parameter only supports retrieval of the most recent 1000 subscribers to the authenticated user's channel. To retrieve a complete list of subscribers, use the
mySubscribers
parameter. That parameter, which does not return subscribers in a particular order, does not limit the number of subscribers that can be retrieved.The definition of the
snippet.thumbnails.(key)
property has been updated for the activity , playlistItem , playlist , search result , thumbnail , and video resources to note that additional thumbnail image sizes are available for some videos.- The
standard
image is 640px wide and 480px tall. - The
maxres
image is 1280px wide and 720px tall.
- The
The definition of the
channelSection.list
method'spart
parameter has been updated to note that thetargeting
part can be retrieved at a cost of2
quota units.The
videos.list
method now returns a forbidden (403
) error when an improperly authorized request tries to retrieve thefileDetails
,processingDetails
, orsuggestions
parts of avideo
resource. Those parts are only available to the video's owner.
17 مه 2016
The new Data API Code Snippets tool provides short code snippets for common YouTube Data API use cases. Code snippets are currently available for all read-only API methods in Apps Script, Go, JavaScript, PHP, Python, and Ruby.
For each method, the tool shows code samples for one or more use cases. For example, it provides five code snippets for the search.list
method:
- List videos by keyword
- List videos by location
- List live events
- Search for the authenticated user's videos
- List related videos
For each use case, the tool displays the parameters used in the API request. You can modify the parameter values, in which case the tool updates the code snippets to reflect the parameter values that you provided.
Finally, the tool displays the API response to each request. If you have modified the request parameters, the API response is based on your provided parameter values. Note that you need to authorize the tool to submit requests on your behalf for API responses to display.
28 آوریل 2016
This update contains the following changes:
The
video
resource's newcontentDetails.projection
property specifies the video's projection format. Valid property values are360
andrectangular
.The
video
resource'srecordingDetails.location
andfileDetails.recordingLocation
properties have both been updated to explain the difference between the two properties:- The
recordingDetails.location
property identifies the location that the video owner wants to associate with the video. This location is editable, searchable on public videos, and might be displayed to users for public videos. - The
fileDetails.recordingLocation
property value is immutable and represents the location associated with the original, uploaded video file. The value is only visible to the video owner.
- The
The definition of the
channel
resource'scontentDetails.relatedPlaylists.favorites
property has been updated to note that the property value might contain a playlist ID that refers to an empty playlist and that cannot be fetched. This is due to the fact that favorite videos functionality has already been deprecated. Note that this property is not subject to the API deprecation policy .The definition of the
ineligibleAccount
error, which can be returned by thecomments.insert
,comments.update
,commentThreads.insert
, orcommentThreads.update
method, has been updated to reflect that the error occurs when the YouTube account used to authorize the API request has not been merged with the user's Google account.
20 آوریل 2016
This update contains the following changes:
The definition of the
channels.update
method'spart
parameter has been updated to note thatlocalizations
is also a valid value for that parameter.The Quota Usage section of the Getting Started guide has been updated to link to the Google Developer's Console, where you can see your actual quota and quota usage.
16 مارس 2016
This update contains the following changes:
Updates to existing resources and methods
The
channelBanner
resource documentation has been updated to note that the recommended size for the uploaded channel banner image is 2560px by 1440px. The minimum size (2048px by 1152px) has not changed.The
channel
resource's newsnippet.customUrl
property identifies the custom URL associated with the channel. (Not all channels have custom URLs.) The YouTube Help Center explains eligibility requirements for getting a custom URL as well as how to set up the URL.The
channel
resource'sbrandingSettings.watch
object and all of its child properties have been deprecated.The API response to a
search.list
request now contains aregionCode
property. The property identifies the region code that was used for the search query. The region code instructs the API to return search results for the specified country.The property value is a two-letter ISO country code that identifies the region. The
i18nRegions.list
method returns a list of supported regions. The default value isUS
. If a non-supported region is specified, YouTube might still select another region, rather than the default value, to handle the query.The definitions of the
videoAbuseReportReason
resource'ssnippet.label
andsnippet.secondaryReasons[].label
properties have been updated to note that the properties contain localized label text for the abuse report reasons.In addition, the
videoAbuseReportReasons.list
method now supports thehl
parameter, which specifies the language that should be used for label text in the API response. The default parameter value isen_US
.The
video
resource's newcontentDetails.contentRating.ecbmctRating
property identifies a video's rating from Turkey's Evaluation and Classification Board of the Ministry of Culture and Tourism.In addition, API properties for other rating systems support the following new property values:
-
contentDetails.contentRating.fpbRating
(South Africa)
Rating: 10; property value:fpb10
-
contentDetails.contentRating.moctwRating
(Taiwan)
Rating: R-12; property value:moctwR12
-
contentDetails.contentRating.moctwRating
(Taiwan)
Rating: R-15; property value:moctwR15
-
The
video
resource'sliveStreamingDetails.activeLiveChatId
property contains the ID of the active live chat associated with the video. The property value is only present if the video is a current live broadcast that has live chat enabled. After the broadcast ends and the live chat concludes, the property is no longer returned for the video.The
video
resource'sstatus.rejectionReason
property supports the new property valuelegal
.
The API supports the following new errors:
نوع خطا جزئیات خطا شرح badRequest (400)
notEditable
The channelSections.insert
,channelSections.update
, andchannelSections.delete
methods return this error to indicate that the specified channel section cannot be created, updated, or deleted.badRequest (400)
styleRequired
The channelSections.insert
andchannelSections.update
methods return this error to indicate that thechannelSection
resource submitted in the API request must specify a value for thesnippet.style
property.badRequest (400)
typeRequired
The channelSections.insert
andchannelSections.update
methods return this error to indicate that thechannelSection
resource submitted in the API request must specify a value for thesnippet.type
property.badRequest (400)
processingFailure
The commentThreads.list
method returns this error to indicate that the API server failed to successfully process the request. While this can be a transient error, it usually indicates that the request's input is invalid. Check the structure of thecommentThread
resource in the request body to ensure that it is valid.forbidden (403)
commentsDisabled
The commentThreads.list
method returns this error to indicate that the video identified by thevideoId
parameter has disabled comments.badRequest (400)
commentTextTooLong
The commentThreads.insert
method returns this error to indicate that thecomment
resource that is being inserted contains too many characters in thesnippet.topLevelComment.snippet.textOriginal
property.invalidValue (400)
videoAlreadyInAnotherSeriesPlaylist
The playlistItems.insert
method returns this error to indicate that the video that you are trying to add to the playlist is already in another series playlist. See the YouTube Help Center for more information about series playlists.badRequest (400)
subscriptionForbidden
The subscriptions.insert
method returns this error to indicate that you have reached your maximum number of subscriptions or that you have created too many recent subscriptions. In the latter case, you can retry the request after a few hours.badRequest (400)
invalidCategoryId
The videos.update
method returns this error to indicate that thesnippet.categoryId
property in the uploadedvideo
resource specified an invalid category ID. Use thevideoCategories.list
method to retrieve supported categories.badRequest (400)
invalidDescription
The videos.update
method returns this error to indicate that thesnippet.description
property in the uploadedvideo
resource specified an invalid value.badRequest (400)
invalidPublishAt
The videos.update
method returns this error to indicate that thestatus.publishAt
property in the uploadedvideo
resource specified an invalid scheduled publishing time.badRequest (400)
invalidRecordingDetails
The videos.update
method returns this error to indicate that therecordingDetails
object in the uploadedvideo
resource specified invalid recording details.badRequest (400)
invalidTags
The videos.update
method returns this error to indicate that thesnippet.tags
property in the uploadedvideo
resource specified an invalid value.badRequest (400)
invalidTitle
The videos.update
method returns this error to indicate that thesnippet.title
property in the uploadedvideo
resource specified an invalid or empty video title.badRequest (400)
invalidVideoMetadata
The videos.update
method returns this error to indicate that the request metadata is invalid. This error occurs if the request updates thesnippet
part of avideo
resource but does not set a value for both thesnippet.title
andsnippet.categoryId
properties.
18 دسامبر 2015
European Union (EU) laws require that certain disclosures must be given to and consents obtained from end users in the EU. Therefore, for end users in the European Union, you must comply with the EU User Consent Policy . We have added a notice of this requirement in our YouTube API Terms of Service .
19 نوامبر 2015
The API now supports the ability to set and retrieve localized text for the snippet.title
and snippet.description
properties of the playlist
and video
resources, the snippet.title
property of the channelSection
resource, and the snippet.description
property of the channel
resource.
Setting localized titles and descriptions
You can set localized values for a resource when calling the
insert
orupdate
method for that resource. To set localized values for a resource, do both of the following:Ensure that a value is set for the resource's
snippet.defaultLanguage
property. That property identifies the language of the resource'ssnippet.title
andsnippet.description
properties. Its value can be any supported application language or most other ISO 639-1:2002 language codes. For example, if you upload a video that has an English title and description, you would set thesnippet.defaultLanguage
property toen
.Note for updating
channel
resources: To set thesnippet.defaultLanguage
property for achannel
resource, you actually need to update thebrandingSettings.channel.defaultLanguage
property.Add the
localizations
object to the resource you are updating. Each object key is a string that identifies an application language or ISO 639-1:2002 language code, and each key maps to an object that contains the localized title (and description) for the resource.The sample snippet below sets the resource's default language to English. It also adds localized German and Spanish titles and descriptions to a video:
{ "kind": "youtube#video", ... "snippet": { "title": "Playing soccer", "description": "We play soccer in the park on Sundays.", "defaultLanguage": "en", ... }, "localizations": "de": { "title": "Fußball spielen", "description": "Wir spielen Fußball im Park am Sonntag" }, "es": { "title": "Jugar al fútbol", "description": "Nosotros jugamos fútbol en el parque los domingos", } } }
Important: Remember that when you update the localized data for a resource, your API request must include all of the existing localized versions of the data. For example, if you sent a subsequent request to add Portuguese data to the video in the example above, the request would need to include the localized data for German, Spanish, and Portuguese.
Retrieving localized values
The API supports two ways to retrieve localized values for a resource:
Add the
hl
parameter to yourchannels.list
,channelSections.list
,playlists.list
, orvideos.list
request to retrieve localized data for a specific application language that the YouTube website supports . If localized resource details are available in that language, the resource'ssnippet.localized
object will contain the localized values. However, if localized details are not available, thesnippet.localized
object will contain resource details in the resource's default language .For example, suppose a
videos.list
request retrieved data for the video described above with localized German and Spanish data. If thehl
parameter were set tode
, the resource would contain the following data:{ "kind": "youtube#video", ... "snippet": { "title": "Playing soccer", "description": "We play soccer in the park on Sundays.", "defaultLanguage": "en", "localized": { "title": "Fußball spielen", "description": "Wir spielen Fußball im Park am Sonntag" } ... } }
However, if the
hl
parameter were set tofr
, thesnippet.localized
object would contain the English title and description because English is the default language for the resource, and localized French details are not available.Important: Thehl
parameter only supports values that identify application languages that the YouTube website supports. To determine whether localized text is available for other languages, you need to retrieve thelocalizations
part for the resource and filter to determine whether the localized text exists.
For example, you would need to retrieve the full list of localizations to determine whether localized text is available in Appalachian English.When retrieving a resource, include
localizations
in thepart
parameter value to retrieve all of the localized details for that resource. If you are retrieving localized data for a language that is not a current YouTube application language , you need to use this approach to retrieve all localizations and then filter to determine whether the desired localized data exists.
Errors related to localized text values
The API also supports the following new errors for localized text values:
نوع خطا جزئیات خطا شرح badRequest (400)
defaultLanguageNotSetError
This error indicates that a request that tries to insert or update the localizations
object for a resource is failing because thesnippet.defaultLanguage
property is not set for that resource. Thechannels.update
,channelSections.insert
,channelSections.update
,playlists.insert
,playlists.update
,videos.insert
, andvideos.update
methods support this error.badRequest (400)
localizationValidationError
This error indicates that one of the values in a resource's localizations
object failed to validate. For example, this error might occur if the object contains an invalid language code. Thechannels.update
,channelSections.insert
,channelSections.update
,playlists.insert
, andplaylists.update
methods support this error.
4 نوامبر 2015
This update contains the following changes:
Updates to existing resources and methods
The
search.list
method'sorder
parameter has been updated to note that if you sort live broadcasts byviewCount
, the API results are sorted by the broadcasts' number of concurrent viewers while the broadcasts are still ongoing.The
search.list
method'srelatedToVideoId
parameter has been updated to note that if the parameter is set, the only other supported parameters arepart
,maxResults
,pageToken
,regionCode
,relevanceLanguage
,safeSearch
,type
(which must be set tovideo
), andfields
. This update does not reflect a change in API behavior.The definition of the
video
resource'ssnippet.publishedAt
property has been updated to note that the property value, which specifies the date and time that the video was published, might be different than the time that the video was uploaded. For example, if a video is uploaded as a private video and then made public at a later time, the property value specifies the time that the video was made public. The updated definition also explains how the value is populated for private and unlisted videos.This change does not reflect a change in API behavior.
The definition of the
video
resource'sstatus.publishAt
property has been updated to note:- If you set this property's value when calling the
videos.update
method, you must also set thestatus.privacyStatus
property value toprivate
even if the video is already private. - If the request schedules a video to be published at some time in the past, it is published right away. As such, the effect of setting the
status.publishAt
property to a past date and time is the same as of changing the video'sprivacyStatus
fromprivate
topublic
.
- If you set this property's value when calling the
The
video
resource'scontentDetails.contentRating.cncRating
property specifies the video's rating from France's Commission de classification cinematographique. This property replaces thecontentDetails.contentRating.fmocRating
property, which is now deprecated.The definition of the
channel
resource's brandingSettings.channel.keywords has been updated to correctly reflect that the property value contains a space-separated list of strings and not a comma-separated list, as previously documented. This update does not reflect a change in API behavior.The documentation for the
thumbnails.set
method has been updated to accurately reflect that the body of the request contains the thumbnail image that you are uploading and associating with a video. The request body does not contain athumbnail
resource. Previously, the documentation said that you should not provide a request body when calling this method. This update does not reflect a change in API behavior.The description of the
activity
resource has been updated to reflect the fact that theactivities.list
method does not currently include resources related to new video comments. The resource'ssnippet.type
andcontentDetails.comment
have been updated as well.
New and updated errors
The API now supports the following errors:
جزئیات خطا activities.insert
HTTP Response Code badRequest (400)
دلیل invalidMetadata
شرح The kind
property does not match the type of ID provided.commentThreads.update
comments.insert
comments.update
HTTP Response Code badRequest (400)
دلیل commentTextTooLong
شرح The comment
resource that is being inserted or updated contains too many characters in thesnippet.topLevelComment.snippet.textOriginal
property.playlistItems.insert
playlistItems.update
HTTP Response Code forbidden (403)
دلیل playlistItemsNotAccessible
شرح The request is not properly authorized to insert, update, or delete the specified playlist item. playlists.delete
playlists.insert
playlists.update
HTTP Response Code badRequest (400)
دلیل playlistForbidden
شرح This operation is forbidden or the request is not properly authorized. search.list
HTTP Response Code badRequest (400)
دلیل invalidLocation
شرح The location
and/orlocationRadius
parameter value was formatted incorrectly.search.list
HTTP Response Code badRequest (400)
دلیل invalidRelevanceLanguage
شرح The relevanceLanguage
parameter value was formatted incorrectly.subscriptions.insert
HTTP Response Code badRequest (400)
دلیل subscriptionForbidden
شرح This error occurs when any of the following are true: - The subscription that you are trying to create already exists
- You have already reached your maximum number of subscriptions
- You are trying to subscribe to your own channel, which is not supported.
- You have created too many subscriptions recently and need to wait a few hours before retrying the request.
videos.update
HTTP Response Code badRequest (400)
دلیل invalidDefaultBroadcastPrivacySetting
شرح The request attempts to set an invalid privacy setting for the default broadcast.
28 آگوست 2015
This update contains the following changes:
Updates to existing resources and methods
The
video
resource'sstatistics.favoriteCount
property has been deprecated.In accordance with our deprecation policy, this property will continue to be included in
video
resources for at least one year after this announcement. However, the property value is now always set to0
.
7 آگوست 2015
This update contains the following changes:
Updates to existing resources and methods
The definition of the
video
resource'ssnippet.tags[]
property has been updated to provide more information about how the API server calculates the length of the property's value. Note that this update does not reflect a change in the API's behavior.Specifically, the definition now explains that if a tag contains a space, the API server handles the tag value as though it were wrapped in quotation marks, and the quotation marks count toward the character limit. So, for the purposes of character limits, the tag Foo-Baz contains seven characters, but the tag Foo Baz contains nine characters.
The
commentThreads.insert
method no longer supports theshareOnGooglePlus
parameter, which previously indicated whether a comment and replies to that comment should also be posted to the author's Google+ profile. If a request submits the parameter, the API server ignores the parameter but otherwise handles the request.
18 ژوئن 2015
This update contains the following changes:
Updates to existing resources and methods
The
commentThreads.list
method's neworder
parameter specifies the order in which the API response should list comment threads. Threads can be ordered by time or relevance. The default behavior is to order them by time.The
video
resource's newsnippet.defaultAudioLanguage
property specifies the language spoken in the video's default audio track.The definition of the
video
resource'scontentDetails.licensedContent
property has been updated to clarify that the content must have been originally uploaded to a channel linked to a YouTube content partner and then claimed by that partner. This does not represent a change in actual API behavior.The
captions.delete
,captions.download
,captions.insert
,captions.list
, andcaptions.update
methods now support theonBehalfOfContentOwner
parameter, which is already supported for several other methods. Requests that use that method also need to be authorized with a token that provides access to thehttps://www.googleapis.com/auth/youtubepartner
scope.
New and updated errors
The API now supports the following errors:
جزئیات خطا videos.rate
HTTP Response Code badRequest (400)
دلیل emailNotVerified
شرح The user must verify her email address prior to rating the video. videos.rate
HTTP Response Code badRequest (400)
دلیل videoPurchaseRequired
شرح Rental videos can only be rated by users who rented them. The
subscriptions.delete
andsubscriptions.insert
methods no longer support theaccountClosed
andaccountSuspended
errors.
27 آوریل 2015
This update contains the following changes:
New resources and methods
The new
videoAbuseReportReason
resource contains information about a reason that a video would be flagged for containing abusive content. ThevideoAbuseReportReasons.list
method lets you retrieve a list of all of the reasons why videos might be flagged.The new
videos.reportAbuse
method provides a way to actually flag a video that contains abusive content. The body of the request contains a JSON object that specifies the video being flagged as well as the reason that the video is deemed to contain abusive content. Valid reasons can be obtained from thevideoAbuseReportReason.list
method described above.The migration guide has also been updated with an example for reporting an abusive video. With this change, the v3 API now supports all of the v2 API features that it is scheduled to support. These features are also all explained in the migration guide.
Updates to existing resources and methods
The
search.list
method's newforDeveloper
filter parameter restricts a search to only retrieve videos uploaded via the developer's application or website. TheforDeveloper
parameter can be used in conjunction with optional search parameters like theq
parameter.For this feature, each uploaded video is automatically tagged with the project number that is associated with the developer's application in the Google Developers Console .
When a search request subsequently sets the
forDeveloper
parameter totrue
, the API server uses the request's authorization credentials to identify the developer. Therefore, a developer can restrict results to videos uploaded through the developer's own app or website but not to videos uploaded through other apps or sites.The new feature offers functionality that is similar, albeit not identical, to the developer tags functionality that the v2 API supported.
The
channel
resource's newsnippet.country
property lets channel owners associate their channels with a particular country.Note: To set the
snippet.country
property for achannel
resource, you actually need to update thebrandingSettings.channel.country
property.The API now supports targeting for
channelSection
resources. Channel section targeting provides a way to restrict visibility of a content section to users that match particular criteria.The API exposes three targeting options. A user must meet all of the targeting settings for a channel section to be visible.
targeting.languages[]
: A list of YouTube application languages . Users who have chosen one of those languages can see the corresponding channel section.targeting.regions[]
: A list of YouTube preferred content regions . The channel section is visible to users that have selected one of those regions as well as users for whom one of those regions is automatically selected.targeting.countries[]
: A list of countries where the channel section is visible. Each value in the list is an ISO 3166-1 alpha-2 country code .
The definition of the
video
resource'scontentDetails.duration
property has been corrected to reflect that the value can reflect hours, days, and so forth.The documentation for the
channelSections.delete
,playlistItems.delete
,playlists.delete
,subscriptions.delete
, andvideos.delete
method has been corrected to reflect that, when successful, those methods all return an HTTP204
response code (No Content
).
New and updated errors
The API now supports the following errors:
نوع خطا جزئیات خطا شرح badRequest (400)
targetInvalidCountry
The channelSections.insert
andchannelSections.update
methods return this error if the insertedchannelSection
resource contained an invalid value for thetargeting.countries[]
property.badRequest (400)
targetInvalidLanguage
The channelSections.insert
andchannelSections.update
methods return this error if the insertedchannelSection
resource contained an invalid value for thetargeting.languages[]
property.badRequest (400)
targetInvalidRegion
The channelSections.insert
andchannelSections.update
methods return this error if the insertedchannelSection
resource contained an invalid value for thetargeting.regions[]
property.badRequest (400)
operationNotSupported
The comments.insert
method returns this error if the API user is not able to insert a comment in reply to the top-level comment identified by thesnippet.parentId
property. In acommentThread
resource, thesnippet.canReply
property indicates whether the current viewer can reply to the thread.badRequest (400)
invalidChannelId
The search.list
method returns this error if thechannelId
parameter in the request specified an invalid channel ID.badRequest (400)
subscriptionForbidden
The subscriptions.insert
method returns this error if the API user tries to subscribe to the user's own channel.The
captions.update
method no longer supports theinvalidMetadata
andvideoNotFound
errors.
16 آوریل 2015
This update contains the following changes:
The migration guide has been updated to explain how to migrate applications still using comments functionality from the v2 API.
The guide also calls out several commenting features that the v2 API did not support but that are supported in the v3 API . این شامل:
- Retrieving comments about a channel
- Retrieving all comment threads related to a channel, which means that the API response can contain comments about the channel or any of its videos.
- Updating the text of a comment
- Marking a comment as spam
- Setting a comment's moderation status
The Subscribing to push notifications guide has been updated to reflect the fact that notifications are only pushed to the Google PubSubHubBub hub and not also to the Superfeedr hub as previously indicated.
9 آوریل 2015
This update contains the following changes:
The API's new
commentThread
andcomment
resources let you retrieve, insert, update, delete, and moderate comments.A
commentThread
resource contains information about a YouTube comment thread, which comprises a top-level comment and replies, if any exist, to that comment. AcommentThread
resource can represent comments about either a video or a channel.The top-level comment and the replies are actually
comment
resources that are nested inside thecommentThread
resource. It is important to note that thecommentThread
resource does not necessarily contain all replies to a comment, and you need to use thecomments.list
method if you want to retrieve all replies for a particular comment. In addition, some comments do not have replies.The API supports the following methods for
commentThread
resources:-
commentThreads.list
– Retrieve a list of comment threads. Use this method to retrieve comments associated with a particular video or channel. -
commentThreads.insert
– Create a new top-level comment. (Use thecomments.insert
method to reply to an existing comment.) -
commentThreads.update
– Modify a top-level comment.
-
A
comment
resource contains information about a single YouTube comment. Acomment
resource can represent a comment about either a video or a channel. In addition, the comment could be a top-level comment or a reply to a top-level comment.The API supports the following methods for
comment
resources:-
comments.list
– Retrieve a list of comment. Use this method to retrieve all of the replies to a particular comment. -
comments.insert
– Create a reply to an existing comment. -
comments.update
– Modify a comment. -
comments.markAsSpam
– Flag one or more comments as spam. -
comments.setModerationStatus
– Set the moderation status of one or more comments. For example, clear a comment for public display or reject a comment as unfit for display. The API request must be authorized by the owner of the channel or video associated with the comments.. -
comments.delete
– Delete a comment.
-
Note that the API's new
https://www.googleapis.com/auth/youtube.force-ssl
scope, described in the revision history for April 2, 2015 , is required for calls to thecomments.insert
,comments.update
,comments.markAsSpam
,comments.setModerationStatus
,comments.delete
,commentThreads.insert
, andcommentThreads.update
methods.The new Subscribing to push notifications guide explains the API's new support for push notifications via PubSubHubBub , a server-to-server publish/subscribe protocol for Web-accessible resources. Your PubSubHubBub callback server can receive Atom feed notifications when a channel does any of the following activities:
- uploads a video
- updates a video's title
- updates a video's description
The migration guide has also been updated to note the new support for push notifications. However, since the v2 API supported numerous other types of push notifications that are not supported in the v3 API, the mention of PubSubHubBub support is still listed in the Deprecated section of that guide.
The API's new
https://www.googleapis.com/auth/youtube.force-ssl
scope is now a valid scope for any API method that previously supported thehttps://www.googleapis.com/auth/youtube
scope.The API now supports the following errors:
نوع خطا جزئیات خطا شرح badRequest (400)
invalidRating
The videos.rate
method returns this error if the request contained an unexpected value for therating
parameter.The
subscriptions.insert
method no longer supports thesubscriptionLimitExceeded
error, which previously indicated that the subscriber identified with the request had exceeded the subscription rate limit.
2 آوریل 2015
This update contains the following changes:
The new
captions
resource represents a YouTube caption track. A caption track is associated with exactly one YouTube video.The API supports methods to list , insert , update , download , and delete caption tracks.
The migration guide has also been updated to explain how to migrate applications still using captions functionality in the v2 API.
The API's new
https://www.googleapis.com/auth/youtube.force-ssl
scope requires communication with the API server to happen over an SSL connection.This new scope grants the same access as the
https://www.googleapis.com/auth/youtube
scope. And, in fact, those two scopes are functionally identical because the YouTube API server is only available via an HTTPS endpoint. As a result, even though thehttps://www.googleapis.com/auth/youtube
scope does not require an SSL connection, there is actually no other way to make an API request.The new scope is required for calls to the all of the
caption
resource's methods.
11 مارس 2015
This update contains the following changes:
The YouTube Data API (v3) migration guide contains a new tab, named New in the v3 API , that lists features that the v3 API does support and that the v2 API did not support. The same features were previously and are still listed in other tabs in the guide. For example, the new feature explaining how to update a channel's in-video promotional campaign data is also listed under the Channels (profiles) tab.
The YouTube Data API (v3) migration guide has been updated to note that the v3 API will support the following v2 API feature:
The YouTube Data API (v3) migration guide has been updated to note that the following v2 API features will not be supported in the v3 API:
Retrieve video recommendations – The v3 API does not retrieve a list that only contains videos recommended for the current API user. However, you can use the v3 API to find recommended videos by calling the
activities.list
method and setting thehome
parameter value totrue
.In the API response, a resource corresponds to a recommended video if the
snippet.type
property's value isrecommendation
. In that case, thecontentDetails.recommendation.reason
andcontentDetails.recommendation.seedResourceId
properties will contain information about why the video was recommended. Note that there is no guarantee that the response will contain any particular number of recommended videos.Retrieve new subscription videos – The v3 API does not retrieve a list that only contains videos that have recently been uploaded to channels that the API user subscribes to. However, you can use the v3 API to find new subscription videos by calling the
activities.list
method and setting thehome
parameter value totrue
.In the API response, a resource corresponds to a new subscription video if the
snippet.type
property's value isupload
. Note that there is no guarantee that the response will contain any particular number of new subscription videos.Push notifications for feed updates – The v2 API supported push notifications, using either the Simple Update Protocol (SUP) or PubSubHubbub , to monitor user activity feeds for YouTube users. Notifications were provided for new channel subscriptions and when videos were rated, shared, marked as favorites, commented on, or uploaded.
The v3 API will support push notifications using the PubSubHubbub protocol , but the notifications will only cover video uploads and updates to video titles or video descriptions.
Channel location – The v2 API used the
<yt:location>
tag to identify the user's location as entered in the channel's YouTube public profile. While some developers used this field to associate a channel with a particular country, the field's data could not consistently be used for that purpose.Set or retrieve developer tags – The v2 API supported the ability to associate keywords, or developer tags, with a video at the time that the video was uploaded. Developer tags would not be displayed to YouTube users, but video owners could retrieve videos that matched a specific developer tag.
The v3 API will provide a similar, but not identical, feature. Specifically, a developer will be able to search for videos uploaded by the developer's own application. For this feature, each uploaded video is automatically tagged with the project number that is associated with the developer's application in the Google Developers Console . The developer then uses the same project number to search for videos.
List videos by publication date, viewcount, or rating – In the v2 API, the
orderby
parameter let you sort videos in a playlist by position, duration, publication date, title, and several other values. In the v3 API, playlist items are typically sorted by position in ascending order and other sorting options are not available.چند استثنا وجود دارد. A new upload, favorite video, liked video, or recently watched video is automatically added as the first item (
snippet.position
=0
) for the following types of playlists. So, each of these lists is effectively sorted in order of newest to oldest item based on the times that items were added to the list.- user uploads
- ویدیوهای مورد علاقه
- liked videos
- watch history
Note, however, that a new item added to the "Watch later" playlist is added as the last item in that list, so that list is effectively sorted from oldest to newest item.
Batch processing – The v3 API supports one of the batch processing use cases that the v2 API had supported. The v3 API's
channels.list
,channelSections.list
,guideCategories.list
,playlistItems.list
,playlists.list
,subscriptions.list
,videoCategories.list
, andvideos.list
methods all support anid
parameter, which can be used to specify a comma-delimited list of IDs (video IDs, channel IDs, etc.). Using those methods, you can retrieve a list of multiple resources with a single request.
With these changes, the guide now identifies all functionality that was supported in the old (v2) API that will be deprecated in the current API version (v3).
4 مارس 2015
This update contains the following changes:
The
channelSections.delete
andchannelSections.update
methods now support theonBehalfOfContentOwner
parameter, which is already supported for several other methods.The following properties and their child properties have been deprecated:
-
brandingSettings.image.backgroundImageUrl
-
brandingSettings.image.largeBrandedBannerImageImapScript
-
brandingSettings.image.largeBrandedBannerImageUrl
-
brandingSettings.image.smallBrandedBannerImageImapScript
-
brandingSettings.image.smallBrandedBannerImageUrl
Note: None of these properties had been subject to the API Deprecation Policy.
-
The
video
resource's newcontentDetails.contentRating.contentDetails.contentRating.djctqRatingReasons
property identifies the reasons that explain why the video received its DJCQT (Brazil) rating.The API now supports the following errors:
نوع خطا جزئیات خطا شرح notFound (404)
channelNotFound
The channels.update
method returns this error if the request'sid
parameter specifies a channel that cannot be found.badRequest (400)
manualSortRequiredinvalidValue
The playlistItems.insert
andplaylistItems.update
methods return this error if the request attempts to set the playlist item's position, but the playlist does not use manual sorting. For example, playlist items might be sorted by date or popularity. You can address this error by removing thesnippet.position
element from the resource sent in the request body. If you want the playlist item to have a specific position in the list, you need to first update the playlist's ordering setting to Manual . THis setting can be adjusted in the YouTube Video Manager .forbidden (403)
channelClosed
The playlists.list
method returns this error if the request'schannelId
parameter specifies a channel that has been closed.forbidden (403)
channelSuspended
The playlists.list
method returns this error if the request'schannelId
parameter specifies a channel that has been suspended.forbidden (403)
playlistForbidden
The playlists.list
method returns this error if the request'sid
parameter does not support the request or the request is not properly authorized.notFound (404)
channelNotFound
The playlists.list
method returns this error if the request'schannelId
parameter specifies a channel that cannot be found.notFound (404)
playlistNotFound
The playlists.list
method returns this error if the request'sid
parameter specifies a playlist that cannot be found.notFound (404)
videoNotFound
The videos.list
method returns this error if the request'sid
parameter specifies a video that cannot be found.badRequest (400)
invalidRating
The videos.rate
method returns this error if the request contains an unexpected value for therating
parameter.
2 مارس 2015
This update contains the following changes:
The
search.list
method now supports therelevanceLanguage
parameter, which lets you request results that are most relevant to a particular language.The YouTube Data API (v3) migration guide has also been updated to explain how to use this new parameter. The parameter addresses a feature gap that previously existed between the current API version (v3) and the previous version (v2), which has already been deprecated.
The YouTube Data API (v3) migration guide has also been updated to indicate the deprecation of the special feeds and metadata fields that the v2 API provided for describing movies, trailers, television shows, television seasons, and television episodes.
14 ژانویه 2015
This update contains the following changes:
The YouTube Data API (v3) migration guide has been updated to explain how to use the v3 API to upload videos using JavaScript. (See the Upload a video section for details.) This functionality is comparable to the browser-based uploading functionality that the v2 API supports. Note that this change to the migration guide does not reflect an actual API change but rather the availability of new sample code for uploading videos with client-side JavaScript.
Given the support for uploading videos with the JavaScript client library and CORS, the migration guide no longer lists browser-based uploading as a feature that may be deprecated in the v3 API.
The documentation for the
videos.insert
method has been updated to include the new JavaScript code sample described above. The list of JavaScript code samples for the YouTube Data API (v3) has also been updated.
November 11, 2014
This update contains the following changes:
The quota cost for a call to the
search.list
method has changed to 100 units.Important: In many cases, you can use other API methods to retrieve information at a lower quota cost. For example, consider these two ways of finding videos uploaded to the GoogleDevelopers channel.
Quota cost: 100 units
Call the
search.list
method and search forGoogleDevelopers
.Quota cost: 6 units
Call the
channels.list
method to find the right channel ID. Set theforUsername
parameter toGoogleDevelopers
and thepart
parameter tocontentDetails
. In the API response, thecontentDetails.relatedPlaylists.uploads
property specifies the playlist ID for the channel's uploaded videos.Then call the
playlistItems.list
method and set theplaylistId
parameter to the captured ID and thepart
parameter tosnippet
.
8 اکتبر 2014
This update contains the following changes:
The
channel
resource contains two new properties:The
status.longUploadsStatus
property indicates whether the channel is eligible to upload videos that are more than 15 minutes long. This property is only returned if the channel owner authorized the API request. Valid property values are:-
allowed
– The channel can upload videos more than 15 minutes long. -
eligible
– The channel is eligible to upload videos more than 15 minutes long but must first enable the feature. -
disallowed
– The channel is not able or eligible to upload videos more than 15 minutes long.
See the property definition for more information about these values. The YouTube Help Center also provides more detailed information about this feature.
-
The
invideoPromotion.useSmartTiming
property indicates whether the channel's promotional campaign uses "smart timing." This feature attempts to show promotions at a point in the video when they are more likely to be clicked and less likely to disrupt the viewing experience. This feature also picks up a single promotion to show on each video.
The definitions of the
video
resource'ssnippet.title
andsnippet.categoryId
properties have both been updated to clarify the way that API handles calls to thevideos.update
method. If you call that method to update thesnippet
part of avideo
resource, you must set a value for both of those properties.If you try to update the
snippet
part of avideo
resource and do not set a value for both of those properties, the API returns aninvalidRequest
error. That error's description has also been updated.The
video
resource'scontentDetails.contentRating.oflcRating
property, which identifies a video's rating from New Zealand's Office of Film and Literature Classification, now supports two new ratings:oflcRp13
andoflcRp16
. These correspond to theRP13
andRP16
ratings, respectively.The
channelBanners.insert
method now supports the following error:نوع خطا جزئیات خطا شرح badRequest
bannerAlbumFull
The channel owner's YouTube Channel Art album has too many images. The channel owner should go to http://photos.google.com , navigate to the albums page, and remove some from images from that album.
12 سپتامبر 2014
This update contains the following changes:
The quota cost for a call to the
search.list
method has changed from 1 unit to 2 units in addition to the cost of the specified resource parts .
13 آگوست 2014
This update contains the following changes:
The
subscriptions.insert
method now supports the following error:نوع خطا جزئیات خطا شرح badRequest
subscriptionLimitExceeded
The subscriber identified with the request has exceeded the subscription rate limit. More subscriptions can be attempted in a few hours.
12 آگوست 2014
This update contains the following changes:
A new guide, titled Migrating Your Application to YouTube Data API (v3) , explains how to use the YouTube Data API (v3) to perform functionality available in the YouTube Data API (v2). The older API was officially deprecated as of March 4, 2014. The guide intends to help you migrate applications still using the v2 API to the most recent API version.
8 جولای 2014
This update contains the following changes:
The
playlists.insert
method now supports the following error:نوع خطا جزئیات خطا شرح badRequest
maxPlaylistExceeded
This error occurs if a playlist cannot be created because the channel already has the maximum number of playlists allowed.
18 ژوئن 2014
This update contains the following changes:
The description of each API method has been updated to include the quota cost incurred by a call to that method. Similarly, the definitions of
part
parameters have been updated to specify the quota cost of each part that can be retrieved in an API call. For example, a call to thesubscriptions.insert
method has a quota cost of approximately 50 units. Thesubscription
resource also contains three parts (snippet
,contentDetails
, andsubscriberSnippet
), and each of those has a cost of two units.Please remember that quota costs can change without warning.
The
video
resource now supports 43 new content rating systems, which identify the ratings that videos received from various national rating agencies. The newly supported rating systems are from Argentina , Austria , Belgium , Bulgaria , Chile ( television ), Chile ( film ), Czech Republic , Colombia , Denmark , Egypt , Estonia , Finland , France , Greece , Hong Kong , Iceland , Indonesia , Ireland , Israel , Italy , Kenya , Latvia , Luxembourg , Malaysia , Maldives , Malta , Netherlands , Nigeria , Norway , Peru , Philippines , Portugal , Romania , Singapore , Slovakia , South Africa , Sweden , Switzerland , Taiwan , Thailand , and Venezuela .
28 مه 2014
This update contains the following changes:
The
search.list
method now supports thelocation
andlocationRadius
parameters, which let you search for videos associated with a geographic location. A request must specify a value for both parameters to retrieve results based on location, and the API will return an error if a request includes only one of the two parameters.The
location
parameter specifies the latitude/longitude coordinates at the center of the circular geographic area.The
locationRadius
parameter specifies the maximum distance that the location associated with a video can be from the center of the area for the video to still be included in search results.
13 مه 2014
This update contains the following changes:
The
channel
resource'sinvideoPromotion.items[]
property has been updated to note that you can typically only set one promoted item for your channel. If you try to insert too many promoted items, the API will return atooManyPromotedItems
error, which has an HTTP400
status code.The
channelSection
resource now can contain information about a few new types of featured content. ThechannelSection
resource'ssnippet.type
property now supports the following values:-
postedPlaylists
- playlists that the channel's owner posted to the channel's activity feed -
postedVideos
- videos that the channel's owner posted to the channel's activity feed -
subscriptions
- channels that the channel owner has subscribed to
-
The
video
resource's newcontentDetails.contentRating.ifcoRating
property identifies the rating that a video received from the Irish Film Classification Office.The definition of the
watermark
resource'sposition.cornerPosition
property has been updated to note that the watermark always appear in the upper right corner of the player.The definition of the
q
parameter for thesearch.list
method has been updated to note that the query term can use the Boolean NOT (-
) operator to exclude videos associated with a particular search term. The value can also use the Boolean OR (|
) operator to find videos associated with one of several search terms.The definition of the
pageInfo.totalResults
property that is returned in an API response to asearch.list
call has been updated to note that the value is an approximation and may not represent an exact value. In addition, the maximum value is 1,000,000. You should not use this value to create pagination links. Instead, use thenextPageToken
andprevPageToken
property values to determine whether to show pagination links.The
watermarks.set
andwatermarks.unset
methods have been updated to reflect that the API returns an HTTP204
response code for successful requests to those methods.
2 مه 2014
This update contains the following changes:
The new
i18nLanguage
resource identifies an application language that the YouTube website supports. The application language can also be referred to as a UI language. For the YouTube website, an application language could be automatically selected based on Google Account settings, browser language, or IP location, and a user could also manually select the desired UI language from the YouTube site footer.The API supports a method to list supported application languages. Supported languages can be used as the value of the
hl
parameter when calling API methods likevideoCategories.list
andguideCategories.list
.The new
i18nRegion
resource identifies a geographic area that a YouTube user can select as the preferred content region. The content region can also be referred to as a content locale. For the YouTube website, a content region could be automatically selected based on heuristics like the YouTube domain or the user's IP location, and a user could also manually select the desired content region from the YouTube site footer.The API supports a method to list supported content regions. Supported region codes can be used as the value of the
regionCode
parameter when calling API methods likesearch.list
,videos.list
,activities.list
, andvideoCategories.list
.
7 آوریل 2014
This update contains the following changes:
The new
channelSection
resource contains information about a set of videos that a channel has chosen to feature. For example, a section could feature a channel's latest uploads, most popular uploads, or videos from one or more playlists.The API supports methods to list , insert , update , or delete channel sections. You can retrieve a list of channel sections for the authenticated user's channel, by specifying a particular channel ID, or by specifying a list of unique channel section IDs.
The error documentation has also been updated to describe the error messages that the API supports specifically for these new methods.
The definition of the
video
resource'sfileDetails
object has been updated to explain that that object will only be returned if the video'sprocessingDetails.fileDetailsAvailability
property has a value ofavailable
.Similarly, the definition of the
video
resource'ssuggestions
object has been updated to explain that that object will only be returned if the video'sprocessingDetails.tagSuggestionsAvailability
property or itsprocessingDetails.editorSuggestionsAvailability
property has a value ofavailable
.The documentation for the
videos.insert
andvideos.update
methods has been updated to reflect that thestatus.publishAt
property can be set when calling those methods.The definition of the
channel
resource'sinvideoPromotion
object has been updated to explain that the object can only be retrieved by the channel's owner.The parameter list for the
videos.rate
method has been updated to reflect that that method does not actually support theonBehalfOfContentOwner
parameter. This was a documentation error asvideos.rate
requests that set this parameter return a500
error.
31 مارس 2014
This update contains the following changes:
The
video
resource's newstatus.publishAt
property lets you specify the date and time when a private video is scheduled to be published. This property can only be set if the video's privacy status isprivate
and the video has never been published. This new property is not subject to the deprecation policy .
13 مارس 2014
This update contains the following changes:
The API now supports the
contentOwnerDetails
part forchannel
resources. The new part contains channel data that is relevant for YouTube partners linked with the channel, including the ID of the content owner linked to the channel and the date and time when the content owner and channel were linked. Note that this new part is not subject to the deprecation policy .The documentation now lists the maximum supported character length for the following properties:
منبع ویژگی حداکثر طول channel
invideoPromotion.items[].customMessage
40 characters video
snippet.title
100 characters video
snippet.description
5000 bytes video
snippet.tags
500 characters. Note that the property value is a list and that commas between items in the list count toward the limit. The
channel
resource'sbrandingSettings.watch.featuredPlaylistId
property has been deprecated. The API will return an error if you attempt to set its value.The following
video
resource properties have been added to the list of values that can be set when inserting or updating a video:The error documentation now specifies the HTTP response code for each error type.
The API now supports the following errors:
نوع خطا جزئیات خطا شرح badRequest (400)
invalidCriteria
The channels.list
method returns this error if the request specifies filter parameters that cannot be used in conjunction with each other.badRequest (400)
channelTitleUpdateForbidden
The channels.update
method returns this error if you attempt to update a channel'sbrandingSettings
part and change the value of thebrandingSettings.channel.title
property. (Note that the API does not return the error if you omit the property.)badRequest (400)
invalidRecentlyUploadedBy
The channels.update
method returns this error if theinvideoPromotion.items[].id.recentlyUploadedBy
property specifies an invalid channel ID.badRequest (400)
invalidTimingOffset
The channels.update
method returns this error if theinvideoPromotion
part specifies an invalid timing offset.badRequest (400)
tooManyPromotedItems
The channels.update
method returns this error if theinvideoPromotion
part specifies more than the allowed number of promoted items.forbidden (403)
promotedVideoNotAllowed
The channels.update
method returns this error if theinvideoPromotion.items[].id.videoId
property specifies a video ID that either cannot be found or cannot be used as a promoted item.forbidden (403)
websiteLinkNotAllowed
The channels.update
method returns this error if theinvideoPromotion.items[].id.websiteUrl
property specifies a URL that is not allowed.required (400)
requiredTimingType
The channels.update
method returns this error if a request does not specify default timing settings for when YouTube should display a promoted item.required (400)
requiredTiming
The channels.update
method must specify aninvideoPromotion.items[].timing
object for each promoted item.required (400)
requiredWebsiteUrl
The channels.update
method must specify aninvideoPromotion.items[].id.websiteUrl
property for each promoted item.badRequest (400)
invalidPublishAt
The videos.insert
method returns this error if the request metadata specifies an invalid scheduled publishing time.
4 مارس 2014
This update contains the following changes:
The YouTube Data API, v3 is now subject to the Deprecation Policy described in the YouTube APIs Terms of Service . Note that the page that lists the APIs that are subject to the deprecation policy specifically excludes some v3 API functionality from being subject to the policy.
5 دسامبر 2013
This update contains the following changes:
The
search.list
method's documentation has been updated to properly reflect that you do not need to specify a value for exactly one filter parameter when submitting a search request. Rather, you can set a value for zero filter parameters or for one filter parameter.The definitions for the
search.list
method's parameters have been updated to note that you must set thetype
parameter's value tovideo
if you also specify a value for any of the following parameters:-
eventType
-
videoCaption
-
videoCategoryId
-
videoDefinition
-
videoDimension
-
videoDuration
-
videoEmbeddable
-
videoLicense
-
videoSyndicated
-
videoType
-
The minimum size of uploaded channel banner images has been reduced to 2048px by 1152px. (Previously, the minimum size was 2120px by 1192px.) In addition, note that the
channel
resource documentation specifies the maximum sizes of all of the banner images served from the API. For example, the maximum size of thebrandingSettings.image.bannerTvImageUrl
image for television applications is 2120px by 1192px, but the actual image may be 2048px by 1152px. The YouTube Help Center provides additional guidance for optimizing channel art for display on different types of devices.Several
channel
resource property definitions have been updated to reflect the following information:- The
brandingSettings.channel.description
property's value has a maximum length of 1000 characters. - The
brandingSettings.channel.featuredChannelsTitle
property has a maximum length of 30 characters. - The
brandingSettings.channel.featuredChannelsUrls[]
property can now list up to 100 channels. - The
brandingSettings.channel.unsubscribedTrailer
property value, if set, must specify the YouTube video ID of a public or unlisted video that is owned by the channel owner.
- The
The
channels.update
method now supports updates to theinvideoPromotion.items[].promotedByContentOwner
property. That property indicates whether the content owner's name will be shown when displaying the promotion. It can only be set if the API request that sets the property value is being made on the content owner's behalf using theonBehalfOfContentOwner
parameter.The
playlistItems.list
andplaylistItems.insert
methods now support theonBehalfOfContentOwner
parameter, which is already supported for several other methods.The
contentDetails.contentRating.acbRating
property can now specify a rating from either the Australian Classification Board (ACB) for movies or from the Australian Communications and Media Authority (ACMA) for children's television programming.The new
contentDetails.contentRating.catvRating
andcontentDetails.contentRating.catvfrRating
properties identify the ratings that a video received under the Canadian TV Classification System and the French-language Régie du cinéma rating system, which is used in Québec, respectively.The
videoCategory
resource's newsnippet.assignable
property indicates whether updated videos or newly uploaded videos can be associated with that video category.Code samples have been added for the following methods:
-
activities.insert
(Go) -
channelBanners.insert
(Python) -
channels.update
(Python) -
playlistItems.list
(Go) -
search.list
(Go) -
thumbnails.set
(Java) -
videos.insert
(Go)
-
24 اکتبر 2013
This update contains the following changes:
The API includes two additional features designed to help find and feature live broadcast content:
The new
snippet.liveBroadcastContent
property in search results indicates whether a video or channel resource has live broadcast content. Valid property values areupcoming
,active
, andnone
.The
video
resource's newsnippet.liveBroadcastContent
property indicates whether the video is an upcoming or active live broadcast. The list below explains the property's possible values:-
upcoming
– The video is a live broadcast that has not yet started. -
active
– The video is an ongoing live broadcast. -
none
– The video is not an upcoming or active live broadcast. This will be the property value for completed broadcasts that are still viewable on YouTube.
-
The
video
resource's newliveStreamingDetails
property is an object that contains metadata about a live video broadcast. To retrieve this metadata, includeliveStreamingDetails
in thepart
parameter value's list of resource parts. The metadata includes the following new properties:-
liveStreamingDetails.actualStartTime
– The time that the broadcast actually started. (This value will be present once the broadcast's state isactive
.) -
liveStreamingDetails.actualEndTime
– The time that the broadcast actually ended. (This value will be present once the broadcast is over.) -
liveStreamingDetails.scheduledStartTime
– The time that the broadcast is scheduled to begin. -
liveStreamingDetails.scheduledEndTime
– The time that the broadcast is scheduled to end. If the property value is empty or the property is not present, then the broadcast is scheduled to go on indefinitely. -
liveStreamingDetails.concurrentViewers
– The number of people watching the live broadcast.
To retrieve this metadata, include
liveStreamingDetails
in thepart
parameter value when calling thevideos.list
,videos.insert
, orvideos.update
method.-
Note that two other features for identifying live broadcast content were released on October 1, 2013 – the
search.list
method'seventType
parameter and the search result'ssnippet.liveBroadcastContent
property.The
videos.insert
method now supports thenotifySubscribers
parameter, which indicates whether YouTube should send a notification about the new video to users who subscribe to the video's channel. The parameter's default value isTrue
, which indicates that subscribers will be notified of newly uploaded videos. However, a channel owner who is uploading many videos might prefer to set the value toFalse
to avoid sending a notification about each new video to the channel's subscribers.The list of properties that can be modified when calling the
channels.update
method has been updated to include theinvideoPromotion.items[].customMessage
andinvideoPromotion.items[].websiteUrl
properties. In addition, the list has been modified to identify thebrandingSettings
properties that are modifiable. ThesebrandingSettings
properties were already modifiable, so the documentation change does not reflect a change to the API's existing functionality.The
playlists.insert
,playlists.update
, andplaylists.delete
methods now support theonBehalfOfContentOwner
parameter, which is already supported for several other methods.The
playlists.insert
method now supports theonBehalfOfContentOwnerChannel
parameter, which is already supported for several other methods.The
video
resource'scontentDetails.contentRating.tvpgRating
property now supports a value ofpg14
, which corresponds to aTV-14
rating.The definition of the
snippet.liveBroadcastContent
property, which is part of search results, has been corrected to reflect thatlive
is a valid property value, butactive
is not a valid property value.The
video
resource'scontentDetails.contentRating.mibacRating
property now supports two additional ratings:-
mibacVap
(VAP) – Children should be accompanied by an adult. -
mibacVm6
(VM6) – Restricted to 6 and over. -
mibacVm12
(VM12) – Restricted to 12 and over.
-
The
channel
resource's newinvideoPromotion.items[].promotedByContentOwner
property indicates whether the content owner's name will be shown when displaying the promotion. This field can only be set if the API request that sets the value is being made on the content owner's behalf. See theonBehalfOfContentOwner
parameter for more information.
1 اکتبر 2013
This update contains the following changes:
The
channel
resource's newauditDetails
object contains channel data that a multichannel network (MCN) would evaluate while determining whether to accept or reject a particular channel. Note that any API request that retrieves this resource part must provide an authorization token that contains thehttps://www.googleapis.com/auth/youtubepartner-channel-audit
scope. In addition, any token that uses that scope must be revoked when the MCN decides to accept or reject the channel or within two weeks of the date that the token was issued.The
channel
resource'sinvideoPromotion.items[].id.type
property now supports a value ofrecentUpload
, which indicates that the promoted item is the most recently uploaded video from a specified channel.By default, the channel is the same as the one for which the in-video promotion data is set. However, you can promote the most recently uploaded video from another channel by setting the value of the new
invideoPromotion.items[].id.recentlyUploadedBy
property to the channel ID for that channel.The
channel
resource contains three new properties –brandingSettings.image.bannerTvLowImageUrl
,brandingSettings.image.bannerTvMediumImageUrl
,brandingSettings.image.bannerTvHighImageUrl
– that specify the URLs for the banner images that display on channel pages in television applications.The new
snippet.liveBroadcastContent
property in search results indicates whether a video or channel resource has live broadcast content. Valid property values areupcoming
,active
, andnone
.- For a
video
resource, a value ofupcoming
indicates that the video is a live broadcast that has not yet started, while a value ofactive
indicates that the video is an ongoing live broadcast. - For a
channel
resource, a value ofupcoming
indicates that the channel has a scheduled broadcast that has not yet started, while a value ofacive
indicates that the channel has an ongoing live broadcast.
- For a
In the
watermark
resource, thetargetChannelId
property has changed from an object to a string. Instead of containing a child property that specifies the YouTube channel ID of the channel that the watermark image links to, thetargetChannelId
property now specifies that value itself. Accordingly, the resource'stargetChannelId.value
property has been removed.The
thumbnails.set
method now supports theonBehalfOfContentOwner
parameter, which is already supported for several other methods.The
search.list
method now supports theeventType
parameter, which restricts a search to only return either active, upcoming, or completed broadcast events.The new
contentDetails.contentRating.mibacRating
property identifies the rating that a video received from Italy's Ministero dei Beni e delle Attivita Culturali e del Turismo.The API now supports the following errors:
نوع خطا جزئیات خطا شرح badRequest
invalidImage
The thumbnails.set
method returns this error if the provided image content is invalid.forbidden
videoRatingDisabled
The videos.rate
method returns this error if the owner of the video that is being rated has disabled ratings for that video.
August 27, 2013
This update contains the following changes:
The new
watermark
resource identifies an image that displays during playbacks of a specified channel's videos. You can also specify a target channel to which the image will link as well as timing details that determine when the watermark appears during video playbacks and the length of time it is visible.The
watermarks.set
method uploads and sets a channel's watermark image. Thewatermarks.unset
method deletes a channel's watermark image.The error documentation describes the error messages that the API supports specifically for the
watermarks.set
andwatermarks.unset
methods.The
channel
resource's newstatistics.hiddenSubscriberCount
property contains a boolean value that indicates whether the channel's number of subscribers is hidden. As such, the property's value isfalse
if the channel's subscriber count is publicly visible.The
playlists.list
method now supports theonBehalfOfContentOwner
andonBehalfOfContentOwnerChannel
parameters. Both parameters are already supported for several other methods.The
videos.list
method now supports theregionCode
parameter, which identifies the content region for which a chart should be retrieved. This parameter can only be used in conjunction with thechart
parameter. The parameter value is an ISO 3166-1 alpha-2 country code.The
error documentation
describes the following new common request error, which could occur for multiple API methods:نوع خطا جزئیات خطا شرح forbidden
insufficientPermissions
The scopes associated with the OAuth 2.0 token provided for the request are insufficient for accessing the requested data.
15 آگوست 2013
This update contains the following changes:
The
channel
resource'sinvideoPromotion
object has the following new and updated properties:The API now supports the ability to specify a website as a promoted item. To do so, set the
invideoPromotion.items[].id.type
property value towebsite
and use the newinvideoPromotion.items[].id.websiteUrl
property to specify the URL. Also use the newinvideoPromotion.items[].customMessage
property to define a custom message to display for the promotion.Links can be to associated websites, merchant sites, or social networking sites. See the YouTube Help Center instructions for associated websites and merchant sites for more information about enabling links for your content.
By adding promotional links, you agree that those links will not be used to redirect traffic to unauthorized sites and that those links will comply with YouTube's AdWords policies , YouTube ad policies , YouTube Community Guidelines and YouTube Terms of Service .
The properties related to the timing settings for displaying promoted items during video playback have been restructured:
The
invideoPromotion.timing
object has been moved toinvideoPromotion.items[].timing
. This object now enables you to customize the timing data for each promoted item in theinvideoPromotion.items[]
list.The new
invideoPromotion.defaultTiming
object specifies default timing settings for your promotion. Those settings define when a promoted item will display during playback of one of your channel's videos. You can override the default timing for any given promoted item using theinvideoPromotion.items[].timing
object.The new
invideoPromotion.items[].timing.durationMs
property specifies the amount of time, in milliseconds, that the promotion should display. TheinvideoPromotion.defaultTiming
object also contains adurationMs
field that specifies the default amount of time that the promoted item will display.
The
invideoPromotion.items[].type
andinvideoPromotion.items[].videoId
properties both have been moved into theinvideoPromotion.items[].id
object.
The
subscriptions.list
method now supports theonBehalfOfContentOwner
andonBehalfOfContentOwnerChannel
parameters. Both parameters are already supported for several other methods.In the API response to a
thumbnails.set
request, thekind
property value has changed fromyoutube#thumbnailListResponse
toyoutube#thumbnailSetResponse
.Code samples have been added for the following methods:
-
channels.update
(Java, Python) -
playlists.insert
(.NET, PHP) -
subscriptions.insert
(PHP, Python) -
thumbnails.set
(PHP, Python) -
videos.insert
(PHP) -
videos.list
(PHP) -
videos.rate
(Python) -
videos.update
(Java, PHP, Python)
Note that the Python example for the
playlistItems.insert
method was also removed since the functionality it demonstrated is now handled by thevideos.rate
method.-
The
error documentation
describes the following new request context error, which could occur for any API method that supports themine
request parameter:نوع خطا جزئیات خطا شرح badRequest
invalidMine
The mine
parameter cannot be used in requests where the authenticated user is a YouTube partner. You should either remove themine
parameter, authenticate as a YouTube user by removing theonBehalfOfContentOwner
parameter, or act as one of the partner's channels by providing theonBehalfOfContentOwnerChannel
parameter if available for the called method.
8 آگوست 2013
This update contains the following changes:
The Getting Started with the YouTube Data API guide's Quota Usage section has been updated to reflect a change in the quota cost of a video upload from approximately 16000 units to approximately 1600 units.
30 جولای 2013
This update contains the following changes:
In a
channelBanner
resource, the value of thekind
property's value has changed fromyoutube#channelBannerInsertResponse
toyoutube#channelBannerResource
. This resource is returned in response to achannelBanners.insert
request.The
channel
resource's newbrandingSettings.channel.profileColor
property specifies a prominent color that complements the channel's content. The property value is a pound sign (#
) followed by a six-character hexadecimal string, such as#2793e6
.The API now supports the ability to specify whether a subscription is for all of a channel's activities or just for new uploads. The
subscription
resource's newcontentDetails.activityType
property identifies the types of activities that the subscriber will be notified about. Valid property values areall
anduploads
.The
videos.list
method supports new parameters for retrieving a chart of the most popular videos on YouTube:- The
chart
parameter identifies the chart that you want to retrieve. Currently, the only supported value ismostPopular
. Note that thechart
parameter is a filter parameter, which means it cannot be used in the same request as other filter parameters (id
andmyRating
). - The
videoCategoryId
parameter identifies the video category for which the chart should be retrieved. This parameter can only be used in conjunction with thechart
parameter. By default, charts are not restricted to a particular category.
- The
The
video
resource's newtopicDetails.relevantTopicIds[]
property provides a list of Freebase topic IDs that are relevant to the video or its content. The subjects of these topics may be mentioned in or appear in the video.The
video
resource'srecordingDetails.location.elevation
property has been renamed torecordingDetails.location.altitude
, and itsfileDetails.recordingLocation.location.elevation
property has been renamed tofileDetails.recordingLocation.location.altitude
.The
video
resource'scontentDetails.contentRating
object specifies the ratings that a video received under various rating schemes, including MPAA ratings, TVPG ratings, and so forth. For each rating system, the API now supports a rating value that indicates that the video has not been rated. Note that for MPAA ratings , an "unrated" rating is frequently used to identify uncut versions of films for which the cut version of the film did receive an official rating.The
video
resource's newcontentDetails.contentRating.ytRating
property identifies age-restricted content. The property value will beytAgeRestricted
if YouTube has identified the video as containing content that is inappropriate for users less than 18 years old. If the property is absent or if the property value is empty, then the content has not been identified as age-restricted.The
channels.list
method'smySubscribers
parameter has been deprecated. Use thesubscriptions.list
method and itsmySubscribers
parameter to retrieve a list of subscribers to the authenticated user's channel.The
channelBanners.insert
,channels.update
,videos.getRating
, andvideos.rate
methods all now support theonBehalfOfContentOwner
parameter. That parameter indicates that the authenticated user is acting on behalf of the content owner specified in the parameter value.The
channels.update
method's documentation has been updated to reflect the fact that that method can be used to update thechannel
resource'sbrandingSettings
object and its child properties. The documentation also now lists the updated list of properties that you can set for thechannel
resource'sinvideoPromotion
object.The
error documentation
describes the following new errors:نوع خطا جزئیات خطا شرح forbidden
accountDelegationForbidden
This error is not specific to a particular API method. It indicates that the authenticated user is not authorized to act on behalf of the specified Google account. forbidden
authenticatedUserAccountClosed
This error is not specific to a particular API method. It indicates that the authenticated user's YouTube account is closed. If the user is acting on behalf of another Google Account, then this error would indicate that that other account is closed. forbidden
authenticatedUserAccountSuspended
This error is not specific to a particular API method. It indicates that the authenticated user's YouTube account is suspended. If the user is acting on behalf of another Google Account, then this error would indicate that that other account is suspended. forbidden
authenticatedUserNotChannel
This error is not specific to a particular API method. It indicates that the API server cannot identify the channel associated with the API request. If the request is authorized and uses the onBehalfOfContentOwner
parameter, you should also set theonBehalfOfContentOwnerChannel
parameter.forbidden
cmsUserAccountNotFound
This error is not specific to a particular API method. The CMS user is not allowed to act on behalf of the specified content owner. notFound
contentOwnerAccountNotFound
This error is not specific to a particular API method. The specified content owner account was not found. badRequest
invalidPart
This error is not specific to a particular API method. The request's part
parameter specifies parts that cannot be written at the same time.badRequest
videoChartNotFound
The videos.list
method returns this error when the request specifies an unsupported or unavailable video chart.notFound
videoNotFound
The videos.update
method returns this error to indicate that the video you are trying to update cannot be found. Check the value of theid
property in the request body to ensure it is correct.
10 ژوئن 2013
This update contains the following changes:
The
channels.list
method's newforUsername
parameter enables you to retrieve information about a channel by specifying its YouTube username.The
activities.list
method now supports theregionCode
parameter, which instructs the API to return results relevant to the specified country. YouTube uses this value when the authorized user's previous activity on YouTube does not provide enough information to generate the activity feed.Playlist resources now contain the
snippet.tags
property. The property will be only be returned to authorized users who are retrieving data about their own playlists. Authorized users can also set playlist tags when calling either theplaylists.insert
orplaylists.update
methods.The
onBehalfOfContentOwner
parameter, which was previously supported for thechannels.list
andsearch.list
methods, is now also supported for thevideos.insert
,videos.update
, andvideos.delete
methods. Note that when this parameter is used in a call to thevideos.insert
method, the request must also specify a value for the newonBehalfOfContentOwnerChannel
parameter, which identifies the channel to which the video will be added. The channel must be linked to the content owner that theonBehalfOfContentOwner
parameter specifies.The parameter indicates that the request's authorization credentials identify a YouTube CMS user who is acting on behalf of the content owner specified in the parameter value. The CMS account that the user authenticates with must be linked to the specified YouTube content owner.
This parameter is intended for content partners that own and manage many different YouTube channels. The parameter enables those partners to authenticate once and get access to all of their video and channel data, without having to provide authentication credentials for each individual channel.
Specifically in regard to this release, the parameter now enables a content partner to insert, update, or delete videos in any of the YouTube channels that the partner owns.
The
error documentation
describes the following new errors:نوع خطا جزئیات خطا شرح forbidden
insufficientCapabilities
This error is not specific to a particular API method. It indicates that the CMS user calling the API does not have sufficient permissions to perform the requested operation. This error is associated with the use of the onBehalfOfContentOwner
parameter, which is supported for several API methods.unauthorized
authorizationRequired
The activities.list
method returns this error when the request uses thehome
parameter but is not properly authorized.In the
channels
resource, theinvideoPromotion.channelId
property has been removed because the channel ID is already specified using the resource'sid
property.The new Working with Channel IDs guide explains how the API uses channel IDs. The guide may be especially useful for developers migrating from the previous version of the API and who have applications that either request content for the
default
user or that rely on the notion that every YouTube channel has a unique username, which is no longer the case.
22 مه 2013
This update contains the following changes:
The new
channelBanners.insert
method enables you to upload a banner image that can subsequently be set as the banner image for a channel using thechannel
resource's newbrandingSettings.image.bannerExternalUrl
property.The documentation for the
channels.update
method has been updated to list the properties that can be modified when calling the method.The
video
resource documentation no longer listsunspecified
as a valid property value for thesuggestions.processingErrors[]
,suggestions.processingHints[]
,suggestions.processingWarnings[]
, andsuggestions.editorSuggestions[]
properties.The
videos.list
method'smaxResults
parameter now has a default value of5
.The
error documentation
now lists errors for thechannelBanners.insert
andsubscriptions.list
methods. It also lists several new errors for thechannels.update
method.
May 14, 2013
This update contains the following changes:
Standalone pages now list code samples for Java , .NET , PHP , and Ruby .
The page that lists Python code samples now includes examples for adding a subscription, creating a playlist, and updating a video.
10 مه 2013
This update contains the following changes:
YouTube no longer identifies experimental API features and services. Instead, we now provide a list of YouTube APIs that are subject to the deprecation policy .
8 مه 2013
This update contains the following changes:
Channel resources now support the
inVideoPromotion
object, which encapsulates information about a promotional campaign associated with the channel. A channel can use an in-video promotional campaign to display thumbnail images for a promoted video within the video player during playbacks of the channel's videos.You can retrieve this data by including
invideoPromotion
in thepart
parameter value in achannels.list
request.The new
channels.update
method can be used to update a channel's in-video promotional campaign data. Note that the method only supports updates to theinvideoPromotion
part of thechannel
resource and does not yet support updates to other parts of that resource.
2 مه 2013
This update contains the following changes:
Channel resources now support the
status.isLinked
property, which indicates whether the channel data identifies a user that is already linked to either a YouTube username or a Google+ account. A user that has one of these links already has a public YouTube identity, which is a prerequisite for several actions, such as uploading videos.Subscription resources now support the
subscriberSnippet
part. That object encapsulates contains snippet data for the subscriber's channel.The API now supports the
videos.getRating
method, which retrieves the ratings that the authenticated user gave to a list of one or more videos.The
videos.list
method's newmyRating
parameter enables you to retrieve a list of videos that the authenticated user rated with alike
ordislike
rating.The
myRating
parameter and theid
parameter are both now considered filter parameters, which means that an API request must specify exactly one of the parameters. (Previously, theid
parameter was a required parameter for this method.)The method returns a
forbidden
error for requests that attempt to retrieve video rating information but are not properly authorized to do so.With the introduction of the
myRating
parameter, thevideos.list
method has also been updated to support pagination. Note, however, that paging parameters are only supported for requests using themyRating
parameter. (Paging parameters and information are not supported for requests that use theid
parameter.)The
maxResults
parameter specifies the maximum number of videos that the API can return in the result set, and thepageToken
parameter identifies a specific page in the result set that you want to retrieve.The
youtube#videoListResponse
resource, which is returned in response to avideos.list
request, now contains thepageInfo
object, which contains details like the total number of results and the number of results included in the current result set. Theyoutube#videoListResponse
resource can also includenextPageToken
andprevPageToken
properties, each of which provides a token that could be used to retrieve a specific page in the result set.
The
videos.insert
method supports the following new parameters:-
autoLevels
– Set this parameter value totrue
to instruct YouTube to automatically enhance the video's lighting and color. -
stabilize
– Set this parameter value totrue
to instruct YouTube to adjust the video by removing shakiness resulting from camera motions.
-
The
channelTitle
property has been added to thesnippet
for the following resources:-
playlistItem
– The property specifies the name of the channel that added the playlist item. -
playlist
– The property specifies the name of the channel that created the playlist. -
subscription
– The property specifies the name of the channel that is subscribed to.
-
Code samples have been added for the following methods:
-
activities.insert
(Ruby) -
playlistItems.list
(.NET) -
search.list
(.NET) -
subscriptions.insert
(Java, Ruby) -
videos.insert
(.NET, Ruby)
-
The
subscriptions.list
method's newmySubscribers
parameter enables you to retrieve a list of the currently authenticated user's subscribers. This parameter can only be used in a properly authorized request.Note: This functionality is intended to replace the
mySubscribers
parameter currently supported for thechannels.list
method. That parameter will be deprecated.In a
video
resource, the property valueunspecified
is no longer a possible value for any of the following properties:API requests that contain an unexpected parameter now return a
badRequest
error, and the reported reason for the error isunexpectedParameter
.The error that the
playlistItems.insert
method returns when the playlist already contains the maximum number of allowed items has been updated. The error is now reported as aforbidden
error, and the error reason isplaylistContainsMaximumNumberOfVideos
.
19 آوریل 2013
This update contains the following changes:
The new
videos.rate
method lets a user set alike
ordislike
rating on a video or remove a rating from a video.The error documentation has also been updated to list the errors that the API might return in response to a
videos.rate
method call.Thumbnail images are now identified in the API documentation as a separate resource , and the new
thumbnails.set
method enables you to upload a custom video thumbnail to YouTube and set it for a video.The error documentation has also been updated to list the errors that the API might return in response to a
thumbnails.set
method call.Note that this change does not really affect existing resources that return thumbnail images. Thumbnail images are returned in those resources in the same way that they were previously, though the documentation does now list the names of the different thumbnail sizes that the API might return.
The
channel
resource's newbrandingSettings
part identifies settings, text, and images for the channel's channel page and video watch pages.The
playlistItem
resource contains the following new properties:The new
status
object encapsulates status information about the playlist item, and thestatus.privacyStatus
property identifies the playlist item's privacy status.
The
video
resource contains the following new properties:The
status.publicStatsViewable
property indicates whether extended video statistics on the watch page are publicly viewable. By default, those statistics are viewable, and statistics like a video's viewcount and ratings will still be publicly visible even if this property's value is set tofalse
. You can set this property's value when calling thevideos.insert
orvideos.update
method.The
contentDetails.contentRating
object encapsulates ratings that the video received under various rating schemes. The list below identifies the supported rating systems and provides a link to the property associated with each rating system. The property definitions identify the supported rating values for each system.کشور Rating system ویژگی ایالات متحده Motion Picture Association of America (MPAA) contentDetails.contentRating.mpaaRating
ایالات متحده رهنمودهای تلویزیونی والدین contentDetails.contentRating.tvpgRating
استرالیا Australian Classification Board (ACB) contentDetails.contentRating.acbRating
برزیل Departamento de Justiça, Classificação, Qualificação e Títulos contentDetails.contentRating.djctqRating
کانادا Canadian Home Video Rating System (CHVRS) contentDetails.contentRating.chvrsRating
فرانسه Centre national du cinéma et de l'image animée (French Ministry of Culture) contentDetails.contentRating.fmocRating
آلمان Freiwillige Selbstkontrolle der Filmwirtschaft (FSK) contentDetails.contentRating.fskRating
بریتانیای کبیر British Board of Film Classification (BBFC) contentDetails.contentRating.bbfcRating
هند Central Board of Film Certification (CBFC) contentDetails.contentRating.cbfcRating
ژاپن 映倫管理委員会 (EIRIN) contentDetails.contentRating.eirinRating
کشور کره 영상물등급위원회 (KMRB) contentDetails.contentRating.kmrbRating
مکزیک General Directorate of Radio, Television and Cinematography (RTC) contentDetails.contentRating.rtcRating
نیوزلند دفتر رده بندی فیلم و ادبیات contentDetails.contentRating.oflcRating
روسیه National Film Registry of the Russian Federation contentDetails.contentRating.russiaRating
اسپانیا موسسه سمعی و بصری سینما و هنرهای هنری (ICAA) contentDetails.contentRating.icaaRating
The
playlistItems.update
method's documentation has been updated to reflect the fact that thesnippet.resourceId
property must be specified in the resource sent as the request body.The
search.list
method now supports the following functionality:The new
forMine
parameter restricts a search to only retrieve the authenticated user's videos.The
order
parameter now supports the ability to sort results alphabetically by title (order=title
) or by video count in descending order (order=videoCount
).The new
safeSearch
parameter indicates whether search results should include restricted content.
The
videos.insert
method supports several new errors, which are listed in the table below:نوع خطا جزئیات خطا شرح badRequest
invalidCategoryId
The snippet.categoryId
property specifies an invalid category ID. Use thevideoCategories.list
method to retrieve supported categories.badRequest
invalidRecordingDetails
The metadata specifies invalid recording details.
badRequest
invalidVideoGameRating
The request metadata specifies an invalid video game rating. badRequest
invalidVideoMetadata
The request metadata is invalid. The
onBehalfOfContentOwner
parameter has been removed from the list of supported parameters for thevideos.update
andvideos.delete
methods.
12 مارس 2013
This update contains the following changes:
The
channelTitle
property has been added to thesnippet
for the following resources:The
search.list
method supports the following new parameters:The
channelType
parameter lets you restrict a search for channels to retrieve all channels or to retrieve only shows.The
videoType
parameter lets you restrict a search for videos to retrieve all videos or to retrieve only movies or only episodes of shows.
The definition of the
video
resource'srecordingDetails
part has been updated to note that the object will only be returned for a video if the video's geolocation data or recording time has been set.The
playlistItems.update
method now returns aninvalidSnippet
error, which is returned if the API request does not specify a valid snippet.Several API methods support new parameters that are intended exclusively for YouTube content partners. YouTube content partners include movie and television studios, record labels, and other content creators that make their content available on YouTube.
پارامتر
onBehalfOfContentOwner
نشان می دهد که اعتبارنامه مجوز درخواست، کاربر YouTube CMS را شناسایی می کند که از طرف مالک محتوا مشخص شده در مقدار پارامتر عمل می کند. The CMS account that the user authenticates with must be linked to the specified YouTube content owner.This parameter is intended for content partners that own and manage many different YouTube channels. The parameter enables those partners to authenticate once and get access to all of their video and channel data, without having to provide authentication credentials for each individual channel.
The
channels.list
,search.list
,videos.delete
,videos.list
, andvideos.update
methods all support this parameter.The
managedByMe
parameter, which is supported by thechannels.list
method, instructs the API to return all channels owned by the content owner that theonBehalfOfContentOwner
parameter specifies.The
forContentOwner
parameter, which is supported by thesearch.list
method, instructs the API to restrict search results to only include resources that are owned by the content owner that theonBehalfOfContentOwner
parameter specifies.
25 فوریه 2013
This update contains the following changes:
The API supports several new parts and properties for
video
resources:The new
fileDetails
,processingDetails
, andsuggestions
parts provide information to video owners about their uploaded videos. This data is very useful in applications that enable video uploads and includes the following:- processing status and progress
- errors or other issues encountered while processing a video
- availability of thumbnail images
- suggestions for improving video or metadata quality
- details about the original file uploaded to YouTube
All of these parts can only be retrieved by the video owner. The list below briefly describes the new parts, and the
video
resource documentation defines all of the properties that each part contains.The
fileDetails
object contains information about the video file that was uploaded to YouTube, including the file's resolution, duration, audio and video codecs, stream bitrates, and more.The
processingProgress
object contains information about YouTube's progress in processing the uploaded video file. The object's properties identify the current processing status and estimate the time remaining until YouTube finishes processing the video. This part also indicates whether different types of data or content, such as file details or thumbnail images, are available for the video.This object is designed to be polled so that the video uploader can track the progress that YouTube has made in processing the uploaded video file.
The
suggestions
object contains suggestions that identify opportunities to improve the video quality or the metadata for the uploaded video.
The
contentDetails
part contains four new properties. These properties can be retrieved with unauthenticated requests.-
dimension
– Indicates whether the video is available in 2D or 3D. -
definition
– Indicates whether the video is available in standard or high definition. -
caption
– Indicates whether captions are available for the video. -
licensedContent
– Indicates whether the video contains content that has been claimed by a YouTube content partner.
-
The
status
part contains two new properties. Video owners can set values for both properties when inserting or updating a video. These properties can also be retrieved with unauthenticated requests.-
embeddable
– Indicates whether the video can be embedded on another website. -
license
– Specifies the video's license. Valid values arecreativeCommon
andyoutube
.
-
The definition of the
part
parameter has been updated for thevideos.list
,videos.insert
, andvideos.update
methods to list the newly added parts described above as well as therecordingDetails
part, which had been inadvertently omitted.The
channel
resource's newcontentDetails.googlePlusUserId
property specifies the Google+ profile ID associated with the channel. This value can be used to generate a link to the Google+ profile.Each thumbnail image object now specifies the image's width and height. Thumbnail images are currently returned in
activity
,channel
,playlist
,playlistItem
,search result
,subscription
, andvideo
resources.The
playlistItems.list
now supports thevideoId
parameter, which can be used in conjunction with theplaylistId
parameter to only retrieve the playlist item that represents the specified video.The API returns a
notFound
error if the video that the parameter identifies cannot be found in the playlist.The error documentation describes a new
forbidden
error, which indicates that a request is not properly authorized for the requested action.The
channel
resource'ssnippet.channelId
property has been removed. The resource'sid
property provides the same value.
30 ژانویه 2013
This update contains the following changes:
The new error page lists errors that the API can return. The page includes general errors, which might occur for multiple different API methods, as well as method-specific errors.
16 ژانویه 2013
This update contains the following changes:
Code samples are now available for the methods and languages shown in the list below:
-
activities.insert
– Java -
playlistItems.insert
– Python -
playlistItems.list
– Java, JavaScript, PHP, Python, Ruby -
playlists.insert
– Java, JavaScript, Python -
search.list
– Java, JavaScript, Python, Ruby -
videos.insert
– Java
-
An
activity
resource can now report achannelItem
action, which occurs when YouTube adds a video to an automatically generated YouTube channel . (YouTube algorithmically identifies topics that have a significant presence on the YouTube website and automatically generates channels for those topics.)The following
search.list
parameters have been updated:- The
q
parameter is no longer designated as a filter, which means .... - The
relatedToVideo
parameter has been renamedrelatedToVideoId
. - The
published
parameter has been replaced with two new parameters,publishedAfter
andpublishedBefore
, which are described below.
- The
The
search.list
method supports the following new parameters:نام پارامتر ارزش شرح channelId
string
Return resources created by the specified channel. publishedAfter
datetime
Return resources created after the specified time. publishedBefore
datetime
Return resources created before the specified time. regionCode
string
Return resources for the specified country. videoCategoryId
string
Filter video search results to only include videos associated with the specified video category . videoEmbeddable
string
Filter video search results to only include videos that can be played in an embedded player on a web page. Set the parameter value to true
to only retrieve embeddable videos.videoSyndicated
string
Filter video search results to only include videos that can be played outside of YouTube.com. Set the parameter value to true
to only retrieve syndicated videos.Several API resources support new properties. The table below identifies the resources and their new properties:
منبع نام ملک ارزش شرح activity
contentDetails.playlistItem.playlistItemId
string
The playlist item ID that YouTube assigned to uniquely identify the item in the playlist. activity
contentDetails.channelItem
object
An object that contains information about a resource that was added to a channel. This property is only present if the snippet.type
ischannelItem
.activity
contentDetails.channelItem.resourceId
object
An object that identifies the resource that was added to the channel. Like other resourceId
properties, it contains akind
property that specifies the resource type, such as video or playlist. It also contains exactly one of several properties –videoId
,playlistId
, etc. – that specifies the ID that uniquely identifies that resource.channel
status
object
This object encapsulates information about the channel's privacy status. channel
status.privacyStatus
string
The channel's privacy status. Valid values are private
andpublic
.playlist
contentDetails
object
This object contains metadata about the playlist's content. playlist
contentDetails.itemCount
unsigned integer
The number of videos in the playlist. playlist
player
object
This object contains information that you would use to play the playlist in an embedded player. playlist
player.embedHtml
string
An <iframe>
tag that embeds a video player that plays the playlist.video
recordingDetails
object
This object encapsulates information that identifies or describes the place and time that the video was recorded. video
recordingDetails.location
object
This object contains geolocation information associated with the video. video
recordingDetails.location.latitude
double
Latitude in degrees. video
recordingDetails.location.longitude
double
Longitude in degrees. video
recordingDetails.location.elevation
double
Altitude above the Earth, in meters. video
recordingDetails.locationDescription
string
A text description of the location where the video was recorded. video
recordingDetails.recordingDate
datetime
The date and time when the video was recorded. The value is specified in ISO 8601 ( YYYY-MM-DDThh:mm:ss.sZ
) format.The documentation for several API methods now identifies properties that must be specified in the request body or that are updated based on values in the request body. The table below lists those methods as well as the required or modifiable properties.
Note: Documentation for other methods may already list required and modifiable properties.
روش خواص activities.insert
Required properties: -
snippet.description
-
snippet.description
-
contentDetails.bulletin.resourceId
playlists.update
Required properties: -
id
playlistItems.update
Required properties: -
id
videos.update
Required properties: -
id
-
The API no longer reports a
playlistAlreadyExists
error if you try to create or update a playlist that would have the same title as a playlist that already exists in the same channel.Several API methods support new error types. The table below identifies the method and the newly supported errors:
روش نوع خطا جزئیات خطا شرح guideCategories.list
notFound
notFound
The guide category identified by the id
parameter cannot be found. Use the guideCategories.list method to retrieve a list of valid values.playlistItems.delete
forbidden
playlistItemsNotAccessible
The request is not properly authorized to delete the specified playlist item. videoCategories.list
notFound
videoCategoryNotFound
The video category identified by the id
parameter cannot be found. Use the videoCategories.list method to retrieve a list of valid values.