YouTube Insight reports provide video owners with statistics about their viewership above and beyond public view count information. They’re a crucial tool when you want to find out more about the demographic or regional breakdown of your videos’ viewership, or what sites are embedding your videos. The YouTube API has provided a way for developers to retrieve YouTube Insight reports in a comma-separated value format for some time now, but there are some recent additions to the Insight retrieval process that we wanted to highlight.

First, we wanted to mention that the API allows developers to access Insight reports for an entire channel’s worth of videos, not just a single video. The appropriate base URL to use for downloading a channel report can be found when requesting the profile corresponding to the user who’s authenticated with the YouTube API, as described in our developer’s guide. The element looks something like:

<link rel='http://gdata.youtube.com/schemas/2007#insight.views' type='text/html' href='http://insight.youtube.com/video-analytics/csvreports?query=PlVJ88-zqkI&type=...'/>

It can be identified by the rel='http://gdata.youtube.com/schemas/2007#insight.views' attribute. As with single-video Insight retrieval, these reports are only available to the corresponding owner, so authenticating as the correct user is a must.

Current users of the Insight API know that we previously supported a rather restrictive set of custom date ranges for reports. We’re happy to announce that these restrictions have been relaxed—we now support date ranges that span 31 days (up from 28) and, more significantly, you can specify any arbitrary start date for your report going back to March 1, 2009. Please see our documentation for more information on formatting your custom date range parameters to take advantage of this historical data.

As always, we’re waiting to hear from you in our developer forum with any questions or comments.

Cheers,
—Jeffrey Posnick, YouTube API Team
Labels: ,

It was a pleasure meeting YouTube developers at the recent GDD, DevFest and GTUG sessions in São Paulo, Buenos Aires, Moscow, Prague, Paris and Warsaw. We would like to let you know that our around-the-world API tour continues and we hope to meet you at one of our upcoming YouTube API presentations. Here is the list of currently planned YouTube sessions:
We will also be speaking at local GTUGs; for the most up to date information please check the event schedule of a GTUG near you. As always, upcoming event information can be found on our Google Developer Events Calendar available at http://code.google.com/events/.

Cheers,
--Jarek Wilkiewicz, YouTube API Team



We’ve got some exciting additions to the list of supported search parameters for YouTube feeds that should make it easier to narrow down your search results to exactly the videos you’re looking for. Each of these search parameters has an accompanying element in a video entry’s metadata, which we’ll cover as well. Here's a quick rundown:
  • license - This parameter lets you filter search results based on whether they're Creative Commons licensed (license=cc) or use the standard YouTube license (license=youtube). The default behavior is to return videos regardless of their license in search results. The license for a given video entry is reflected in its <media:license> element.
  • hd - This one lets you request videos that have high-resolution versions available. If you specify hd (no value is needed), all the videos in your search results will be available for playback in at least 720p, and higher resolutions, like 1080p, might be available, too. If you leave the parameter out, then search results won't be filtered at all based on resolution. The <yt:hd> element corresponds to this search parameter.
  • duration - If you cater to an audience with a short attention span, then this parameter is for you. This parameter lets you filter search results based on video length. To find videos less than 4 minutes long, use duration=short. To find videos that are between 4 and 20 minutes long (inclusive), use duration=medium. Only videos that are longer than 20 minutes will be returning when requesting duration=long. The <yt:duration> element in a video entry provides a video’s exact runtime.
  • 3d - Finally, for those of you living in the future who want to find 3D content on YouTube, this aptly-named parameter is for you. Adding 3d (no value is needed) to your searches will ensure that all videos you get back are available for viewing in 3D. Videos that are available in 3D will have a <yt:threed> element in them, and that element will contain more detail about the nature of the 3D content in the given video.
Putting it all together, let’s say you want to use the API to find Creative Commons-licensed 3D YouTube videos that are available in resolutions of 720p and above and are longer than 20 minutes.The following request URL will return a feed of such videos:

https://gdata.youtube.com/feeds/api/videos?prettyprint=true&v=2&license=cc&hd&duration=long&3d

As always, if you have any questions or comments, please let us know in our developer forum.

Cheers,
—Jeff Posnick, YouTube API Team


Authenticated access to YouTube APIs lets your app offer many features that are unavailable to logged-out users. By authenticating user actions, your app can allow users to manage subscriptions, create playlists, and upload videos. Until recently, users could only perform any of these operations if they had YouTube accounts. (A YouTube account provides a user with a YouTube channel. ...
Update (December 2011): The YouTube API now supports associating an unlinked Google Account with a YouTube channel as well as providing username suggestions. 

Authenticated access to YouTube APIs lets your app offer many features that are unavailable to logged-out users. By authenticating user actions, your app can allow users to manage subscriptions, create playlists, and upload videos. Until recently, users could only perform any of these operations if they had YouTube accounts. (A YouTube account provides a user with a YouTube channel.)

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:


API v2 API v2.1
YouTube Account 200 OK 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



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
Labels: ,