An Update to our Deprecation Policy

As you might have seen announced on our Google Developers blog, the deprecation policies associated with many of Google’s APIs are changing. We want to highlight the specific way this affects YouTube API developers.

As of today, our YouTube API deprecation policy states:

Google will announce if we intend to discontinue or make backwards incompatible changes to this API or Service. We will use commercially reasonable efforts to continue to operate the YouTube API without these changes until the later of: (i) one year after the announcement or (ii) April 20, 2015, unless (as Google determines in its reasonable good faith judgment):

• required by law or third party relationship (including if there is a change in applicable law or relationship), or
• doing so could create a security risk or substantial economic or material technical burden.

This Deprecation Policy doesn't apply to versions, features, and functionality labeled as "experimental."

Please note that while the deprecation policy listed above is current as of the date of this blog post, the definitive version of the policy can always be found in our Terms of Service.

Cheers,
—Jeff Posnick, YouTube API Team

Upgrading Old Embed Codes

We’d like to let the community know about an upcoming change that will affect some developers using Flash-only players in their webpages or applications. Previously, a URL like http://www.youtube.com/v/VIDEO_ID would default to the ActionScript 2 version of the Flash player, and it was necessary to explicitly add in the version=3 URL parameter to request the newer, ActionScript 3-based player. Starting on Wednesday, May 2, we will be changing the default behavior so that the ActionScript 3 player will be loaded in those scenarios.

This change to the default version affects both the Embedded and Chromeless Flash players. Developers who are using the newer <iframe> embedded player will not see any change, as that already defaults to the ActionScript 3 player when Flash playback is needed.

If for some reason you explicitly need the ActionScript 2 version of the player, perhaps because you’re hosting it from within a parent Flash container that was written in ActionScript 2, then you should change your code to explicitly add in the version=2 URL parameter to the player URL. Most developers will not need to do this, though, and they’ll automatically get the benefits of the modern ActionScript 3 playback experience without having to change their code.

As we’ve previously announced, the ActionScript 2 players are all officially deprecated, and have been for several years now. Our plan is to shut them down completely starting in October of this year, so while it is still possible to explicitly request them with version=2 if they’re needed, our recommendation is that you do not continue to rely on the ActionScript 2 player in your code.

Cheers,
—Jeff Posnick, YouTube API Team

New Player Options for Lists of Videos

Most developers know that the YouTube embedded player can display a single video, but did you know that it can be used to display a list of videos as well? There have been a number of recent enhancements around list playback functionality, and if you’re not already taking advantage of those new features, we wanted to let you know what you’re missing out on.

The first change of note is the syntax for embedding the player in an HTML document. As for single-video playback, you can use the <iframe> embed code to load a list of videos, and the IFrame embed supports HTML5 <video> playback in environments where Flash is not available.

Another exciting change relates to the lists of videos that you can load. The player is no longer limited to just displaying videos from an actual YouTube playlist. You can also load a user's uploaded videos, a user's favorite videos, or videos matching a specific search term. In the embed URL, the listType and list parameters control the list of videos that is loaded. The listType value can be either playlist (the default), user_uploads, or search. Depending on the listType value, the list parameter value should be set to the desired playlist id, YouTube user ID, or search term. For example, the following embed code displays the most recent videos uploaded in the “GoogleDevelopers” YouTube channel:

<iframe width="560" height="315" src="http://www.youtube.com/embed/?listType=user_uploads&list=GoogleDevelopers" frameborder="0" allowfullscreen></iframe>

The corresponding embedded player is shown below:



Finally, for developers who want more control over their player than what a simple embed code offers, a full YouTube JavaScript API is available for use. There are methods for loading lists, moving to the next/previous video in a list, and controlling whether playback is shuffled or looped. To give you an idea of how you can use this new JavaScript Player API functionality, we’ve put together a sample page that you can experiment with and use as inspiration when developing your own code.

Cheers,
—Jeff Posnick, YouTube API Team

Minimum embeds: 200px x 200px

If you're a careful reader of the YouTube API Terms of Service as well as the YouTube Player documentation, you may have noticed that while embedded players smaller than the minimum size might not support all player features, we haven’t defined what that size is.

As a part of our spring cleaning, we've tidied up our documentation to specify a minimum player size, which is 200px by 200px.

This change will take effect beginning late April 2012, so please check your application to avoid surprises. If you have any questions or comments about this, or any other YouTube API feature, please let us know on the API forum.

Cheers,

-Jarek Wilkiewicz, YouTube API Team

Keeping Things Fresh

Pop quiz: what’s the difference between the following feed URLs?

1. https://gdata.youtube.com/feeds/api/users/googledevelopers/uploads?v=2
2. https://gdata.youtube.com/feeds/api/users/googledevelopers/uploads?v=2&orderby=published
3. https://gdata.youtube.com/feeds/api/videos?v=2&author=googledevelopers&orderby=published

All three will return a list of videos uploaded in the GoogleDevelopers YouTube channel, with the most recent uploads listed first. However, only the first URL will return the freshest results available — the second or third feeds could both be missing videos that were uploaded within the past few hours. In addition, even if the videos are listed in the second and third feeds, the metadata returned for those videos might not reflect any recent updates.

The reason for this, as explained in our documentation, is that some requests go against our search index, which has cached data, while other requests retrieve data directly from our backend databases, which always contain the most up-to-date data. To determine whether a request will query the search index or the backend database, you can use the following rules of thumb:

• If your request only includes the max-results and/or start-index query parameters, then it should go against the backend database and the results will be fresh. A few other parameters that change the way the feed is formatted, like prettyprint, callback, or alt, can also be used without triggering the search index. Although it does filter results out of the feed, the fields parameter can also be used while still going against the backend database, because the filtering is performed server-side after the data has been retrieved.

• If your request contains other parameters, there’s a good chance it will end up against the search index. Some common parameters that will always trigger a search are q and orderby.

Going against the search index isn’t inherently a bad thing. Using the search index is an incredibly efficient way of returning all the videos that match an arbitrary keyword, or ordering a feed of videos so that they’re sorted by view count. The important thing to realize is that the search index doesn’t need to be used for tasks that the backend database can handle, and you’ll get fresher results from the backend database.

Until now we’ve been focusing on retrieving a feed of videos uploaded in a specific account, but these same principles apply to looking up a single video with a given ID as well. Using the information above, can you determine which of these URLs will request a video entry from the backend database, and which will go against the search index?

1. https://gdata.youtube.com/feeds/api/videos/sOEAD-gfJ_M?v=2
2. http://gdata.youtube.com/feeds/api/videos?q=sOEAD-gfJ_M?v=2

As you’ve probably figured out, the first URL retrieves the entry for video ID sOEAD-gfJ_M directly from the backend database, while the second URL searches for all entries with metadata containing sOEAD-gfJ_M and then returns the one matching result. The results look similar, but only the first URL will give you the complete, up-to-date video metadata. As such, we recommend always using that syntax when retrieving the entry for a video whose ID you know.

Cheers,
-Jeff Posnick, YouTube API Team

YouTube, Google+, the API, and You

Update (April 2012): The last paragraph was changed to reflect the distinct yt:display and display attribute names, depending on whether the parent element is media:credit or yt:username.


By now, you may have read about the recent launch of connecting a Google+ profile with a new YouTube channel and questioned whether the change will affect YouTube Data API responses and, consequently, your application. The API does have a couple of changes that affect the way account names are returned, and these changes are designed to be backward compatible with applications that follow the best practices defined in our compatibility guidelines.

With that in mind, this post explains how to ensure that user names function properly in your application.

• If your application uses authentication and refers to feeds belonging to the currently authenticated user, always use the string default as the username in the feed URL. For example, the URL https://gdata.youtube.com/feeds/api/users/default?v=2 retrieves the currently authenticated user's profile no matter what type of account she has, and https://uploads.gdata.youtube.com/resumable/feeds/api/users/default/uploads?v=2 is always the correct URL to POST to when performing a resumable upload into the current user’s account.

• Avoid manually generating links to related feeds — instead, extract URLs for related feeds from <link> or <gd:feedLink> elements. For instance, the profile entry for a given account contains a <gd:feedLink> element with a rel attribute of http://gdata.youtube.com/schemas/2007#user.playlists, and that element's href attribute contains the URL for that account’s playlists.

• If you do need to manually generate a feed URL that is not for the default user, use the value in the <yt:username> element as the username in the feed URL. Other fields, like <author>, might contain a display name or a different identifier that is not appropriate for use in a feed URL.
  
  Note that for accounts that have connected a Google+ profile to a new YouTube channel and for Google Accounts without a linked YouTube account, the <yt:username> field will not be a traditional YouTube username. Instead, it will be a globally unique identifier that isn't intended for display in a user interface. A new field, <yt:userId>, will always contain this globally unique identifier regardless of the account type, and if you are writing new code to specifically deal with that identifier, we recommend reading it from <yt:userId>.

• Any existing code that relies on displaying the <yt:username> or <media:credit> value to users should instead switch to using a value taken from one of that element's attributes. On the <yt:username> element, the relevant attribute is called display. On the <media:credit> element, the corresponding attribute is called yt:display. The display or yt:display attribute value will always be a meaningful value suitable for display. For accounts connected to Google+, it will be set to the full public display name. For full YouTube accounts that aren’t connected to Google+, it will be set to the YouTube account name.

Cheers,
–Jeff Posnick, YouTube API Team

“Super Tuesday” Reporting, Powered by YouTube Direct

It’s Presidential election season in the United States, and YouTube’s News and Politics team is partnering with Storyful to highlight timely political videos from across the country. With that in mind, we’re excited to announce that citizen journalists can now submit videos documenting the election process by using the new Android and iOS mobile applications powered by YouTube Direct and released by Storyful. Both applications are based on the open source code examples we’ve released for Android and iOS, and submit videos to the instance of YouTube Direct that Storyful curates.

Tomorrow is “Super Tuesday,” when 10 states will hold their primary elections. If you live in one of the Super Tuesday states, we encourage you to install the Storyful Direct mobile application and shoot some footage documenting your political experience—a selection of videos will appear on YouTube and google.com/elections throughout the day. Even if you don’t live in a state that’s holding a primary tomorrow, the Storyful Direct apps can be used to document your experience during the runup to the Presidential election in November.

And if you’re a developer who isn’t yet familiar with the YouTube Direct platform, you can find all the information you need to get started with the web and mobile platforms at the Google Code project page.

Cheers,
—Jeffrey Posnick, YouTube API Team