youtube-eng.blogspot

Introducing Google Account support and YouTube API v2.1

Friday, October 7, 2011

Update (December 2011): The YouTube API now supports associating an unlinked Google Account with a YouTube channel as well as providing username suggestions.
We are pleased to announce that we have also started to give Google Account holders who don’t already have YouTube channels access to certain YouTube features on YouTube.com and in the YouTube API. We call these unlinked Google Accounts since they haven’t already been linked to a YouTube channel. For example, a user with a Gmail account or an Android device is certain to have a Google Account but may not have already linked that account to a YouTube channel.
What this means for your application is that with a few relatively simple changes, you should be able to allow authenticated access for users who have unlinked Google Accounts. Thus, those users will be able to log in to YouTube without having to create a YouTube username.
In a moment, we’ll dive into the details of how to use the API with unlinked Google Accounts and also offer a few user experience recommendations for your YouTube API application. First, though, a quick note about the new minor YouTube API revision that we’re introducing.
Say "Hello!" to YouTube API v2.1
When designing this feature, we decided to take a conservative approach toward backward compatibility. The set of write operations supported for Google Accounts is currently a subset of API operations available to YouTube account holders. Rather than expose existing applications to accounts with potentially restricted functionality, we’re explicitly requiring that an application prepared to handle unlinked Google Accounts tells us so by using the API version 2.1, a new, minor version of the API. Our documentation explains that you can specify an API version by appending v=2.1 to the API request URI or by using the GData-Version: 2.1 request header.
HTTP response codes for authenticated operations
API v2.0 supports all authenticated operations for users with YouTube accounts, which could also be called linked Google Accounts, but doesn’t support any authenticated operations for unlinked Google Accounts. If the authentication token for a v2.0 API request identifies an unlinked Google Account, the API will return a 401 NoLinkedYouTubeAccount error.
In API v2.1, however, a number of operations that require authentication are supported for users with unlinked Google Accounts, and the API will return a 200 response code for those operations. For operations that aren’t supported for unlinked Google Accounts in v2.1, the API will return an HTTP 403 Forbidden error with a youtube_signup_required error code.
The table below shows how API v2.1 changes response codes when different types of users try to execute operations that require authentication: table { border-spacing: 0; width:80%; } table tr td { border: 1px solid black; } table .cell-left { border-left: 0; border-top: 0; } table .cell-top { text-align: center; background-color: #95B9C7; color: black; } table .cell-hdr { text-align: center; border-left: 0; border-top: 0; } table .cell-data { text-align: center; font-family: "Courier New", Courier, monospace } table .cell-data-top { text-align: center; background-color: #95B9C7; color: black; } table .cell-row-hdr { text-align: center; background-color: #95B9C7; color: black; }

API v2

API v2.1

YouTube Account

200 OK

Unlinked Google Account

401 NoLinkedYouTubeAccount

200 OK or 403 Forbidden youtube_signup_required

Handling the youtube_signup_required error
We do not recommend that you try to modify your application to provide a different experience for users with YouTube accounts than for unlinked Google Accounts. That approach would require you to constantly update your application as YouTube expands the list of features that we support for unlinked Google Accounts.Instead, we recommend that you prepare your application to gracefully handle the youtube_signup_required error, preferably by associating the unlinked Google Account with a YouTube channel using the API, or presenting an option for the user to navigate to https://www.youtube.com/create_channel. If you are building a mobile application, you can bypass a redirect by using https://m.youtube.com/create_channel instead. The API documentation lists the operations that are and are not currently supported for unlinked Google Account holders.
The XML below shows a sample youtube_signup_required error:<errors>
  <error>
    <domain>yt:service</domain>
    <code>youtube_signup_required</code>
  </error>
</errors>
User profiles for unlinked Google Account holders
A user profile entry for a user with an unlinked Google Account differs from a user profile entry for a user with a YouTube account in two ways:

An entry for an unlinked Google Account holder contains a <yt:incomplete> tag. (This tag is not present if the user already has a YouTube channel.) It is useful if you choose to disregard our advice about the youtube_signup_required error and modify your application to provide a different user experience for users with unlinked Google Accounts.

An entry for an unlinked Google Account holder contains only a few tags as those users can not customize their profile data without first creating a YouTube channel. The <entry> tag definition lists the different tags that may appear in a profile entry depending on whether the user has a YouTube account or an unlinked Google Account.

Displaying an email address for unlinked Google Account holders

In addition to handling the youtube_signup_required error, your application should also be prepared to display an email address for users with unlinked Google Accounts.

In Closing

If you have reached this point in the blog post, thanks for being a dedicated reader. We recognize that unlinked Google Accounts do introduce a certain level of complexity, but, at the same time, they can also open your application to a much larger audience of users who use Google services but haven’t created YouTube channels yet.

We also want to note that v2.1 does not deprecate v2.0 since it is a minor revision. Going forward, new features unrelated to unlinked Google Accounts will be added to both v2.0 and v2.1 but not to the (deprecated) v1.0 of the API.

Version 2.1 of the API is now available for testing on stage.gdata.youtube.com, and will be released to production in mid-October.

Cheers,

—Jarek Wilkiewicz, YouTube API Team

Support for the Watch Later List

Wednesday, October 5, 2011

YouTube’s Watch Later list is the perfect way to keep track of interesting videos you come across but don’t have time to watch at the moment. Since rolling out that feature on the YouTube website and the embedded players, developers have been asking for ways to interact with the Watch Later list via the YouTube Data API. We’re happy to announce that this is now possible.

As explained in our documentation, the YouTube Data API treats the Watch Later list like a playlist, and the normal playlist operations (additions, retrievals, modifications) can all be performed on the Watch Later list. While every YouTube user has their own Watch Later list, it’s important to keep in mind that by default it’s a private playlist, so it will not normally be accessible unless you’re making an authenticated request as the list’s owner.

If you have any questions about using the Data API to work with the Watch Later list, please let us know in our developer forum.

Cheers,
—Jeff Posnick, YouTube API Team

YouTube API and the News

Wednesday, September 28, 2011

If you love to follow the news as much as you love to code, then Hacks/Hackers, an international organization that sits at the nexus of journalism and technology, is for you. Its mission is to create a network of journalists (“hacks”) and technologists (“hackers”) to rethink the future of news and information. Recently, YouTube and LinkTV hosted a Hacks/Hackers meetup at Google’s San Francisco office. Together with four developer partners, we demoed web applications used by reporters and built using the YouTube API. The presentation started with a YouTube API overview, followed by demos of the following:

YouTube Direct is an open source, user-generated content video submission and moderation platform.

Storyful was founded by journalists to discover the smartest conversations about world events and raise up the authentic voices on the big stories.

Storify lets users make stories using social media. With Storify you can drag-and-drop tweets, YouTube videos, Flickr images, Facebook updates, etc. and add your own narrative to tell a story.

Shortform is a new social entertainment medium, delivering continuous channels containing the best videos from anywhere on the web, curated by our community of video DJs (VJs).

GoAnimate was founded to provide an outlet for everyone's creative ideas. In just 10 minutes, you can make fun animated videos without having to draw.

Link TV recently launched Link News, an international news website that sifts through YouTube's library of news content to deliver breaking news and hidden stories to a wider audience.

We would like to share the video recording of the event with you so that you can learn more. If you want to discover more about Hacks/Hackers, you can find the list of local chapters here. Cheers,
—Jarek Wilkiewicz, YouTube API Team

Getting 3D Content on YouTube

Thursday, September 8, 2011

Over the last few months, we've been steadily rolling out features for YouTube 3D. Early this year, we announced support for the LG Optimus 3D and NVIDIA 3D Vision, and this month we announced support for Samsung 3D TVs. And we'll keep rolling out to more platforms to make it easier for everyone to get access to user-generated 3D content.
Many readers have been asking how to upload content. 3D uploads to YouTube will work across all supported devices, from red/blue glasses to the latest 3D televisions.
There are two ways to upload content to YouTube in 3D. If you're just uploading one or two videos, upload content in any supported format and then edit the video settings to tell us that it's 3D. From a video's watch page, select "edit info", then "3D Video". This will only work on videos you've uploaded yourself.
If you're using the API to upload 3D videos, you'll want to format your video in a certain way. YouTube supports automatic detection of 3D content with certain file formats. If you upload with a format that supports automatic detection, we'll automatically set the correct settings so that your video shows up automatically in 3D and shows up properly on phones, TVs, and PCs.
In both cases, YouTube requires that content be uploaded in Side by Side L/R with each frame squashed 50% and preferably with a 16:9 aspect ratio. The following formats are automatically detected when uploaded:

WebM with the StereoMode setting set to STEREOMODE_TYPE_LEFT_RIGHT. Note that other modes, including alternate track, are not supported.

H264 AVC with Supplementary Enhancement Information, Frame Packing Arrangement set. If you are using x264, the argument --frame-packing=3 will set this correctly. In Handbrake you can set this in "x264 Advanced Option String".

We're excited to see what you'll show us! Here's an idea from a favorite webcomic of ours.
Cheers, —Jonathan Huang, YouTube 3D Product Manager
P.S.—We recently worked with some folks to help them get 3D Mars footage from 1979 restored from the Viking landers. Check it out!

Auth Tokens & Unlinked YouTube Accounts

Thursday, August 25, 2011

Dedicated readers of this blog will remember our post from a few months back entitled “ClientLogin #FAIL”. In it, we laid out a number of scenarios in which attempts to use ClientLogin authentication would result in an error (and urged developers to move off of ClientLogin in general). The first failure scenario involved users whose YouTube account is not linked to a Google Account. Fortunately, the number of YouTube accounts in that unlinked state has decreased greatly over the past few months, so failures of that sort with ClientLogin are not as common now.

There’s another related failure scenario that we want to bring to everyone’s attention, this time involving both AuthSub and OAuth (collectively referred to here as “auth”) tokens. Starting on Wednesday, August 31, if your code attempts to use an auth token that was generated for an unlinked YouTube account, your request will fail with an HTTP 401 response code indicating that the token is invalid.

It’s important to note that what determines when the token is invalid is whether the YouTube account was linked at the time the initial auth token was generated. For example, if your code generated the auth token for an unlinked YouTube account on March 1, and then the user linked their YouTube and Google accounts on March 2, the auth token will still be considered invalid.

On March 31 we started to enforce the need to have a linked Google Account as part of the AuthSub and OAuth login flow, meaning that it was impossible to generate an auth token for an unlinked YouTube account after that date. So this change can only affect auth tokens generated before March 31 of this year.

While auth tokens normally don’t expire, users have the option of manually revoking them. If your code uses a revoked token, you’ll also get back an HTTP 401 response. If you’re using a client library, it will generate an exception to indicate the failure. It’s a best practice to make sure that your code handles invalid token errors by asking your user to go through the AuthSub or OAuth login flow again, storing the new token value and discarding the old one in the process.

If you have any questions about YouTube API authentication, please let us know in our developer forum.

Cheers,
—Jeff Posnick, YouTube API Team

The New CodeIgniter PHP Client Library

Tuesday, August 23, 2011

While the YouTube Data API’s RESTful nature means that talking to YouTube is as easy as making an HTTP request, using a client library is a great way to improve your YouTube Data API productivity and write code using your preferred language’s native features. PHP developers using the Zend framework have had access to a client library for a while now, and that library continues to be a supported way of using the YouTube API. But if you’re a PHP developer using the CodeIgniter framework, you’ll be happy to hear that there’s now an alternative client library available just for you.

A third-party developer, Jim Saunders, has developed a YouTube Data API library specifically for the CodeIgniter framework. You download the library on GitHub, and read the article he’s written to find out how to get started with some sample code.

While Jim wrote and still maintains the library, please feel free to ask any questions about the YouTube API in general in our developer forum!

Cheers,
—Jeff Posnick, YouTube API Team

Coming Soon: The Dark Player for Embeds

Friday, August 5, 2011

modestbrandingplayer parameters<iframe width="560" height="349"
src="http://www.youtube.com/embed/9h1swNWgP8Q?theme=light&color=red"
frameborder="0" allowfullscreen></iframe>

Engineering and Developers Blog