YouTube

YouTube

Revision History

This page lists YouTube Data API (v3) changes and documentation updates. Subscribe to this changelog. Subscribe

March 4, 2014

This update contains the following changes:

December 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 the type parameter's value to video 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 the brandingSettings.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 channels.update method now supports updates to the invideoPromotion.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 the onBehalfOfContentOwner parameter.

  • The playlistItems.list and playlistItems.insert methods now support the onBehalfOfContentOwner 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 and contentDetails.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 new snippet.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:

October 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 are upcoming, active, and none.

    • The video resource's new snippet.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 new liveStreamingDetails property is an object that contains metadata about a live video broadcast. To retrieve this metadata, include liveStreamingDetails in the part parameter value's list of resource parts. The metadata includes the following new properties:

      To retrieve this metadata, include liveStreamingDetails in the part parameter value when calling the videos.list, videos.insert, or videos.update method.

    Note that two other features for identifying live broadcast content were released on October 1, 2013 – the search.list method's eventType parameter and the search result's snippet.liveBroadcastContent property.

  • The videos.insert method now supports the notifySubscribers 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 is True, 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 to False 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 the invideoPromotion.items[].customMessage and invideoPromotion.items[].websiteUrl properties. In addition, the list has been modified to identify the brandingSettings properties that are modifiable. These brandingSettings properties were already modifiable, so the documentation change does not reflect a change to the API's existing functionality.

  • The playlists.insert, playlists.update, and playlists.delete methods now support the onBehalfOfContentOwner parameter, which is already supported for several other methods.

  • The playlists.insert method now supports the onBehalfOfContentOwnerChannel parameter, which is already supported for several other methods.

  • The video resource's contentDetails.contentRating.tvpgRating property now supports a value of pg14, which corresponds to a TV-14 rating.

  • The definition of the snippet.liveBroadcastContent property, which is part of search results, has been corrected to reflect that live is a valid property value, but active is not a valid property value.

  • The video resource's contentDetails.contentRating.mibacRating property now supports two additional ratings:

    • mibacVap (VAP) – Children should be accompanied by an adult.
    • mibacVm12 (V.M.12) – Restricted to 12 and over.

  • The channel resource's new invideoPromotion.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 the onBehalfOfContentOwner parameter for more information.

October 1, 2013

This update contains the following changes:

  • The channel resource's new auditDetails 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 the https://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's invideoPromotion.items[].id.type property now supports a value of recentUpload, 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 are upcoming, active, and none.

    • For a video resource, a value of upcoming indicates that the video is a live broadcast that has not yet started, while a value of active indicates that the video is an ongoing live broadcast.
    • For a channel resource, a value of upcoming indicates that the channel has a scheduled broadcast that has not yet started, while a value of acive indicates that the channel has an ongoing live broadcast.

  • In the watermark resource, the targetChannelId 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, the targetChannelId property now specifies that value itself. Accordingly, the resource's targetChannelId.value property has been removed.

  • The thumbnails.set method now supports the onBehalfOfContentOwner parameter, which is already supported for several other methods.

  • The search.list method now supports the eventType 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:

    Error type Error detail Description
    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. The watermarks.unset method deletes a channel's watermark image.

    The error documentation describes the error messages that the API supports specifically for the watermarks.set and watermarks.unset methods.

  • The channel resource's new statistics.hiddenSubscriberCount property contains a boolean value that indicates whether the channel's number of subscribers is hidden. As such, the property's value is false if the channel's subscriber count is publicly visible.

  • The playlists.list method now supports the onBehalfOfContentOwner and onBehalfOfContentOwnerChannel parameters. Both parameters are already supported for several other methods.

  • The videos.list method now supports the regionCode parameter, which identifies the content region for which a chart should be retrieved. This parameter can only be used in conjunction with the chart 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:

    Error type Error detail Description
    forbidden insufficientPermissions The scopes associated with the OAuth 2.0 token provided for the request are insufficient for accessing the requested data.

August 15, 2013

This update contains the following changes:

  • The channel resource's invideoPromotion 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 to website and use the new invideoPromotion.items[].id.websiteUrl property to specify the URL. Also use the new invideoPromotion.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 to invideoPromotion.items[].timing. This object now enables you to customize the timing data for each promoted item in the invideoPromotion.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 the invideoPromotion.items[].timing object.

      • The new invideoPromotion.items[].timing.durationMs property specifies the amount of time, in milliseconds, that the promotion should display. The invideoPromotion.defaultTiming object also contains a durationMs field that specifies the default amount of time that the promoted item will display.

    • The invideoPromotion.items[].type and invideoPromotion.items[].videoId properties both have been moved into the invideoPromotion.items[].id object.

  • The subscriptions.list method now supports the onBehalfOfContentOwner and onBehalfOfContentOwnerChannel parameters. Both parameters are already supported for several other methods.

  • In the API response to a thumbnails.set request, the kind property value has changed from youtube#thumbnailListResponse to youtube#thumbnailSetResponse.

  • Code samples have been added for the following methods:

    Note that the Python example for the playlistItems.insert method was also removed since the functionality it demonstrated is now handled by the videos.rate method.

  • The error documentation describes the following new request context error, which could occur for any API method that supports the mine request parameter:

    Error type Error detail Description
    badRequest invalidMine The mine parameter cannot be used in requests where the authenticated user is a YouTube partner. You should either remove the mine parameter, authenticate as a YouTube user by removing the onBehalfOfContentOwner parameter, or act as one of the partner's channels by providing the onBehalfOfContentOwnerChannel parameter if available for the called method.

August 8, 2013

This update contains the following changes:

July 30, 2013

This update contains the following changes:

  • In a channelBanner resource, the value of the kind property's value has changed from youtube#channelBannerInsertResponse to youtube#channelBannerResource. This resource is returned in response to a channelBanners.insert request.

  • The channel resource's new brandingSettings.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 new contentDetails.activityType property identifies the types of activities that the subscriber will be notified about. Valid property values are all and uploads.

  • 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 is mostPopular. Note that the chart parameter is a filter parameter, which means it cannot be used in the same request as other filter parameters (id and myRating).
    • The videoCategoryId parameter identifies the video category for which the chart should be retrieved. This parameter can only be used in conjunction with the chart parameter. By default, charts are not restricted to a particular category.

  • The video resource's new topicDetails.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's recordingDetails.location.elevation property has been renamed to recordingDetails.location.altitude, and its fileDetails.recordingLocation.location.elevation property has been renamed to fileDetails.recordingLocation.location.altitude.

  • The video resource's contentDetails.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 new contentDetails.contentRating.ytRating property identifies age-restricted content. The property value will be ytAgeRestricted 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's mySubscribers parameter has been deprecated. Use the subscriptions.list method and its mySubscribers parameter to retrieve a list of subscribers to the authenticated user's channel.

  • The channelBanners.insert, channels.update, videos.getRating, and videos.rate methods all now support the onBehalfOfContentOwner 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 the channel resource's brandingSettings object and its child properties. The documentation also now lists the updated list of properties that you can set for the channel resource's invideoPromotion object.

  • The error documentation describes the following new errors:

    Error type Error detail Description
    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 the onBehalfOfContentOwnerChannel 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 the id property in the request body to ensure it is correct.

June 10, 2013

This update contains the following changes:

  • The channels.list method's new forUsername parameter enables you to retrieve information about a channel by specifying its YouTube username.

  • The activities.list method now supports the regionCode 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 the playlists.insert or playlists.update methods.

  • The onBehalfOfContentOwner parameter, which was previously supported for the channels.list and search.list methods, is now also supported for the videos.insert, videos.update, and videos.delete methods. Note that when this parameter is used in a call to the videos.insert method, the request must also specify a value for the new onBehalfOfContentOwnerChannel parameter, which identifies the channel to which the video will be added. The channel must be linked to the content owner that the onBehalfOfContentOwner 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:

    Error type Error detail Description
    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 the home parameter but is not properly authorized.

  • In the channels resource, the invideoPromotion.channelId property has been removed because the channel ID is already specified using the resource's id 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.

May 22, 2013

This update contains the following changes:

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.

May 10, 2013

This update contains the following changes:

May 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 the part parameter value in a channels.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 the invideoPromotion part of the channel resource and does not yet support updates to other parts of that resource.

May 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 new myRating parameter enables you to retrieve a list of videos that the authenticated user rated with a like or dislike rating.

    The myRating parameter and the id parameter are both now considered filter parameters, which means that an API request must specify exactly one of the parameters. (Previously, the id 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, the videos.list method has also been updated to support pagination. Note, however, that paging parameters are only supported for requests using the myRating parameter. (Paging parameters and information are not supported for requests that use the id parameter.)

    • The maxResults parameter specifies the maximum number of videos that the API can return in the result set, and the pageToken parameter identifies a specific page in the result set that you want to retrieve.

    • The youtube#videoListResponse resource, which is returned in response to a videos.list request, now contains the pageInfo object, which contains details like the total number of results and the number of results included in the current result set. The youtube#videoListResponse resource can also include nextPageToken and prevPageToken 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 to true to instruct YouTube to automatically enhance the video's lighting and color.
    • stabilize – Set this parameter value to true to instruct YouTube to adjust the video by removing shakiness resulting from camera motions.

  • The channelTitle property has been added to the snippet 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:

  • The subscriptions.list method's new mySubscribers 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 the channels.list method. That parameter will be deprecated.

  • In a video resource, the property value unspecified 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 is unexpectedParameter.

  • 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 a forbidden error, and the error reason is playlistContainsMaximumNumberOfVideos.

April 19, 2013

This update contains the following changes:

  • The new videos.rate method lets a user set a like or dislike 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 new brandingSettings 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 the status.privacyStatus property identifies the playlist item's privacy status.

  • The video resource contains the following new properties:

  • The playlistItems.update method's documentation has been updated to reflect the fact that the snippet.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:

    Error type Error detail Description
    badRequest invalidCategoryId The snippet.categoryId property specifies an invalid category ID. Use the videoCategories.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 the videos.update and videos.delete methods.

March 12, 2013

This update contains the following changes:

  • The channelTitle property has been added to the snippet for the following resources:

    • activity – The property specifies the name of the channel responsible for the activity.
    • search – The property specifies the name of the channel associated with the resource that the search result identifies.
    • video – The property specifies the name of the channel that uploaded the video.

  • 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's recordingDetails 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 an invalidSnippet 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.

    • The onBehalfOfContentOwner 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.

      The channels.list, search.list, videos.delete, videos.list, and videos.update methods all support this parameter.

    • The managedByMe parameter, which is supported by the channels.list method, instructs the API to return all channels owned by the content owner that the onBehalfOfContentOwner parameter specifies.

    • The forContentOwner parameter, which is supported by the search.list method, instructs the API to restrict search results to only include resources that are owned by the content owner that the onBehalfOfContentOwner parameter specifies.

February 25, 2013

This update contains the following changes:

  • The API supports several new parts and properties for video resources:

    • The new fileDetails, processingDetails, and suggestions 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 are creativeCommon and youtube.

  • The definition of the part parameter has been updated for the videos.list, videos.insert, and videos.update methods to list the newly added parts described above as well as the recordingDetails part, which had been inadvertently omitted.

  • The channel resource's new contentDetails.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, and video resources.

  • The playlistItems.list now supports the videoId parameter, which can be used in conjunction with the playlistId 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's snippet.channelId property has been removed. The resource's id property provides the same value.

January 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.

January 16, 2013

This update contains the following changes:

  • Code samples are now available for the methods and languages shown in the list below:

  • An activity resource can now report a channelItem 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 renamed relatedToVideoId.
    • The published parameter has been replaced with two new parameters, publishedAfter and publishedBefore, which are described below.

  • The search.list method supports the following new parameters:

    Parameter name Value Description
    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:

    Resource Property name Value Description
    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 is channelItem.
    activity contentDetails.channelItem.resourceId object An object that identifies the resource that was added to the channel. Like other resourceId properties, it contains a kind 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 and public.
    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.

    Method Properties
    activities.insert Required properties:
    • snippet.description
    Modifiable properties:
    • 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:

    Method Error type Error detail Description
    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.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.